Jest – Elasticsearch Java Client

1. Introduction

Anyone who has worked with Elasticsearch knows that building queries using their RESTful search API can be tedious and error-prone.

In this tutorial, we’ll look at Jest, an HTTP Java client for Elasticsearch. While Elasticsearch provides its own native Java client, Jest provides a more fluent API and easier interfaces to work with.

2. Maven Dependency

The first thing we need to do is import the Jest library into our POM:

<dependency>
    <groupId>io.searchbox</groupId>
    <artifactId>jest</artifactId>
    <version>6.3.1</version>
</dependency>

The versioning for Jest follows that of the main Elasticsearch product. This helps ensure compatibility between client and server.

By including the Jest dependency, the corresponding Elasticsearch library will be included as a transitive dependency.

3. Using Jest Client

In this section, we’ll look at using the Jest client to perform common tasks with Elasticsearch.

To use the Jest client, we simply create a JestClient object using the JestClientFactory. These objects are expensive to create and are thread-safe, so we’ll create a singleton instance that can be shared throughout our application:

public JestClient jestClient() {
    JestClientFactory factory = new JestClientFactory();
    factory.setHttpClientConfig(
      new HttpClientConfig.Builder("http://localhost:9200")
        .multiThreaded(true)
        .defaultMaxTotalConnectionPerRoute(2)
        .maxTotalConnection(10)
        .build());
    return factory.getObject();
}

This will create a Jest client connected to an Elasticsearch client running locally. While this connection example is trivial, Jest also has full support for proxies, SSL, authentication, and even node discovery.

The JestClient class is generic and only has a handful of public methods. The main one we’ll use is execute, which takes an instance of the Action interface. The Jest client provides several builder classes to help create different actions that interact with Elasticsearch.

The result of all Jest calls is an instance of JestResult. We can check for success by calling isSucceeded. For unsuccessful actions, we can call getErrorMessage to get more detail:

JestResult jestResult = jestClient.execute(new Delete.Builder("1").index("employees").build());

if (jestResult.isSucceeded()) {
    System.out.println("Success!");
}
else {
    System.out.println("Error: " + jestResult.getErrorMessage());
}

3.1. Managing Indices

To check if an index exists, we use the IndicesExists action:

JestResult result = jestClient.execute(new IndicesExists.Builder("employees").build())

To create an index, we use the CreateIndex action:

jestClient.execute(new CreateIndex.Builder("employees").build());

This will create an index with default settings. We can override specific settings during index creation:

Map<String, Object> settings = new HashMap<>();
settings.put("number_of_shards", 11);
settings.put("number_of_replicas", 2);
jestClient.execute(new CreateIndex.Builder("employees").settings(settings).build());

And creating or changing aliases is also simple using the ModifyAliases action:

jestClient.execute(new ModifyAliases.Builder(
  new AddAliasMapping.Builder("employees", "e").build()).build());
jestClient.execute(new ModifyAliases.Builder(
  new RemoveAliasMapping.Builder("employees", "e").build()).build());

3.2. Creating Documents

The Jest client makes it easy to index – or create – new documents using the Index action class. Documents in Elasticsearch are just JSON data, and there are multiple ways to pass JSON data to the Jest client for indexing.

For this example, let’s use an imaginary Employee document:

{
    "name": "Michael Pratt",
    "title": "Java Developer",
    "skills": ["java", "spring", "elasticsearch"],
    "yearsOfService": 2
}

The first way to represent a JSON document is by using a Java String. While we can manually create the JSON string, we have to be mindful of proper formatting, braces, and escaping quote characters.

Therefore, it’s easier to use a JSON library such as Jackson to build our JSON structure and then convert to a String:

ObjectMapper mapper = new ObjectMapper();
JsonNode employeeJsonNode = mapper.createObjectNode()
  .put("name", "Michael Pratt")
  .put("title", "Java Developer")
  .put("yearsOfService", 2)
  .set("skills", mapper.createArrayNode()
    .add("java")
    .add("spring")
    .add("elasticsearch"));
jestClient.execute(new Index.Builder(employeeJsonNode.toString()).index("employees").build());

We can also use a Java Map to represent JSON data and pass that to the Index action:

Map<String, Object> employeeHashMap = new LinkedHashMap<>();
employeeHashMap.put("name", "Michael Pratt");
employeeHashMap.put("title", "Java Developer");
employeeHashMap.put("yearsOfService", 2);
employeeHashMap.put("skills", Arrays.asList("java", "spring", "elasticsearch"));
jestClient.execute(new Index.Builder(employeeHashMap).index("employees").build());

