Migrating from the High Level Rest Client

The Elasticsearch Java API Client is an entirely new client library that has no relation to the older High Level Rest Client (HLRC). This was a deliberate choice to provide a library that is independent from the Elasticsearch server code and that provides a very consistent and easier to use API for all Elasticsearch features.

Migrating from the HLRC therefore requires some code rewrite in your application. This transition can however happen progressively as the two client libraries can coexist in a single application with no operational overhead.

The HLRC version 7.17 can be used with Elasticsearch version 8.x by enabling HLRC’s compatibility mode (see code sample below). In this mode HLRC sends additional headers that instruct Elasticsearch 8.x to behave like a 7.x server.

The Java API Client doesn’t need this setting as compatibility mode is always enabled.

You can use the HLRC version 7.x with the Java API Client version 8.x:

dependencies {
    implementation 'co.elastic.clients:elasticsearch-java:8.16.2'
    implementation 'org.elasticsearch.client:elasticsearch-rest-high-level-client:7.17.4'
    // other dependencies 
}

To avoid any operational overhead during the transition phase where an application would use both the HLRC and the new Java API Client, both clients can share the same Low Level Rest Client, which is the network layer that manages all connections, round-robin strategies, node sniffing, and so on.

The code below shows how to initialize both clients with the same HTTP client:

// Create the low-level client
RestClient httpClient = RestClient.builder(
    new HttpHost("localhost", 9200)
).build();

// Create the HLRC
RestHighLevelClient hlrc = new RestHighLevelClientBuilder(httpClient)
    .setApiCompatibilityMode(true) 
    .build();

// Create the Java API Client with the same low level client
ElasticsearchTransport transport = new RestClientTransport(
    httpClient,
    new JacksonJsonpMapper()
);

ElasticsearchClient esClient = new ElasticsearchClient(transport);

// hlrc and esClient share the same httpClient

There are different ways you can start transitioning away from the HLRC in your application code.

For example: