Aiven Blog

Mar 1, 2022

Migrate your Elasticsearch client to OpenSearch®

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 Feed

Developer Advocate

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.

How to migrate your Elasticsearch client to using OpenSearch®

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 Elasticsearch to OpenSearch migration:

In this article, we will briefly explain the database migration process, and how to perform your client migration.

Database migration from Elasticsearch to OpenSearch

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.

Client migration from Elasticsearch 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.

ClientRecommended version
Java low-level REST client7.13.4
Java high-level REST client7.13.4

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:

- elasticsearch==7.10.2 + opensearch-py==1.0.0

In the source code, change the imports:

- from elasticsearch import Elasticsearch + from opensearchpy import OpenSearch

and the client:

- client_against_opensearch = Elasticsearch(ES_SERVICE_URI, use_ssl=True) + client_against_opensearch = OpenSearch(OS_SERVICE_URI, use_ssl=True)

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:

- 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'

In your Java client, the changes look like this:

- 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";

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:

JavaScript (Node.js/NodeJS)

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:

$ npm install --save @opensearch-project/opensearch

You can find in this sample the client change for the NodeJS client:

- const { Client } = require('@elastic/elasticsearch'); + const { Client } = require('@opensearch-project/opensearch');

You should be able to reuse the APIs once the imports are set correctly.

Check more resources for OpenSearch migration with NodeJS client:

Next steps

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.

Related resources

  • Aiven for OpenSearch® updated to version 2.11.1 illustration

    Dec 20, 2023

    Aiven for Opensearch® is running OpenSearch® 2.11.1, bringing new AI capabilities, visual overhauls, and much more. Check out what's new and upgrade today.

  • What is Grafana®? illustration

    Sep 27, 2022

    By combining and correlating data from any source in one dashboard, Grafana® ensures your team is always on the same page.

  • Staying sane in open source illustration

    Oct 11, 2021

    Being part of a community is not always easy. Find out what Aiven is doing to support the individuals who contribute to and maintain open source projects.