The Elasticsearch Java High-Level Rest Client is Out
Part of the success of Elasticsearch has probably been its large number of supported language clients right from the start. Its powerful REST API can be accessed using HTTP and JSON, which makes it easy to integrate with using any language that provides those capabilities.
Nevertheless, there hasn’t been an official Elastic Java REST client for a long time. This was partly due to the existence of the native Java Client (also sometimes called the TransportClient), that doesn’t communicate with the cluster via REST but via a binary protocol. However, there are several drawbacks of this client, like security aspects or tighter coupling to JVM and cluster versions. For more details, we recommend reading the State of the Official Elasticsearch Java Clients blog post, where we also described our future plans around the Java clients for Elasticsearch.
Enter the Low-Level Client
As a first step to improve the situation, the low-level REST client was released with version 5.0 of the Elastic Stack. It solved the compatibility and dependency problems by providing strict access via the REST API. However, this came at the price of losing all the comforts of the Java API, which people were used to when using the transport client, like search request and query builders and response objects that are convenient to use in Java. That’s why next we started working on the high-level REST client: a client that sends requests using the low-level client, but that is also able to accept higher level request objects and returns response objects similar to those the native client already uses.
Let's Level Up
Right after the release of version 5.0 we started working on the high-level client, with the primary goal to make migration from the current transport client easy and to initially support the core APIs index, bulk, get, delete and search. It soon became clear that in order to progress and to ease migration at the same time, we would still need the current search and query builders and support the current response objects. The work then mostly involved implementing parsing Elasticsearch REST responses back to Java objects, a tedious issue if you consider the richness especially of the search response with all its varying aggregation responses. One of the tracking issues gives a bit of an insight into the work that has gone into this.
For this reason, the high-level client still depends on Elasticsearch, like the Java API does today. This may not be ideal, as it still ties users of the client to depend on a certain version of Elasticsearch, but this decision allows users to migrate away more easily from the transport client. We would like to get rid of this direct dependency in the future, but since this is a separate long-term project, we didn’t want this to affect the timing of the client’s first release.
The first release of the Java high-level REST client went out with the 6.0.0-beta1 release of the Elastic Stack. It allows you to communicate via REST with Elasticsearch nodes running 6.0.0-beta1, but it is not fully compatible with 5.x nodes. The 5.6.0 release of the Elastic Stack recently went out and includes the 5.6.0 version of the high-level client, which works against Elasticsearch nodes running version 5.6. It is unfortunately not compatible with previous 5.x versions of Elasticsearch.
What’s Up Next?
The high-level client will eventually replace the transport client in the future, hence we invite all our Java users to try it out and migrate to it if possible. The current release supports the following Elasticsearch APIs:
index, get, delete, update, bulk, search, scroll and clear scroll. Support for other APIs will be added step by step, also according to the feedback received from the community. As described in our migration guide, it is possible meanwhile to use the low-level REST client to perform requests that are not yet supported by the high-level one.
The documentation for the high-level REST client can be found here, and its javadoc here. We are looking forward to your feedback! Even better: become an Elastic Pioneer and receive a special Elastic gift package as our thanks for trying out the high level client in one of the 6.0 pre-releases and report any bug you find on our GitHub page.