Elasticsearch:FAQ about using a client to access an Elasticsearch cluster

Client and port compatibility

The following table summarizes which client and port to use based on your cluster version.

Custom ports are not supported. All versions support Java APIs over port 9200.

Is Alibaba Cloud Elasticsearch compatible with open source Elasticsearch APIs?

Alibaba Cloud Elasticsearch supports two categories of APIs:

• Open source REST APIs — fully compatible with the REST APIs provided by open source Elasticsearch. Use these to manage cluster data: add, update, or delete documents, run searches, and configure aliases. See REST API.

• Alibaba Cloud management API — a dedicated API for administrative operations, equivalent to what you can do in the Alibaba Cloud Elasticsearch console: create clusters, configure IP address whitelists, and more. See List of operations by function.

How do I configure the cluster.name parameter when using Transport Client?

Set cluster.name to the cluster ID. Get the cluster ID from the Basic Information page in the Alibaba Cloud Elasticsearch console. See View the basic information of a cluster.

Settings settings = Settings.builder()
    .put("cluster.name", "<your-cluster-id>")   // Replace with your cluster ID from the Basic Information page
    .put("client.transport.sniff", false)         // Required: set to false for Alibaba Cloud ES
    .build();

Why does NoNodeAvailableException appear when using Transport Client?

This error occurs when using Transport Client 5.5 or 5.6, which have known SDK bugs. Use Transport Client 5.3.3 instead. Note that Transport Client can only access Alibaba Cloud Elasticsearch V5.5 or V5.6 clusters.

Also set client.transport.sniff to false:

Settings settings = Settings.builder()
    .put("client.transport.sniff", false)
    .build();

For more details, see Transport Client (5.x).

What do I do if Client Request Timeout appears?

Check the following causes in order:

Can I use a Java API to access a cluster over port 9200?

Yes. All Java APIs supported by open source Elasticsearch work with Alibaba Cloud Elasticsearch clusters of all versions over port 9200.

For V5.X clusters, you can also use Transport Client 5.3.3 over port 9300. Port 9300 is disabled on V6.0 and later clusters due to security risks — use port 9200 only.

See the Client and port compatibility table for a full summary.

What do I do if Connection reset by peer appears?

This error occurs when the client attempts a read or write operation after losing its connection to the cluster. Work through the following checks:

1. Check cluster health

Review cluster logs and monitoring data for signs of trouble: unhealthy cluster status, node disconnection, or elevated error rates. Resolve any cluster-side issues before investigating the client. See Metrics and exception handling suggestions.

2. Check for a network interception policy

Capture packets from three points — the client side, the Elasticsearch service side, and the Server Load Balancer (SLB) side — to identify where the connection drops. If no packet loss is visible on any side, check whether a firewall or network interception policy on the client is closing the connection.

3. Check HTTP keep-alive timeout

HTTP keep-alive allows a single TCP connection to transfer multiple requests. If no traffic passes through the connection during the idle timeout period, the server closes it. Any request made after that point triggers a "Connection reset by peer" error.

To reduce this, increase the timeout values on the client side:

// Increase timeout values to reduce connection resets
RequestConfig requestConfig = RequestConfig.custom()
    .setConnectTimeout(10000)     // ConnectTimeout in milliseconds
    .setSocketTimeout(30000)      // SocketTimeout in milliseconds
    .build();

If the issue persists after these checks, review your application's retry logic and error-handling code.

How do I install cURL on Windows and connect to a cluster?

1. Download the cURL package for Windows from curl.se/windows and install it.

2. Run a cURL command to connect to your cluster. For command syntax and examples, see Use cURL commands and API operations to manage an Elasticsearch cluster.

Which SQL query methods are supported?

Alibaba Cloud Elasticsearch supports the same SQL query methods as open source Elasticsearch. The following methods are available:

• SQL REST API — submit SQL queries over HTTP. See SQL REST API.

• SQL Translate API — convert SQL queries to Elasticsearch DSL. See SQL Translate API.

• SQL JDBC driver — connect SQL-compatible tools to Elasticsearch. See SQL JDBC driver.

For a full list of supported SQL client applications, see SQL client applications. Clusters on V6.3 or later support X-Pack SQL.

You can also use:

• X-Pack SQL — the x-pack-sql plug-in provided by Elastic. See sql-search-api.

• Third-party SQL plug-ins — for example, the open source elasticsearch-sql plug-in. See elasticsearch-sql on GitHub.