mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-05 20:48:22 +00:00
1e35674eb0
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
187 lines
6.5 KiB
Plaintext
187 lines
6.5 KiB
Plaintext
[[client]]
|
|
== Client
|
|
|
|
You can use the *Java client* in multiple ways:
|
|
|
|
* 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
|
|
* Start full nodes when you want to run Elasticsearch embedded in your
|
|
own application or when you want to launch unit or integration tests
|
|
|
|
Obtaining an elasticsearch `Client` is simple. The most common way to
|
|
get a client is by:
|
|
|
|
1. Creating an embedded <<node-client,`Node`>> that acts as a node
|
|
within a cluster.
|
|
2. Requesting a `Client` from your embedded `Node`.
|
|
|
|
Another manner is by creating a <<transport-client,`TransportClient`>>
|
|
that connects to a cluster.
|
|
|
|
*Important:*
|
|
|
|
______________________________________________________________________________________________________________________________________________________________
|
|
Please note that you are encouraged to use the same version on client
|
|
and cluster sides. You may hit some incompatibility issues when mixing
|
|
major versions.
|
|
______________________________________________________________________________________________________________________________________________________________
|
|
|
|
|
|
[[node-client]]
|
|
=== Node Client
|
|
|
|
Instantiating a node based client is the simplest way to get a `Client`
|
|
that can execute operations against elasticsearch.
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
import static org.elasticsearch.node.NodeBuilder.*;
|
|
|
|
// on startup
|
|
|
|
Node node = nodeBuilder().node();
|
|
Client client = node.client();
|
|
|
|
// on shutdown
|
|
|
|
node.close();
|
|
--------------------------------------------------
|
|
|
|
When you start a `Node`, it joins an elasticsearch cluster. You can have
|
|
different clusters by simply setting the `cluster.name` setting, or
|
|
explicitly using the `clusterName` method on the builder.
|
|
|
|
You can define `cluster.name` in the `/src/main/resources/elasticsearch.yml`
|
|
file in your project. As long as `elasticsearch.yml` is present in the
|
|
classpath, it will be used when you start your node.
|
|
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
cluster.name: yourclustername
|
|
--------------------------------------------------
|
|
|
|
Or in Java:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
Node node = nodeBuilder().clusterName("yourclustername").node();
|
|
Client client = node.client();
|
|
--------------------------------------------------
|
|
|
|
The benefit of using the `Client` is the fact that operations are
|
|
automatically routed to the node(s) the operations need to be executed
|
|
on, without performing a "double hop". For example, the index operation
|
|
will automatically be executed on the shard that it will end up existing
|
|
at.
|
|
|
|
When you start a `Node`, the most important decision is whether it
|
|
should hold data or not. In other words, should indices and shards be
|
|
allocated to it. Many times we would like to have the clients just be
|
|
clients, without shards being allocated to them. This is simple to
|
|
configure by setting either `node.data` setting to `false` or
|
|
`node.client` to `true` (the `NodeBuilder` respective helper methods on
|
|
it):
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
import static org.elasticsearch.node.NodeBuilder.*;
|
|
|
|
// on startup
|
|
|
|
Node node = nodeBuilder().client(true).node();
|
|
Client client = node.client();
|
|
|
|
// on shutdown
|
|
|
|
node.close();
|
|
--------------------------------------------------
|
|
|
|
Another common usage is to start the `Node` and use the `Client` in
|
|
unit/integration tests. In such a case, we would like to start a "local"
|
|
`Node` (with a "local" discovery and transport). Again, this is just a
|
|
matter of a simple setting when starting the `Node`. Note, "local" here
|
|
means local on the JVM (well, actually class loader) level, meaning that
|
|
two *local* servers started within the same JVM will discover themselves
|
|
and form a cluster.
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
import static org.elasticsearch.node.NodeBuilder.*;
|
|
|
|
// on startup
|
|
|
|
Node node = nodeBuilder().local(true).node();
|
|
Client client = node.client();
|
|
|
|
// on shutdown
|
|
|
|
node.close();
|
|
--------------------------------------------------
|
|
|
|
|
|
[[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
|
|
|
|
Client client = TransportClient.builder().build()
|
|
.addTransportAddress(new InetSocketTransportAddress("host1", 9300))
|
|
.addTransportAddress(new InetSocketTransportAddress("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.settingsBuilder()
|
|
.put("cluster.name", "myClusterName").build();
|
|
Client client = TransportClient.builder().settings(settings).build();
|
|
//Add transport addresses and do something with the client...
|
|
--------------------------------------------------
|
|
|
|
Or using `elasticsearch.yml` file as shown in <<node-client>>
|
|
|
|
The client allows sniffing the rest of the cluster, which adds data nodes
|
|
into its list of machines to use. In this case, note that the IP addresses
|
|
used will be the ones that the other nodes were started with (the
|
|
"publish" address). In order to enable it, set the
|
|
`client.transport.sniff` to `true`:
|
|
|
|
[source,java]
|
|
--------------------------------------------------
|
|
Settings settings = Settings.settingsBuilder()
|
|
.put("client.transport.sniff", true).build();
|
|
TransportClient client = TransportClient.builder().settings(settings).build();
|
|
--------------------------------------------------
|
|
|
|
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`.
|
|
|=======================================================================
|
|
|