Elasticsearch:Java API

Alibaba Cloud Elasticsearch supports four Java clients for interacting with your cluster. Each client uses a different protocol and targets different Elasticsearch versions. Choose the client that matches your cluster version and use case.

Client types

How it works

All REST-based Java clients (Low Level REST Client, High Level REST Client, and Java API Client) connect to your Elasticsearch cluster over HTTPS using basic authentication. The client sends HTTP requests to the cluster endpoint and receives JSON responses.

Transport Client connects over TCP instead of HTTP. Because TCP-based communication introduces version compatibility constraints that HTTP-based clients avoid, Elasticsearch deprecated Transport Client starting in version 7.x.

Version compatibility

Match your client version to your cluster version to avoid compatibility issues. The Java API Client follows Elasticsearch's version numbering: a client at version 8.x is forward-compatible with Elasticsearch 8.x clusters and later minor versions within the same major release.

Usage examples

All examples use basic authentication. Replace the placeholders with your actual values before running the code.

Java High Level REST Client

This example uses High Level REST Client 6.7. Add the following dependency to your Maven pom.xml:

<dependency>
  <groupId>org.elasticsearch.client</groupId>
  <artifactId>elasticsearch-rest-high-level-client</artifactId>
  <version>6.7.0</version>
</dependency>

For Gradle, add:

dependencies {
    implementation 'org.elasticsearch.client:elasticsearch-rest-high-level-client:6.7.0'
}

import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.elasticsearch.action.delete.DeleteRequest;
import org.elasticsearch.action.delete.DeleteResponse;
import org.elasticsearch.action.index.IndexRequest;
import org.elasticsearch.action.index.IndexResponse;
import org.elasticsearch.client.*;

import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

public class HighLevelRestClientExample {

    private static final RequestOptions COMMON_OPTIONS;

    static {
        RequestOptions.Builder builder = RequestOptions.DEFAULT.toBuilder();
        COMMON_OPTIONS = builder.build();
    }

    public static void main(String[] args) throws IOException {
        // Set up credentials
        final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(AuthScope.ANY,
            new UsernamePasswordCredentials("<UserName>", "<YourPassword>"));

        // Create the client
        RestClientBuilder builder = RestClient.builder(
            new HttpHost("<YourEsHost>", 9200, "http"))
            .setHttpClientConfigCallback(
                (HttpAsyncClientBuilder httpClientBuilder) ->
                    httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider));

        RestHighLevelClient client = new RestHighLevelClient(builder);

        // Index a document
        Map<String, Object> document = new HashMap<>();
        document.put("title", "Example document");
        document.put("content", "Hello, Elasticsearch!");

        IndexRequest indexRequest = new IndexRequest("<YourEsIndex>")
            .id("<YourEsId>")
            .source(document);

        IndexResponse indexResponse = client.index(indexRequest, COMMON_OPTIONS);
        System.out.println("Indexed document ID: " + indexResponse.getId());

        // Delete a document
        DeleteRequest deleteRequest = new DeleteRequest("<YourEsIndex>", "<YourEsId>");
        DeleteResponse deleteResponse = client.delete(deleteRequest, COMMON_OPTIONS);
        System.out.println("Deleted document ID: " + deleteResponse.getId());

        client.close();
    }
}

Java Low Level REST Client

The Java Low Level REST Client works with all Elasticsearch versions. Use it when you need broad version compatibility or want full control over request serialization.

Add the following dependency to your Maven pom.xml:

<dependency>
  <groupId>org.elasticsearch.client</groupId>
  <artifactId>elasticsearch-rest-client</artifactId>
  <version>6.7.0</version>
</dependency>

For Gradle, add:

dependencies {
    implementation 'org.elasticsearch.client:elasticsearch-rest-client:6.7.0'
}

import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.elasticsearch.client.RestClient;
import org.elasticsearch.client.RestClientBuilder;

public class LowLevelRestClientExample {

    public static void main(String[] args) throws Exception {
        // Set up credentials
        final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
        credentialsProvider.setCredentials(AuthScope.ANY,
            new UsernamePasswordCredentials("<UserName>", "<YourPassword>"));

        // Create the client
        RestClient client = RestClient.builder(
            new HttpHost("<YourEsHost>", 9200, "http"))
            .setHttpClientConfigCallback(
                (HttpAsyncClientBuilder httpClientBuilder) ->
                    httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider))
            .build();

        // Use the client to send requests...

        client.close();
    }
}

Related topics

• For sample code covering all client types, see Overview.

• To reset your cluster password, see Reset the access password for an Elasticsearch cluster.