Get started with the Java client

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Get started with the Java client

This page guides you through the installation process of the Java client, shows you how to initialize the client, and how to perform basic Elasticsearch operations with it.

See the Java client documentation for more detailed usage instructions.

The same client is used for Elasticsearch Serverless, on-premise and managed Elasticsearch. Some API endpoints are however not available in Elasticsearch Serverless.

Requirements

edit

Java 8 or later.
A JSON object mapping library to allow seamless integration of your application classes with the Elasticsearch API. The examples below show usage with Jackson.

Installation

edit

You can add the Java client to your Java project using either Gradle or Maven.

Use the version with the highest version number found on Maven Central, like 8.16.1. We refer to it as elasticVersion in the configuration examples below.

Using Gradle

edit

You can install the Java client as a Gradle dependency:

dependencies {
    implementation "co.elastic.clients:elasticsearch-java:${elasticVersion}"
    implementation "com.fasterxml.jackson.core:jackson-databind:2.17.0"
}

Using Maven

edit

You can install the Java client as a Maven dependency, add the following to the pom.xml of your project:

<project>
    <dependencies>

        <dependency>
            <groupId>co.elastic.clients</groupId>
            <artifactId>elasticsearch-java</artifactId>
            <version>${elasticVersion}</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.17.0</version>
        </dependency>

    </dependencies>
</project>

Initialize the client

edit

Initialize the client using your API key and Elasticsearch endpoint:

// URL and API key
String serverUrl = "https://...elastic.cloud";
String apiKey = "VnVhQ2ZHY0JDZGJrU...";

// Create the low-level client
RestClient restClient = RestClient
    .builder(HttpHost.create(serverUrl))
    .setDefaultHeaders(new Header[]{
        new BasicHeader("Authorization", "ApiKey " + apiKey)
    })
    .build();

// Create the transport with a Jackson mapper
ElasticsearchTransport transport = new RestClientTransport(
    restClient, new JacksonJsonpMapper());

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

To get API keys for the Elasticsearch endpoint for a project, see Get started.

Using the API

edit

After you initialized the client, you can start ingesting documents.

Creating an index and ingesting documents

edit

The following is an example of indexing a document, here a Product application object in the products index:

Product product = new Product("bk-1", "City bike", 123.0);

IndexResponse response = esClient.index(i -> i
    .index("products")
    .id(product.getSku())
    .document(product)
);

logger.info("Indexed with version " + response.version());

Searching

edit

Now that some data is available, you can search your documents using the search API:

String searchText = "bike";

SearchResponse<Product> response = esClient.search(s -> s
    .index("products")
    .query(q -> q
        .match(t -> t
            .field("name")
            .query(searchText)
        )
    ),
    Product.class
);

A few things to note in the above example:

The search query is built using a hierarchy of lambda expressions that closely follows the Elasticsearch HTTP API. Lambda expressions allows you to be guided by your IDE’s autocompletion, without having to import (or even know!) the actual classes representing a query.
The last parameter Product.class instructs the client to return results as Product application objects instead of raw JSON.

Updating

edit

You can update your documents using the update API:

Product product = new Product("bk-1", "City bike", 123.0);

esClient.update(u -> u
        .index("products")
        .id("bk-1")
        .upsert(product),
    Product.class
);

Delete

edit

You can also delete documents:

esClient.delete(d -> d.index("products").id("bk-1"));

Deleting an index

edit

esClient.indices().delete(d -> d.index("products"));

« Get started with the Go client Get started with the serverless .NET client »