OpenSearch/docs/java-api/client.asciidoc

114 lines
4.7 KiB
Plaintext
Raw Normal View History

[[client]]
== Client
You can use the *Java client* in multiple ways:
[doc] Reorganize and clean Java documentation This commit reorganizes the docs to make Java API docs looking more like the REST docs. Also, with 2.0.0, FilterBuilders don't exist anymore but only QueryBuilders. Also, all docs api move now to docs/java-api/docs dir as for REST doc. Remove removed queries/filters ----- * Remove Constant Score Query with filter * Remove Fuzzy Like This (Field) Query (flt and flt_field) * Remove FilterBuilders Move filters to queries ----- * Move And Filter to And Query * Move Bool Filter to Bool Query * Move Exists Filter to Exists Query * Move Geo Bounding Box Filter to Geo Bounding Box Query * Move Geo Distance Filter to Geo Distance Query * Move Geo Distance Range Filter to Geo Distance Range Query * Move Geo Polygon Filter to Geo Polygon Query * Move Geo Shape Filter to Geo Shape Query * Move Has Child Filter by Has Child Query * Move Has Parent Filter by Has Parent Query * Move Ids Filter by Ids Query * Move Limit Filter to Limit Query * Move MatchAll Filter to MatchAll Query * Move Missing Filter to Missing Query * Move Nested Filter to Nested Query * Move Not Filter to Not Query * Move Or Filter to Or Query * Move Range Filter to Range Query * Move Ids Filter to Ids Query * Move Term Filter to Term Query * Move Terms Filter to Terms Query * Move Type Filter to Type Query Add missing queries ----- * Add Common Terms Query * Add Filtered Query * Add Function Score Query * Add Geohash Cell Query * Add Regexp Query * Add Script Query * Add Simple Query String Query * Add Span Containing Query * Add Span Multi Term Query * Add Span Within Query Reorganize the documentation ----- * Organize by full text queries * Organize by term level queries * Organize by compound queries * Organize by joining queries * Organize by geo queries * Organize by specialized queries * Organize by span queries * Move Boosting Query * Move DisMax Query * Move Fuzzy Query * Move Indices Query * Move Match Query * Move Mlt Query * Move Multi Match Query * Move Prefix Query * Move Query String Query * Move Span First Query * Move Span Near Query * Move Span Not Query * Move Span Or Query * Move Span Term Query * Move Template Query * Move Wildcard Query Add some missing pages ---- * Add multi get API * Add indexed-scripts link Also closes #7826 Related to https://github.com/elastic/elasticsearch/pull/11477#issuecomment-114745934
2015-06-24 17:27:19 -04:00
* Perform standard <<java-docs-index,index>>, <<java-docs-get,get>>,
<<java-docs-delete,delete>> and <<java-search,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 <<transport-client,`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: The `TransportClient` is aimed to be replaced by the Java High Level REST
Client, which executes HTTP requests instead of serialized Java requests. The
`TransportClient` will be deprecated in upcoming versions of Elasticsearch and it
is advised to use the Java High Level REST Client instead.
[[transport-client]]
=== 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).
[source,java]
--------------------------------------------------
// 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":
[source,java]
--------------------------------------------------
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`:
[source,java]
--------------------------------------------------
2017-03-09 05:52:19 -05:00
Settings settings = Settings.builder()
.put("client.transport.sniff", true).build();
TransportClient client = new PreBuiltTransportClient(settings);
--------------------------------------------------
Other transport client level settings include:
[cols="<,<",options="header",]
|=======================================================================
|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`.
|=======================================================================
[[client-connected-to-client-node]]
=== 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 <<transport-client,`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).