"Fossies" - the Fresh Open Source Software Archive

Member "elasticsearch-6.8.23/docs/java-api/client.asciidoc" (29 Dec 2021, 5466 Bytes) of package /linux/www/elasticsearch-6.8.23-src.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming AsciiDoc format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "client.asciidoc": 6.8.20_vs_6.8.21.

Client

You can use the Java client in multiple ways:

  • Perform standard index, get, delete and search operations on an existing cluster

  • Perform administrative tasks on a running cluster

Obtaining an Elasticsearch Client is simple. The most common way to get a client is by creating a TransportClient that connects to a cluster.

Important

The client must have the same major version (e.g. 2.x, or 5.x) as the nodes in the cluster. Clients may connect to clusters which have a different minor version (e.g. 2.3.x) but it is possible that new functionality may not be supported. Ideally, the client should have the same version as the cluster.

Warning

We plan on deprecating the TransportClient in Elasticsearch 7.0 and removing it completely in 8.0. Instead, you should be using the {java-rest}/java-rest-high.html[Java High Level REST Client], which executes HTTP requests rather than serialized Java requests. The {java-rest}/java-rest-high-level-migration.html[migration guide] describes all the steps needed to migrate.

The Java High Level REST Client currently has support for the more commonly used APIs, but there are a lot more that still need to be added. You can help us prioritise by telling us which missing APIs you need for your application by adding a comment to this issue: Java high-level REST client completeness.

Any missing APIs can always be implemented today by using the {java-rest}/java-rest-low.html[low level Java REST Client] with JSON request and response bodies.

Transport Client

The TransportClient connects remotely to an Elasticsearch cluster using the transport module. It does not join the cluster, but simply gets one or more initial transport addresses and communicates with them in round robin fashion on each action (though most actions will probably be "two hop" operations).

// on startup

TransportClient client = new PreBuiltTransportClient(Settings.EMPTY)
        .addTransportAddress(new TransportAddress(InetAddress.getByName("host1"), 9300))
        .addTransportAddress(new TransportAddress(InetAddress.getByName("host2"), 9300));

// on shutdown

client.close();

Note that you have to set the cluster name if you use one different than "elasticsearch":

Settings settings = Settings.builder()
        .put("cluster.name", "myClusterName").build();
TransportClient client = new PreBuiltTransportClient(settings);
//Add transport addresses and do something with the client...

The Transport client comes with a cluster sniffing feature which allows it to dynamically add new hosts and remove old ones. When sniffing is enabled, the transport client will connect to the nodes in its internal node list, which is built via calls to addTransportAddress. After this, the client will call the internal cluster state API on those nodes to discover available data nodes. The internal node list of the client will be replaced with those data nodes only. This list is refreshed every five seconds by default. Note that the IP addresses the sniffer connects to are the ones declared as the 'publish' address in those node’s Elasticsearch config.

Keep in mind that the list might possibly not include the original node it connected to if that node is not a data node. If, for instance, you initially connect to a master node, after sniffing, no further requests will go to that master node, but rather to any data nodes instead. The reason the transport client excludes non-data nodes is to avoid sending search traffic to master only nodes.

In order to enable sniffing, set client.transport.sniff to true:

Settings settings = Settings.builder()
        .put("client.transport.sniff", true).build();
TransportClient client = new PreBuiltTransportClient(settings);

Other transport client level settings include:

Parameter Description

client.transport.ignore_cluster_name

Set to true to ignore cluster name validation of connected nodes. (since 0.19.4)

client.transport.ping_timeout

The time to wait for a ping response from a node. Defaults to 5s.

client.transport.nodes_sampler_interval

How often to sample / ping the nodes listed and connected. Defaults to 5s.

Connecting a Client to a Coordinating Only Node

You can start locally a {ref}/modules-node.html#coordinating-only-node[Coordinating Only Node] and then simply create a TransportClient in your application which connects to this Coordinating Only Node.

This way, the coordinating only node will be able to load whatever plugin you need (think about discovery plugins for example).