In this article, I will show you how to switch from Elasticsearch to an OpenSearch client.
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.
In this article, we will briefly explain the database migration process, and how to perform your client migration.
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.
| 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.
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
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:
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'
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:
Resources
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.
Top comments (0)