Finally, the Jest client can accept any POJO that represents the document to index. Let’s say we have an Employee class:

public class Employee {
    String name;
    String title;
    List<String> skills;
    int yearsOfService;
}

We can pass an instance of this class directly to the Index builder:

Employee employee = new Employee();
employee.setName("Michael Pratt");
employee.setTitle("Java Developer");
employee.setYearsOfService(2);
employee.setSkills(Arrays.asList("java", "spring", "elasticsearch"));
jestClient.execute(new Index.Builder(employee).index("employees").build());

3.3. Reading Documents

There are two primary ways to access a document from Elasticsearch using Jest client. First, if we know the document ID, we can access it directly using the Get action:

jestClient.execute(new Get.Builder("employees", "17").build());

To access the returned document, we must call one of the various getSource methods. We can either get the result as raw JSON or deserialize it back to a DTO:

Employee getResult = jestClient.execute(new Get.Builder("employees", "1").build())
    .getSourceAsObject(Employee.class);

The other way of accessing documents is using a search query, which is implemented in Jest with the Search action.

Jest client supports the full Elasticsearch query DSL. Just like indexing operations, queries are expressed as JSON documents, and there are multiple ways to perform searches.

First, we can pass a JSON string that represents the search query. As a reminder, we must take care to ensure the string is properly escaped and is valid JSON:

String search = "{" +
  "  \"query\": {" +
  "    \"bool\": {" +
  "      \"must\": [" +
  "        { \"match\": { \"name\":   \"Michael Pratt\" }}" +
  "      ]" +
  "    }" +
  "  }" +
  "}";
jestClient.execute(new Search.Builder(search).build());

As with the Index action above, we could use a library such as Jackson to build our JSON query string.

Additionally, we can also use the native Elasticsearch query action API. The one downside of this is that our application has to depend on the full Elasticsearch library.

With the Search action, the matching documents can be accessed using the getSource methods. However, Jest also provides the Hit class, which wraps the matching documents and provides metadata about the results. Using the Hit class, we can access additional metadata for each result: score, routing, and explain results, to name a few:

List<SearchResult.Hit<Employee, Void>> searchResults = 
  jestClient.execute(new Search.Builder(search).build())
    .getHits(Employee.class);
searchResults.forEach(hit -> {
    System.out.println(String.format("Document %s has score %s", hit.id, hit.score));
});

3.4. Updating Documents

Jest provides a simple Update action for updating documents:

employee.setYearOfService(3);
jestClient.execute(new Update.Builder(employee).index("employees").id("1").build());

It accepts the same JSON representations as the Index action we saw earlier, making it easy to share code between the two operations.

3.5. Deleting Documents

Deleting a document from an index is done using the Delete action. It only requires an index name and document ID:

jestClient.execute(new Delete.Builder("17")
  .index("employees")
  .build());

4. Bulk Operations

Jest client also supports bulk operations. This means we can save time and bandwidth by sending multiple operations together at the same time.

Using the Bulk action, we can combine any number of requests into a single call. We can even combine different types of requests together:

jestClient.execute(new Bulk.Builder()
  .defaultIndex("employees")
  .addAction(new Index.Builder(employeeObject1).build())
  .addAction(new Index.Builder(employeeObject2).build())
  .addAction(new Delete.Builder("17").build())
  .build());

5. Asynchronous Operations

Jest client also supports asynchronous operations, which means we can perform any of the above operations using non-blocking I/O.

To invoke an operation asynchronously, simply use the executeAsync method of the client:

jestClient.executeAsync(
  new Index.Builder(employeeObject1).build(),
  new JestResultHandler<JestResult>() {
      @Override public void completed(JestResult result) {
          // handle result
      }
      @Override public void failed(Exception ex) {
          // handle exception
      }
  });

Note that in addition to the action (indexing in this case), the asynchronous flow also requires a JestResultHandler. The Jest client will call this object when the action has finished. The interface has two methods – completed and failed – that allow handling either success or failure of the operation, respectively.

6. Conclusion

In this tutorial, we have looked briefly at the Jest client, a RESTful Java client for Elasticsearch.

Although we have only covered a small portion of its functionality, it’s clear that Jest is a robust Elasticsearch client. Its fluent builder classes and RESTful interfaces make it easy to learn, and its full support for Elasticsearch interfaces make it a capable alternative to the native client.