The official Java client for Elasticsearch.

Note: this project is still in beta. This client is meant to replace the existing Java High Level Client and remove all dependencies to the Elasticsearch server code base.

The Java client for Elasticsearch provides strongly typed requests and responses for all Elasticsearch APIs. It delegates protocol handling to an http client such as the Elasticsearch Low Level REST client that takes care of all transport-level concerns (http connection establishment and pooling, retries, etc).

The docs/design folder contains records of the major decisions in the design of the API. Most notably:

• Object construction is based on the builder pattern.
• Nested objects can be constructed with builder lambdas, allowing for clean and expressive DSL-like code.
• Optional values are represented as null with @Nullable annotations instead of the newer Optional, the Java ecosystem being still very null-based.

Please refer to the full documentation on elastic.co for comprehensive information.

This library requires at least Java 8.

Along with this library, you also need a JSON/object mapping library. elasticsearch-java has built-in support for Jackson and JSON-B implementations such as Eclipse Yasson.

Releases are hosted on Maven Central. If you are looking for a SNAPSHOT version, the Elastic Maven Snapshot repository is available at https://snapshots.elastic.co/maven/.

Gradle project (Groovy flavor) setup using Jackson:

dependencies {
    implementation 'co.elastic.clients:elasticsearch-java:7.15.0'
    implementation 'com.fasterxml.jackson.core:jackson-databind:2.12.3'
}

In the pom.xml for your project add the following repository definition and dependencies:

<project>
  <dependencies>
    <dependency>
      <groupId>co.elastic.clients</groupId>
      <artifactId>elasticsearch-java</artifactId>
      <version>7.15.0</version>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.12.3</version>
    </dependency>
  </dependencies>

</project>

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

// Create the transport that provides JSON and http services to API clients
Transport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());

// And create our API client
ElasticsearchClient client = new ElasticsearchClient(transport);

// Search all items in an index that contains documents of type AppData
SearchResponse search = client.search(s -> s
    .index("test-index"),
    AppData.class
);

if (search.hits().hits().isEmpty()) {
    System.out.println("No match");
} else {
    for (Hit<AppData> hit : search.hits().hits()) {
        processAppData(hit._source());
    }
}

The main branch targets the next major release (8.0) and the 7.x branch targets the next minor release. Support is still incomplete as the API code is generated from the Elasticsearch Specification that is also still a work in progress.

The Elasticsearch Java client is forward compatible; meaning that the client supports communicating with greater minor versions of Elasticsearch. Elastic language clients are also backwards compatible with lesser supported minor Elasticsearch versions.

Beta state means we don't expect large architectural changes and the library is already fairly usable. This library also essentially deals with request & response serialization & deserialization and delegates all http request processing to the battle-tested Low Level Rest Client.

What's missing falls in two main categories, related to the Elasticsearch specification:

• incomplete support for some data types used in specification (e.g. unions). Until they have been implemented in the code generator, they are represented as raw JsonValue objects.
• incomplete APIs: as the API specification is still incomplete, so are their implementations in this library since their code is entirely generated from the spec.

See CONTRIBUTING.md

This software is licensed under the Apache License 2.0.