Migrate your Elasticsearch client to OpenSearch^®

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:

• Upgrade Elasticsearch clients to OpenSearch, if you are migrating within Aiven
• General tips in how to work with your OpenSearch cluster
• Migrate Elasticsearch data to Aiven for OpenSearch, if you are migrating an external database to Aiven

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.

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.

Python

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
Copy to clipboard

In the source code, change the imports:

- from elasticsearch import Elasticsearch
+ from opensearchpy import OpenSearch
Copy to clipboard

and the client:

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

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:

• Compatibility
• Python Client
• Python, OpenSearch migration examples

Java

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'
Copy to clipboard

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";
Copy to clipboard

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:

• Compatibility
• Java High Level Client
• Java, OpenSearch migration examples

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
Copy to clipboard

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

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

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

Check more resources for OpenSearch migration with NodeJS client:

• Compatibility
• NodeJS Client
• NodeJS, OpenSearch migration examples

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.