Leaving ES to stay open source? Data migration all planned? Now learn how to migrate your Elasticsearch client to OpenSearch® in Python, Java and Node.js.
Laysa Uchoa
|RSS FeedDeveloper Advocate
Subscribe for the latest news and insights on open source, Aiven offerings, and more.
Note On 2022-08-23, Aiven will complete its migration away from Elasticsearch, and migration between Aiven services will no longer be necessary. See Aiven finishes the transition away from Elasticsearch: technical details for more information.
We are replacing Elasticsearch with the open source fork of the project, OpenSearch. In this article, we will show you how to upgrade the client code in your application to make the switch.
When we think about database migration, we normally think about migrating the data itself. However, you have to consider migrating your client, and especially which version is being used.
You can check our related articles about Aiven for OpenSearch® and the Elasticsearch to OpenSearch migration:
In this article, we will briefly explain the database migration process, and how to perform your client migration.
In terms of database migration, Aiven's client can perform the upgrade without any downtime. You can find all the steps needed to perform your migration on Aiven's devportal. Note that upgrading from Elasticsearch to OpenSearch will also upgrade Kibana to OpenSearch Dashboards. If you are already using Aiven, we recommend you do the upgrade soon as the end of life is due to be on March 23. After this date, Aiven's services related to Elasticsearch will be upgraded automatically to OpenSearch.
Migrating a native Elasticsearch client to OpenSearch requires changes in the client code so that you can continue to interact with your cluster. Are you curious how this can be done? Here we will go over client migration in three languages: Python, Java, and JavaScript (Node.js).
Before diving into the code, there is one thing you should keep in mind. According to OpenSearch docs, Elasticsearch clients for v7.10.2 should work in terms of compatibility with OpenSearch client v1. However, the latest version of Elasticsearch clients may contain checks that can break compatibility. Here are the recommendations regarding the Elasticsearch client version that you should have to migrate to OpenSearch v1.0.0.
| Client | Recommended version |
|---|---|
| Java low-level REST client | 7.13.4 |
| Java high-level REST client | 7.13.4 |
| Python | 7.13.4 |
| NodeJS | 7.13.0 |
Check the full table on the OpenSearch page.
As you can see, it is recommended that first, you upgrade or downgrade your Elasticsearch to match v7.13.4 or v7.13.0, check if is still running correctly, then migrate to the compatible OpenSearch version v1.0.0. Finally, you can upgrade to the latest OpenSearch version that contains additional features and bug fixes. Doing this will help you correct API incompatibilities that may appear during your client migration process.
So let's check how those changes are done code-wise.
For Pythonists, the changes needed in their Python client are regarding the library in use, and how their Python client objects are called. Here we are considering the official Python client libraries for Elasticsearch and OpenSearch.
With a few steps, you can replace your Elasticsearch client with the OpenSearch one.
In the dependencies, change libraries and versions:
Loading code...
In the source code, change the imports:
Loading code...
and the client:
Loading code...
The good news is that you can reuse the same APIs as the Elasticsearch ones in your OpenSearch client. Take a look at the full example on our OpenSearch migration repository.
If you want to know more about the Python OpenSearch client and its compatibility, feel free to explore those resources:
Good news for Java client users, minimal changes are needed when you are migrating to OpenSearch. You only need to install the new dependencies and change your imports. Here you can find the changes related to imports:
Loading code...
In your Java client, the changes look like this:
Loading code...
By changing the imports, you should be able to use your OpenSearch client with the same APIs as the Elasticsearch ones.
Find out more about OpenSearch Java client, including a full running example of OpenSearch client migration on the links below:
Client migration in JavaScript is pretty straightforward, you only need to install the new dependency and change the require statement.
The dependencies can be installed with npm as follows:
Loading code...
You can find in this sample the client change for the NodeJS client:
Loading code...
You should be able to reuse the APIs once the imports are set correctly.
Check more resources for OpenSearch migration with NodeJS client:
With the recent changes in Elasticsearch policies, many users are looking for ways to migrate to alternatives like OpenSource. Being a direct fork of Elasticsearch v7, OpenSearch is very compatible with Elasticsearch. Aiven offers an easy way to perform an upgrade from the Aiven console with a click of a button. While this might seem straightforward, it involves a change in the client regarding the library and APIs used. This article walks you through the process that you need to do to guarantee a successful migration of your data.
Being open source, the OpenSearch project welcomes everyone to contribute to it by adding new features and helping to maintain them. We all know that open source is for everyone, but at Aiven we take the responsibility to contribute back to such projects. Aiven is actively contributing to the OpenSearch project via our Open Source Program Office.
The examples in this article are part of the OSS project for OpenSearch migration examples, feel free to make a fork and add more examples in your favorite languages. It is a nice way to share your knowledge with the OpenSearch and Elasticsearch communities.
Elasticsearch is a trademark of Elasticsearch B.V., registered in the U.S. and in other countries.
- elasticsearch==7.10.2
+ opensearch-py==1.0.0- from elasticsearch import Elasticsearch
+ from opensearchpy import OpenSearch- client_against_opensearch = Elasticsearch(ES_SERVICE_URI, use_ssl=True)
+ client_against_opensearch = OpenSearch(OS_SERVICE_URI, use_ssl=True)- implementation 'org.elasticsearch.client:elasticsearch-rest-client:7.10.2'
- implementation 'org.elasticsearch.client:elasticsearch-rest-high-level-client:7.10.2'
+ implementation 'org.opensearch.client:opensearch-rest-client:1.1.0'
+ implementation 'org.opensearch.client:opensearch-rest-high-level-client:1.1.0'- private static final String CLIENT_LIBRARY = "org.elasticsearch.client:elasticsearch-rest-client:7.10.2";
+ private static final String CLIENT_LIBRARY = "org.opensearch.client:opensearch-rest-client:1.1.0";
$ npm install --save @opensearch-project/opensearch- const { Client } = require('@elastic/elasticsearch');
+ const { Client } = require('@opensearch-project/opensearch');