"Fossies" - the Fresh Open Source Software Archive

Member "elasticsearch-6.8.23/docs/java-api/index.asciidoc" (29 Dec 2021, 5662 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 "index.asciidoc": 6.8.20_vs_6.8.21.

Unresolved directive in ../Versions.asciidoc - include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[]

Unresolved directive in ../Versions.asciidoc - include::{asciidoc-dir}/../../shared/attributes.asciidoc[]

Preface

This section describes the Java API that Elasticsearch provides. All Elasticsearch operations are executed using a Client object. All operations are completely asynchronous in nature (either accepts a listener, or returns a future).

Additionally, operations on a client may be accumulated and executed in Bulk.

Note, all the APIs are exposed through the Java API (actually, the Java API is used internally to execute them).

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.

Javadoc

Maven Repository

Elasticsearch is hosted on Maven Central.

For example, you can define the latest version in your pom.xml file:


    org.elasticsearch.client
    transport
    {version}

Lucene Snapshot repository

The very first releases of any major version (like a beta), might have been built on top of a Lucene Snapshot version. In such a case you will be unable to resolve the Lucene dependencies of the client.

For example, if you want to use the 6.0.0-beta1 version which depends on Lucene 7.0.0-snapshot-00142c9, you must define the following repository.

For Maven:


    elastic-lucene-snapshots
    Elastic Lucene Snapshots
    https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9
    true
    false

For Gradle:

maven {
    name "lucene-snapshots"
    url 'https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9'
}

Log4j 2 Logger

You need to also include Log4j 2 dependencies:


    org.apache.logging.log4j
    log4j-core
    2.17.1

And also provide a Log4j 2 configuration file in your classpath. For example, you can add in your src/main/resources project dir a log4j2.properties file like:

appender.console.type = Console
appender.console.name = console
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = [%d{ISO8601}][%-5p][%-25c] %marker%m%n

rootLogger.level = info
rootLogger.appenderRef.console.ref = console

Using another Logger

If you want to use another logger than Log4j 2, you can use SLF4J bridge to do that:


    org.apache.logging.log4j
    log4j-to-slf4j
    2.17.1


    org.slf4j
    slf4j-api
    1.7.24

This page lists implementations you can use. Pick your favorite logger and add it as a dependency. As an example, we will use the slf4j-simple logger:


    org.slf4j
    slf4j-simple
    1.7.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).

Document APIs

This section describes the following CRUD APIs:

Single document APIs
Note
All CRUD APIs are single-index APIs. The index parameter accepts a single index name, or an alias which points to a single index.

Index API

The index API allows one to index a typed JSON document into a specific index and make it searchable.

Generate JSON document

There are several different ways of generating a JSON document:

  • Manually (aka do it yourself) using native byte[] or as a String

  • Using a Map that will be automatically converted to its JSON equivalent

  • Using a third party library to serialize your beans such as Jackson

  • Using built-in helpers XContentFactory.jsonBuilder()

Internally, each type is converted to byte[] (so a String is converted to a byte[]). Therefore, if the object is in this form already, then use it. The jsonBuilder is highly optimized JSON generator that directly constructs a byte[].

Do It Yourself

Nothing really difficult here but note that you will have to encode dates according to the {ref}/mapping-date-format.html[Date Format].

String json = "{" +
        "\"user\":\"kimchy\"," +
        "\"postDate\":\"2013-01-30\"," +
        "\"message\":\"trying out Elasticsearch\"" +
    "}";
Using Map

Map is a key:values pair collection. It represents a JSON structure:

Map<String, Object> json = new HashMap<String, Object>();
json.put("user","kimchy");
json.put("postDate",new Date());
json.put("message","trying out Elasticsearch");
Serialize your beans

You can use Jackson to serialize your beans to JSON. Please add Jackson Databind to your project. Then you can use ObjectMapper to serialize your beans:

import com.fasterxml.jackson.databind.*;

// instance a json mapper
ObjectMapper mapper = new ObjectMapper(); // create once, reuse

// generate json
byte[] json = mapper.writeValueAsBytes(yourbeaninstance);
Use Elasticsearch helpers

Elasticsearch provides built-in helpers to generate JSON content.

import static org.elasticsearch.common.xcontent.XContentFactory.*;

XContentBuilder builder = jsonBuilder()
    .startObject()
        .field("user", "kimchy")
        .field("postDate", new Date())
        .field("message", "trying out Elasticsearch")
    .endObject()

Note that you can also add arrays with startArray(String) and endArray() methods. By the way, the field method
accepts many object types. You can directly pass numbers, dates and even other XContentBuilder objects.

If you need to see the generated JSON content, you can use the Strings.toString() method.

import org.elasticsearch.common.Strings;

String json = Strings.toString(builder);

Index document

The following example indexes a JSON document into an index called twitter, under a type called _doc`, with id valued 1:

import static org.elasticsearch.common.xcontent.XContentFactory.*;

IndexResponse response = client.prepareIndex("twitter", "_doc", "1")
        .setSource(jsonBuilder()
                    .startObject()
                        .field("user", "kimchy")
                        .field("postDate", new Date())
                        .field("message", "trying out Elasticsearch")
                    .endObject()
                  )
        .get();

Note that you can also index your documents as JSON String and that you don’t have to give an ID:

String json = "{" +
        "\"user\":\"kimchy\"," +
        "\"postDate\":\"2013-01-30\"," +
        "\"message\":\"trying out Elasticsearch\"" +
    "}";

IndexResponse response = client.prepareIndex("twitter", "_doc")
        .setSource(json, XContentType.JSON)
        .get();

IndexResponse object will give you a report:

// Index name
String _index = response.getIndex();
// Type name
String _type = response.getType();
// Document ID (generated or not)
String _id = response.getId();
// Version (if it's the first time you index this document, you will get: 1)
long _version = response.getVersion();
// status has stored current instance statement.
RestStatus status = response.status();

For more information on the index operation, check out the REST {ref}/docs-index_.html[index] docs.

Get API

The get API allows to get a typed JSON document from the index based on its id. The following example gets a JSON document from an index called twitter, under a type called _doc`, with id valued 1:

GetResponse response = client.prepareGet("twitter", "_doc", "1").get();

For more information on the get operation, check out the REST {ref}/docs-get.html[get] docs.

Delete API

The delete API allows one to delete a typed JSON document from a specific index based on its id. The following example deletes the JSON document from an index called twitter, under a type called _doc, with id valued 1:

DeleteResponse response = client.prepareDelete("twitter", "_doc", "1").get();

For more information on the delete operation, check out the {ref}/docs-delete.html[delete API] docs.

Delete By Query API

The delete by query API allows one to delete a given set of documents based on the result of a query:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[delete-by-query-sync]
  1. query

  2. index

  3. execute the operation

  4. number of deleted documents

As it can be a long running operation, if you wish to do it asynchronously, you can call execute instead of get and provide a listener like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[delete-by-query-async]
  1. query

  2. index

  3. listener

  4. number of deleted documents

Update API

You can either create an UpdateRequest and send it to the client:

UpdateRequest updateRequest = new UpdateRequest();
updateRequest.index("index");
updateRequest.type("_doc");
updateRequest.id("1");
updateRequest.doc(jsonBuilder()
        .startObject()
            .field("gender", "male")
        .endObject());
client.update(updateRequest).get();

Or you can use prepareUpdate() method:

client.prepareUpdate("ttl", "doc", "1")
        .setScript(new Script(
            "ctx._source.gender = \"male\"", (1)
            ScriptService.ScriptType.INLINE, null, null))
        .get();

client.prepareUpdate("ttl", "doc", "1")
        .setDoc(jsonBuilder()               (2)
            .startObject()
                .field("gender", "male")
            .endObject())
        .get();
  1. Your script. It could also be a locally stored script name. In that case, you’ll need to use ScriptService.ScriptType.FILE

  2. Document which will be merged to the existing one.

Note that you can’t provide both script and doc.

Update by script

The update API allows to update a document based on a script provided:

UpdateRequest updateRequest = new UpdateRequest("ttl", "doc", "1")
        .script(new Script("ctx._source.gender = \"male\""));
client.update(updateRequest).get();

Update by merging documents

The update API also support passing a partial document, which will be merged into the existing document (simple recursive merge, inner merging of objects, replacing core "keys/values" and arrays). For example:

UpdateRequest updateRequest = new UpdateRequest("index", "type", "1")
        .doc(jsonBuilder()
            .startObject()
                .field("gender", "male")
            .endObject());
client.update(updateRequest).get();

Upsert

There is also support for upsert. If the document does not exist, the content of the upsert element will be used to index the fresh doc:

IndexRequest indexRequest = new IndexRequest("index", "type", "1")
        .source(jsonBuilder()
            .startObject()
                .field("name", "Joe Smith")
                .field("gender", "male")
            .endObject());
UpdateRequest updateRequest = new UpdateRequest("index", "type", "1")
        .doc(jsonBuilder()
            .startObject()
                .field("gender", "male")
            .endObject())
        .upsert(indexRequest);              (1)
client.update(updateRequest).get();
  1. If the document does not exist, the one in indexRequest will be added

If the document index/_doc/1 already exists, we will have after this operation a document like:

{
    "name"  : "Joe Dalton",
    "gender": "male"        (1)
}
  1. This field is added by the update request

If it does not exist, we will have a new document:

{
    "name" : "Joe Smith",
    "gender": "male"
}

Multi Get API

The multi get API allows to get a list of documents based on their index and id:

MultiGetResponse multiGetItemResponses = client.prepareMultiGet()
    .add("twitter", "_doc", "1")            (1)
    .add("twitter", "_doc", "2", "3", "4")  (2)
    .add("another", "_doc", "foo")          (3)
    .get();

for (MultiGetItemResponse itemResponse : multiGetItemResponses) { (4)
    GetResponse response = itemResponse.getResponse();
    if (response.isExists()) {                      (5)
        String json = response.getSourceAsString(); (6)
    }
}
  1. get by a single id

  2. or by a list of ids for the same index

  3. you can also get from another index

  4. iterate over the result set

  5. you can check if the document exists

  6. access to the _source field

For more information on the multi get operation, check out the REST {ref}/docs-multi-get.html[multi get] docs.

Bulk API

The bulk API allows one to index and delete several documents in a single request. Here is a sample usage:

import static org.elasticsearch.common.xcontent.XContentFactory.*;

BulkRequestBuilder bulkRequest = client.prepareBulk();

// either use client#prepare, or use Requests# to directly build index/delete requests
bulkRequest.add(client.prepareIndex("twitter", "_doc", "1")
        .setSource(jsonBuilder()
                    .startObject()
                        .field("user", "kimchy")
                        .field("postDate", new Date())
                        .field("message", "trying out Elasticsearch")
                    .endObject()
                  )
        );

bulkRequest.add(client.prepareIndex("twitter", "_doc", "2")
        .setSource(jsonBuilder()
                    .startObject()
                        .field("user", "kimchy")
                        .field("postDate", new Date())
                        .field("message", "another post")
                    .endObject()
                  )
        );

BulkResponse bulkResponse = bulkRequest.get();
if (bulkResponse.hasFailures()) {
    // process failures by iterating through each bulk response item
}

Using Bulk Processor

The BulkProcessor class offers a simple interface to flush bulk operations automatically based on the number or size of requests, or after a given period.

To use it, first create a BulkProcessor instance:

import org.elasticsearch.action.bulk.BackoffPolicy;
import org.elasticsearch.action.bulk.BulkProcessor;
import org.elasticsearch.common.unit.ByteSizeUnit;
import org.elasticsearch.common.unit.ByteSizeValue;
import org.elasticsearch.common.unit.TimeValue;

BulkProcessor bulkProcessor = BulkProcessor.builder(
        client,  (1)
        new BulkProcessor.Listener() {
            @Override
            public void beforeBulk(long executionId,
                                   BulkRequest request) { ... } (2)

            @Override
            public void afterBulk(long executionId,
                                  BulkRequest request,
                                  BulkResponse response) { ... } (3)

            @Override
            public void afterBulk(long executionId,
                                  BulkRequest request,
                                  Throwable failure) { ... } (4)
        })
        .setBulkActions(10000) (5)
        .setBulkSize(new ByteSizeValue(5, ByteSizeUnit.MB)) (6)
        .setFlushInterval(TimeValue.timeValueSeconds(5)) (7)
        .setConcurrentRequests(1) (8)
        .setBackoffPolicy(
            BackoffPolicy.exponentialBackoff(TimeValue.timeValueMillis(100), 3)) (9)
        .build();
  1. Add your Elasticsearch client

  2. This method is called just before bulk is executed. You can for example see the numberOfActions with request.numberOfActions()

  3. This method is called after bulk execution. You can for example check if there was some failing requests with response.hasFailures()

  4. This method is called when the bulk failed and raised a Throwable

  5. We want to execute the bulk every 10 000 requests

  6. We want to flush the bulk every 5mb

  7. We want to flush the bulk every 5 seconds whatever the number of requests

  8. Set the number of concurrent requests. A value of 0 means that only a single request will be allowed to be executed. A value of 1 means 1 concurrent request is allowed to be executed while accumulating new bulk requests.

  9. Set a custom backoff policy which will initially wait for 100ms, increase exponentially and retries up to three times. A retry is attempted whenever one or more bulk item requests have failed with an EsRejectedExecutionException which indicates that there were too little compute resources available for processing the request. To disable backoff, pass BackoffPolicy.noBackoff().

By default, BulkProcessor:

  • sets bulkActions to 1000

  • sets bulkSize to 5mb

  • does not set flushInterval

  • sets concurrentRequests to 1, which means an asynchronous execution of the flush operation.

  • sets backoffPolicy to an exponential backoff with 8 retries and a start delay of 50ms. The total wait time is roughly 5.1 seconds.

Add requests

Then you can simply add your requests to the BulkProcessor:

bulkProcessor.add(new IndexRequest("twitter", "_doc", "1").source(/* your doc here */));
bulkProcessor.add(new DeleteRequest("twitter", "_doc", "2"));

Closing the Bulk Processor

When all documents are loaded to the BulkProcessor it can be closed by using awaitClose or close methods:

bulkProcessor.awaitClose(10, TimeUnit.MINUTES);

or

bulkProcessor.close();

Both methods flush any remaining documents and disable all other scheduled flushes if they were scheduled by setting flushInterval. If concurrent requests were enabled the awaitClose method waits for up to the specified timeout for all bulk requests to complete then returns true, if the specified waiting time elapses before all bulk requests complete, false is returned. The close method doesn’t wait for any remaining bulk requests to complete and exits immediately.

Using Bulk Processor in tests

If you are running tests with Elasticsearch and are using the BulkProcessor to populate your dataset you should better set the number of concurrent requests to 0 so the flush operation of the bulk will be executed in a synchronous manner:

BulkProcessor bulkProcessor = BulkProcessor.builder(client, new BulkProcessor.Listener() { /* Listener methods */ })
        .setBulkActions(10000)
        .setConcurrentRequests(0)
        .build();

// Add your requests
bulkProcessor.add(/* Your requests */);

// Flush any remaining requests
bulkProcessor.flush();

// Or close the bulkProcessor if you don't need it anymore
bulkProcessor.close();

// Refresh your indices
client.admin().indices().prepareRefresh().get();

// Now you can start searching!
client.prepareSearch().get();

Global Parameters

Global parameters can be specified on the BulkRequest as well as BulkProcessor, similar to the REST API. These global parameters serve as defaults and can be overridden by local parameters specified on each sub request. Some parameters have to be set before any sub request is added - index, type - and you have to specify them during BulkRequest or BulkProcessor creation. Some are optional - pipeline, routing - and can be specified at any point before the bulk is sent.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/BulkProcessorIT.java[bulk-processor-mix-parameters]
  1. global parameters from the BulkRequest will be applied on a sub request

  2. local pipeline parameter on a sub request will override global parameters from BulkRequest

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/BulkRequestWithGlobalParametersIT.java[bulk-request-mix-pipeline]
  1. local pipeline parameter on a sub request will override global pipeline from the BulkRequest

  2. global parameter from the BulkRequest will be applied on a sub request

Update By Query API

The simplest usage of updateByQuery updates each document in an index without changing the source. This usage enables picking up a new property or another online mapping change.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query]

Calls to the updateByQuery API start by getting a snapshot of the index, indexing any documents found using the internal versioning.

Note
Version conflicts happen when a document changes between the time of the snapshot and the time the index request processes.

When the versions match, updateByQuery updates the document and increments the version number.

All update and query failures cause updateByQuery to abort. These failures are available from the BulkByScrollResponse#getIndexingFailures method. Any successful updates remain and are not rolled back. While the first failure causes the abort, the response contains all of the failures generated by the failed bulk request.

To prevent version conflicts from causing updateByQuery to abort, set abortOnVersionConflict(false). The first example does this because it is trying to pick up an online mapping change and a version conflict means that the conflicting document was updated between the start of the updateByQuery and the time when it attempted to update the document. This is fine because that update will have picked up the online mapping update.

The UpdateByQueryRequestBuilder API supports filtering the updated documents, limiting the total number of documents to update, and updating documents with a script:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-filter]

UpdateByQueryRequestBuilder also enables direct access to the query used to select the documents. You can use this access to change the default scroll size or otherwise modify the request for matching documents.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-size]

You can also combine size with sorting to limit the documents updated:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-sort]

In addition to changing the _source field for the document, you can use a script to change the action, similar to the Update API:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-script]

As in the Update API, you can set the value of ctx.op to change the operation that executes:

noop

Set ctx.op = "noop" if your script doesn’t make any changes. The updateByQuery operation then omits that document from the updates. This behavior increments the noop counter in the response body.

delete

Set ctx.op = "delete" if your script decides that the document must be deleted. The deletion will be reported in the deleted counter in the response body.

Setting ctx.op to any other value generates an error. Setting any other field in ctx generates an error.

This API doesn’t allow you to move the documents it touches, just modify their source. This is intentional! We’ve made no provisions for removing the document from its original location.

You can also perform these operations on multiple indices and types at once, similar to the search API:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-multi-index]

If you provide a routing value then the process copies the routing value to the scroll query, limiting the process to the shards that match that routing value:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-routing]

updateByQuery can also use the ingest node by specifying a pipeline like this:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-pipeline]

Works with the Task API

You can fetch the status of all running update-by-query requests with the Task API:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-list-tasks]

With the TaskId shown above you can look up the task directly:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-get-task]

Works with the Cancel Task API

Any Update By Query can be canceled using the Task Cancel API:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-cancel-task]

Use the list tasks API to find the value of taskId.

Cancelling a request is typically a very fast process but can take up to a few seconds. The task status API continues to list the task until the cancellation is complete.

Rethrottling

Use the _rethrottle API to change the value of requests_per_second on a running update:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[update-by-query-rethrottle]

Use the list tasks API to find the value of taskId.

As with the updateByQuery API, the value of requests_per_second can be any positive float value to set the level of the throttle, or Float.POSITIVE_INFINITY to disable throttling. A value of requests_per_second that speeds up the process takes effect immediately. requests_per_second values that slow the query take effect after completing the current batch in order to prevent scroll timeouts.

Reindex API

See {ref}/docs-reindex.html[reindex API].

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation/ReindexDocumentationIT.java[reindex1]
  1. Optionally a query can provided to filter what documents should be re-indexed from the source to the target index.

The search API allows one to execute a search query and get back search hits that match the query. It can be executed across one or more indices and across one or more types. The query can be provided using the query Java API. The body of the search request is built using the SearchSourceBuilder. Here is an example:

import org.elasticsearch.action.search.SearchResponse;
import org.elasticsearch.action.search.SearchType;
import org.elasticsearch.index.query.QueryBuilders.*;
SearchResponse response = client.prepareSearch("index1", "index2")
        .setSearchType(SearchType.DFS_QUERY_THEN_FETCH)
        .setQuery(QueryBuilders.termQuery("multi", "test"))                 // Query
        .setPostFilter(QueryBuilders.rangeQuery("age").from(12).to(18))     // Filter
        .setFrom(0).setSize(60).setExplain(true)
        .get();

Note that all parameters are optional. Here is the smallest search call you can write:

// MatchAll on the whole cluster with all default options
SearchResponse response = client.prepareSearch().get();
Note
Although the Java API defines the additional search types QUERY_AND_FETCH and DFS_QUERY_AND_FETCH, these modes are internal optimizations and should not be specified explicitly by users of the API.

For more information on the search operation, check out the REST {ref}/search.html[search] docs.

Using scrolls in Java

Read the {ref}/search-request-scroll.html[scroll documentation] first!

import static org.elasticsearch.index.query.QueryBuilders.*;

QueryBuilder qb = termQuery("multi", "test");

SearchResponse scrollResp = client.prepareSearch(test)
        .addSort(FieldSortBuilder.DOC_FIELD_NAME, SortOrder.ASC)
        .setScroll(new TimeValue(60000))
        .setQuery(qb)
        .setSize(100).get(); //max of 100 hits will be returned for each scroll
//Scroll until no hits are returned
do {
    for (SearchHit hit : scrollResp.getHits().getHits()) {
        //Handle the hit...
    }

    scrollResp = client.prepareSearchScroll(scrollResp.getScrollId()).setScroll(new TimeValue(60000)).execute().actionGet();
} while(scrollResp.getHits().getHits().length != 0); // Zero hits mark the end of the scroll and the while loop.

MultiSearch API

See {ref}/search-multi-search.html[MultiSearch API Query] documentation

SearchRequestBuilder srb1 = client
    .prepareSearch().setQuery(QueryBuilders.queryStringQuery("elasticsearch")).setSize(1);
SearchRequestBuilder srb2 = client
    .prepareSearch().setQuery(QueryBuilders.matchQuery("name", "kimchy")).setSize(1);

MultiSearchResponse sr = client.prepareMultiSearch()
        .add(srb1)
        .add(srb2)
        .get();

// You will get all individual responses from MultiSearchResponse#getResponses()
long nbHits = 0;
for (MultiSearchResponse.Item item : sr.getResponses()) {
    SearchResponse response = item.getResponse();
    nbHits += response.getHits().getTotalHits();
}

Using Aggregations

The following code shows how to add two aggregations within your search:

SearchResponse sr = client.prepareSearch()
    .setQuery(QueryBuilders.matchAllQuery())
    .addAggregation(
            AggregationBuilders.terms("agg1").field("field")
    )
    .addAggregation(
            AggregationBuilders.dateHistogram("agg2")
                    .field("birth")
                    .dateHistogramInterval(DateHistogramInterval.YEAR)
    )
    .get();

// Get your facet results
Terms agg1 = sr.getAggregations().get("agg1");
Histogram agg2 = sr.getAggregations().get("agg2");

See Aggregations Java API documentation for details.

Terminate After

The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early. If set, you will be able to check if the operation terminated early by asking for isTerminatedEarly() in the SearchResponse object:

SearchResponse sr = client.prepareSearch(INDEX)
    .setTerminateAfter(1000)    (1)
    .get();

if (sr.isTerminatedEarly()) {
    // We finished early
}
  1. Finish after 1000 docs

Search Template

See {ref}/search-template.html[Search Template] documentation

Define your template parameters as a Map<String,Object>:

Map<String, Object> template_params = new HashMap<>();
template_params.put("param_gender", "male");

You can use your stored search templates in config/scripts. For example, if you have a file named config/scripts/template_gender.mustache containing:

{
    "query" : {
        "match" : {
            "gender" : "{{param_gender}}"
        }
    }
}

Create your search template request:

SearchResponse sr = new SearchTemplateRequestBuilder(client)
    .setScript("template_gender")                 (1)
    .setScriptType(ScriptService.ScriptType.FILE) (2)
    .setScriptParams(template_params)             (3)
    .setRequest(new SearchRequest())              (4)
    .get()                                        (5)
    .getResponse();                               (6)
  1. template name

  2. template stored on disk in gender_template.mustache

  3. parameters

  4. set the execution context (ie. define the index name here)

  5. execute and get the template response

  6. get from the template response the search response itself

You can also store your template in the cluster state:

client.admin().cluster().preparePutStoredScript()
    .setScriptLang("mustache")
    .setId("template_gender")
    .setSource(new BytesArray(
        "{\n" +
        "    \"query\" : {\n" +
        "        \"match\" : {\n" +
        "            \"gender\" : \"{{param_gender}}\"\n" +
        "        }\n" +
        "    }\n" +
        "}")).get();

To execute a stored templates, use ScriptService.ScriptType.STORED:

SearchResponse sr = new SearchTemplateRequestBuilder(client)
        .setScript("template_gender")         (1)
        .setScriptType(ScriptType.STORED)     (2)
        .setScriptParams(template_params)     (3)
        .setRequest(new SearchRequest())      (4)
        .get()                                (5)
        .getResponse();                       (6)
  1. template name

  2. template stored in the cluster state

  3. parameters

  4. set the execution context (ie. define the index name here)

  5. execute and get the template response

  6. get from the template response the search response itself

You can also execute inline templates:

sr = new SearchTemplateRequestBuilder(client)
        .setScript("{\n" +                   (1)
                "        \"query\" : {\n" +
                "            \"match\" : {\n" +
                "                \"gender\" : \"{{param_gender}}\"\n" +
                "            }\n" +
                "        }\n" +
                "}")
        .setScriptType(ScriptType.INLINE)    (2)
        .setScriptParams(template_params)    (3)
        .setRequest(new SearchRequest())     (4)
        .get()                               (5)
        .getResponse();                      (6)
  1. template’s body

  2. template is passed inline

  3. parameters

  4. set the execution context (ie. define the index name here)

  5. execute and get the template response

  6. get from the template response the search response itself

Aggregations

Elasticsearch provides a full Java API to play with aggregations. See the {ref}/search-aggregations.html[Aggregations guide].

Use the factory for aggregation builders (AggregationBuilders) and add each aggregation you want to compute when querying and add it to your search request:

SearchResponse sr = node.client().prepareSearch()
        .setQuery( /* your query */ )
        .addAggregation( /* add an aggregation */ )
        .execute().actionGet();

Note that you can add more than one aggregation. See {ref}/search-search.html[Search Java API] for details.

To build aggregation requests, use AggregationBuilders helpers. Just import them in your class:

import org.elasticsearch.search.aggregations.AggregationBuilders;

Structuring aggregations

As explained in the {ref}/search-aggregations.html[Aggregations guide], you can define sub aggregations inside an aggregation.

An aggregation could be a metrics aggregation or a bucket aggregation.

For example, here is a 3 levels aggregation composed of:

  • Terms aggregation (bucket)

  • Date Histogram aggregation (bucket)

  • Average aggregation (metric)

SearchResponse sr = node.client().prepareSearch()
    .addAggregation(
        AggregationBuilders.terms("by_country").field("country")
        .subAggregation(AggregationBuilders.dateHistogram("by_year")
            .field("dateOfBirth")
            .dateHistogramInterval(DateHistogramInterval.YEAR)
            .subAggregation(AggregationBuilders.avg("avg_children").field("children"))
        )
    )
    .execute().actionGet();

Metrics aggregations

Min Aggregation

Here is how you can use {ref}/search-aggregations-metrics-min-aggregation.html[Min Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

MinAggregationBuilder aggregation =
        AggregationBuilders
                .min("agg")
                .field("height");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.min.Min;
// sr is here your SearchResponse object
Min agg = sr.getAggregations().get("agg");
double value = agg.getValue();

Max Aggregation

Here is how you can use {ref}/search-aggregations-metrics-max-aggregation.html[Max Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

MaxAggregationBuilder aggregation =
        AggregationBuilders
                .max("agg")
                .field("height");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.max.Max;
// sr is here your SearchResponse object
Max agg = sr.getAggregations().get("agg");
double value = agg.getValue();

Sum Aggregation

Here is how you can use {ref}/search-aggregations-metrics-sum-aggregation.html[Sum Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

SumAggregationBuilder aggregation =
        AggregationBuilders
                .sum("agg")
                .field("height");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.sum.Sum;
// sr is here your SearchResponse object
Sum agg = sr.getAggregations().get("agg");
double value = agg.getValue();

Avg Aggregation

Here is how you can use {ref}/search-aggregations-metrics-avg-aggregation.html[Avg Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AvgAggregationBuilder aggregation =
        AggregationBuilders
                .avg("agg")
                .field("height");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.avg.Avg;
// sr is here your SearchResponse object
Avg agg = sr.getAggregations().get("agg");
double value = agg.getValue();

Stats Aggregation

Here is how you can use {ref}/search-aggregations-metrics-stats-aggregation.html[Stats Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

StatsAggregationBuilder aggregation =
        AggregationBuilders
                .stats("agg")
                .field("height");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.stats.Stats;
// sr is here your SearchResponse object
Stats agg = sr.getAggregations().get("agg");
double min = agg.getMin();
double max = agg.getMax();
double avg = agg.getAvg();
double sum = agg.getSum();
long count = agg.getCount();

Extended Stats Aggregation

Here is how you can use {ref}/search-aggregations-metrics-extendedstats-aggregation.html[Extended Stats Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

ExtendedStatsAggregationBuilder aggregation =
        AggregationBuilders
                .extendedStats("agg")
                .field("height");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.stats.extended.ExtendedStats;
// sr is here your SearchResponse object
ExtendedStats agg = sr.getAggregations().get("agg");
double min = agg.getMin();
double max = agg.getMax();
double avg = agg.getAvg();
double sum = agg.getSum();
long count = agg.getCount();
double stdDeviation = agg.getStdDeviation();
double sumOfSquares = agg.getSumOfSquares();
double variance = agg.getVariance();

Value Count Aggregation

Here is how you can use {ref}/search-aggregations-metrics-valuecount-aggregation.html[Value Count Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

ValueCountAggregationBuilder aggregation =
        AggregationBuilders
                .count("agg")
                .field("height");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.valuecount.ValueCount;
// sr is here your SearchResponse object
ValueCount agg = sr.getAggregations().get("agg");
long value = agg.getValue();

Percentile Aggregation

Here is how you can use {ref}/search-aggregations-metrics-percentile-aggregation.html[Percentile Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

PercentilesAggregationBuilder aggregation =
        AggregationBuilders
                .percentiles("agg")
                .field("height");

You can provide your own percentiles instead of using defaults:

PercentilesAggregationBuilder aggregation =
        AggregationBuilders
                .percentiles("agg")
                .field("height")
                .percentiles(1.0, 5.0, 10.0, 20.0, 30.0, 75.0, 95.0, 99.0);
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.percentiles.Percentile;
import org.elasticsearch.search.aggregations.metrics.percentiles.Percentiles;
// sr is here your SearchResponse object
Percentiles agg = sr.getAggregations().get("agg");
// For each entry
for (Percentile entry : agg) {
    double percent = entry.getPercent();    // Percent
    double value = entry.getValue();        // Value

    logger.info("percent [{}], value [{}]", percent, value);
}

This will basically produce for the first example:

percent [1.0], value [0.814338896154595]
percent [5.0], value [0.8761912455821302]
percent [25.0], value [1.173346540141847]
percent [50.0], value [1.5432023318692198]
percent [75.0], value [1.923915462033674]
percent [95.0], value [2.2273644908535335]
percent [99.0], value [2.284989339108279]

Percentile Ranks Aggregation

Here is how you can use {ref}/search-aggregations-metrics-percentile-rank-aggregation.html[Percentile Ranks Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

PercentileRanksAggregationBuilder aggregation =
        AggregationBuilders
                .percentileRanks("agg")
                .field("height")
                .values(1.24, 1.91, 2.22);
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.percentiles.Percentile;
import org.elasticsearch.search.aggregations.metrics.percentiles.PercentileRanks;
// sr is here your SearchResponse object
PercentileRanks agg = sr.getAggregations().get("agg");
// For each entry
for (Percentile entry : agg) {
    double percent = entry.getPercent();    // Percent
    double value = entry.getValue();        // Value

    logger.info("percent [{}], value [{}]", percent, value);
}

This will basically produce:

percent [29.664353095090945], value [1.24]
percent [73.9335313461868], value [1.91]
percent [94.40095147327283], value [2.22]

Cardinality Aggregation

Here is how you can use {ref}/search-aggregations-metrics-cardinality-aggregation.html[Cardinality Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

CardinalityAggregationBuilder aggregation =
        AggregationBuilders
                .cardinality("agg")
                .field("tags");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.cardinality.Cardinality;
// sr is here your SearchResponse object
Cardinality agg = sr.getAggregations().get("agg");
long value = agg.getValue();

Geo Bounds Aggregation

Here is how you can use {ref}/search-aggregations-metrics-geobounds-aggregation.html[Geo Bounds Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

GeoBoundsBuilder aggregation =
        GeoBoundsAggregationBuilder
                .geoBounds("agg")
                .field("address.location")
                .wrapLongitude(true);
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.metrics.geobounds.GeoBounds;
// sr is here your SearchResponse object
GeoBounds agg = sr.getAggregations().get("agg");
GeoPoint bottomRight = agg.bottomRight();
GeoPoint topLeft = agg.topLeft();
logger.info("bottomRight {}, topLeft {}", bottomRight, topLeft);

This will basically produce:

bottomRight [40.70500764381921, 13.952946866893775], topLeft [53.49603022435221, -4.190029308156676]

Top Hits Aggregation

Here is how you can use {ref}/search-aggregations-metrics-top-hits-aggregation.html[Top Hits Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
    AggregationBuilders
        .terms("agg").field("gender")
        .subAggregation(
            AggregationBuilders.topHits("top")
        );

You can use most of the options available for standard search such as from, size, sort, highlight, explain…​

AggregationBuilder aggregation =
    AggregationBuilders
        .terms("agg").field("gender")
        .subAggregation(
            AggregationBuilders.topHits("top")
                .explain(true)
                .size(1)
                .from(10)
        );
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.terms.Terms;
import org.elasticsearch.search.aggregations.metrics.tophits.TopHits;
// sr is here your SearchResponse object
Terms agg = sr.getAggregations().get("agg");

// For each entry
for (Terms.Bucket entry : agg.getBuckets()) {
    String key = entry.getKey();                    // bucket key
    long docCount = entry.getDocCount();            // Doc count
    logger.info("key [{}], doc_count [{}]", key, docCount);

    // We ask for top_hits for each bucket
    TopHits topHits = entry.getAggregations().get("top");
    for (SearchHit hit : topHits.getHits().getHits()) {
        logger.info(" -> id [{}], _source [{}]", hit.getId(), hit.getSourceAsString());
    }
}

This will basically produce for the first example:

key [male], doc_count [5107]
 -> id [AUnzSZze9k7PKXtq04x2], _source [{"gender":"male",...}]
 -> id [AUnzSZzj9k7PKXtq04x4], _source [{"gender":"male",...}]
 -> id [AUnzSZzl9k7PKXtq04x5], _source [{"gender":"male",...}]
key [female], doc_count [4893]
 -> id [AUnzSZzM9k7PKXtq04xy], _source [{"gender":"female",...}]
 -> id [AUnzSZzp9k7PKXtq04x8], _source [{"gender":"female",...}]
 -> id [AUnzSZ0W9k7PKXtq04yS], _source [{"gender":"female",...}]

Scripted Metric Aggregation

Here is how you can use {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Scripted Metric Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

ScriptedMetricAggregationBuilder aggregation = AggregationBuilders
    .scriptedMetric("agg")
    .initScript(new Script("state.heights = []"))
    .mapScript(new Script("state.heights.add(doc.gender.value == 'male' ? doc.height.value : -1.0 * doc.height.value)"));

You can also specify a combine script which will be executed on each shard:

ScriptedMetricAggregationBuilder aggregation = AggregationBuilders
    .scriptedMetric("agg")
    .initScript(new Script("state.heights = []"))
    .mapScript(new Script("state.heights.add(doc.gender.value == 'male' ? doc.height.value : -1.0 * doc.height.value)"))
    .combineScript(new Script("double heights_sum = 0.0; for (t in state.heights) { heights_sum += t } return heights_sum"));

You can also specify a reduce script which will be executed on the node which gets the request:

ScriptedMetricAggregationBuilder aggregation = AggregationBuilders
    .scriptedMetric("agg")
    .initScript(new Script("state.heights = []"))
    .mapScript(new Script("state.heights.add(doc.gender.value == 'male' ? doc.height.value : -1.0 * doc.height.value)"))
    .combineScript(new Script("double heights_sum = 0.0; for (t in state.heights) { heights_sum += t } return heights_sum"))
    .reduceScript(new Script("double heights_sum = 0.0; for (a in states) { heights_sum += a } return heights_sum"));
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.terms.Terms;
import org.elasticsearch.search.aggregations.metrics.tophits.TopHits;
// sr is here your SearchResponse object
ScriptedMetric agg = sr.getAggregations().get("agg");
Object scriptedResult = agg.aggregation();
logger.info("scriptedResult [{}]", scriptedResult);

Note that the result depends on the script you built. For the first example, this will basically produce:

scriptedResult object [ArrayList]
scriptedResult [ {
"heights" : [ 1.122218480146643, -1.8148918111233887, -1.7626731575142909, ... ]
}, {
"heights" : [ -0.8046067304119863, -2.0785486707864553, -1.9183567430207953, ... ]
}, {
"heights" : [ 2.092635728868694, 1.5697545960886536, 1.8826954461968808, ... ]
}, {
"heights" : [ -2.1863201099468403, 1.6328549117346856, -1.7078288405893842, ... ]
}, {
"heights" : [ 1.6043904836424177, -2.0736538674414025, 0.9898266674373053, ... ]
} ]

The second example will produce:

scriptedResult object [ArrayList]
scriptedResult [-41.279615707402876,
                -60.88007362339038,
                38.823270659734256,
                14.840192739445632,
                11.300902755741326]

The last example will produce:

scriptedResult object [Double]
scriptedResult [2.171917696507009]

Bucket aggregations

Global Aggregation

Here is how you can use {ref}/search-aggregations-bucket-global-aggregation.html[Global Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilders
    .global("agg")
    .subAggregation(AggregationBuilders.terms("genders").field("gender"));
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.global.Global;
// sr is here your SearchResponse object
Global agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Filter Aggregation

Here is how you can use {ref}/search-aggregations-bucket-filter-aggregation.html[Filter Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilders
    .filter("agg", QueryBuilders.termQuery("gender", "male"));
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.filter.Filter;
// sr is here your SearchResponse object
Filter agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Filters Aggregation

Here is how you can use {ref}/search-aggregations-bucket-filters-aggregation.html[Filters Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
    AggregationBuilders
        .filters("agg",
            new FiltersAggregator.KeyedFilter("men", QueryBuilders.termQuery("gender", "male")),
            new FiltersAggregator.KeyedFilter("women", QueryBuilders.termQuery("gender", "female")));
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.filters.Filters;
// sr is here your SearchResponse object
Filters agg = sr.getAggregations().get("agg");

// For each entry
for (Filters.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();            // bucket key
    long docCount = entry.getDocCount();            // Doc count
    logger.info("key [{}], doc_count [{}]", key, docCount);
}

This will basically produce:

key [men], doc_count [4982]
key [women], doc_count [5018]

Missing Aggregation

Here is how you can use {ref}/search-aggregations-bucket-missing-aggregation.html[Missing Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilders.missing("agg").field("gender");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.missing.Missing;
// sr is here your SearchResponse object
Missing agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Nested Aggregation

Here is how you can use {ref}/search-aggregations-bucket-nested-aggregation.html[Nested Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilders
    .nested("agg", "resellers");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.nested.Nested;
// sr is here your SearchResponse object
Nested agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Reverse Nested Aggregation

Here is how you can use {ref}/search-aggregations-bucket-reverse-nested-aggregation.html[Reverse Nested Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
    AggregationBuilders
        .nested("agg", "resellers")
        .subAggregation(
                AggregationBuilders
                        .terms("name").field("resellers.name")
                        .subAggregation(
                                AggregationBuilders
                                        .reverseNested("reseller_to_product")
                        )
        );
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.nested.Nested;
import org.elasticsearch.search.aggregations.bucket.nested.ReverseNested;
import org.elasticsearch.search.aggregations.bucket.terms.Terms;
// sr is here your SearchResponse object
Nested agg = sr.getAggregations().get("agg");
Terms name = agg.getAggregations().get("name");
for (Terms.Bucket bucket : name.getBuckets()) {
    ReverseNested resellerToProduct = bucket.getAggregations().get("reseller_to_product");
    resellerToProduct.getDocCount(); // Doc count
}

Children Aggregation

Here is how you can use {ref}/search-aggregations-bucket-children-aggregation.html[Children Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
    AggregationBuilders
        .children("agg", "reseller"); (1)
  1. "agg" is the name of the aggregation and "reseller" is the child type

Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.join.aggregations.Children;
// sr is here your SearchResponse object
Children agg = sr.getAggregations().get("agg");
agg.getDocCount(); // Doc count

Terms Aggregation

Here is how you can use {ref}/search-aggregations-bucket-terms-aggregation.html[Terms Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilders
    .terms("genders")
    .field("gender");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.terms.Terms;
// sr is here your SearchResponse object
Terms genders = sr.getAggregations().get("genders");

// For each entry
for (Terms.Bucket entry : genders.getBuckets()) {
    entry.getKey();      // Term
    entry.getDocCount(); // Doc count
}
Order

Import bucket ordering strategy classes:

import org.elasticsearch.search.aggregations.BucketOrder;

Ordering the buckets by their doc_count in an ascending manner:

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.count(true))

Ordering the buckets alphabetically by their terms in an ascending manner:

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.key(true))

Ordering the buckets by single value metrics sub-aggregation (identified by the aggregation name):

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.aggregation("avg_height", false))
    .subAggregation(
        AggregationBuilders.avg("avg_height").field("height")
    )

Ordering the buckets by multiple criteria:

AggregationBuilders
    .terms("genders")
    .field("gender")
    .order(BucketOrder.compound( // in order of priority:
        BucketOrder.aggregation("avg_height", false), // sort by sub-aggregation first
        BucketOrder.count(true))) // then bucket count as a tie-breaker
    .subAggregation(
        AggregationBuilders.avg("avg_height").field("height")
    )

Significant Terms Aggregation

Here is how you can use {ref}/search-aggregations-bucket-significantterms-aggregation.html[Significant Terms Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .significantTerms("significant_countries")
                .field("address.country");

// Let say you search for men only
SearchResponse sr = client.prepareSearch()
        .setQuery(QueryBuilders.termQuery("gender", "male"))
        .addAggregation(aggregation)
        .get();
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.significant.SignificantTerms;
// sr is here your SearchResponse object
SignificantTerms agg = sr.getAggregations().get("significant_countries");

// For each entry
for (SignificantTerms.Bucket entry : agg.getBuckets()) {
    entry.getKey();      // Term
    entry.getDocCount(); // Doc count
}

Range Aggregation

Here is how you can use {ref}/search-aggregations-bucket-range-aggregation.html[Range Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .range("agg")
                .field("height")
                .addUnboundedTo(1.0f)               // from -infinity to 1.0 (excluded)
                .addRange(1.0f, 1.5f)               // from 1.0 to 1.5 (excluded)
                .addUnboundedFrom(1.5f);            // from 1.5 to +infinity
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();             // Range as key
    Number from = (Number) entry.getFrom();          // Bucket from
    Number to = (Number) entry.getTo();              // Bucket to
    long docCount = entry.getDocCount();    // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, from, to, docCount);
}

This will basically produce for the first example:

key [*-1.0], from [-Infinity], to [1.0], doc_count [9]
key [1.0-1.5], from [1.0], to [1.5], doc_count [21]
key [1.5-*], from [1.5], to [Infinity], doc_count [20]

Date Range Aggregation

Here is how you can use {ref}/search-aggregations-bucket-daterange-aggregation.html[Date Range Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .dateRange("agg")
                .field("dateOfBirth")
                .format("yyyy")
                .addUnboundedTo("1950")    // from -infinity to 1950 (excluded)
                .addRange("1950", "1960")  // from 1950 to 1960 (excluded)
                .addUnboundedFrom("1960"); // from 1960 to +infinity
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();                // Date range as key
    DateTime fromAsDate = (DateTime) entry.getFrom();   // Date bucket from as a Date
    DateTime toAsDate = (DateTime) entry.getTo();       // Date bucket to as a Date
    long docCount = entry.getDocCount();                // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, fromAsDate, toAsDate, docCount);
}

This will basically produce:

key [*-1950], from [null], to [1950-01-01T00:00:00.000Z], doc_count [8]
key [1950-1960], from [1950-01-01T00:00:00.000Z], to [1960-01-01T00:00:00.000Z], doc_count [5]
key [1960-*], from [1960-01-01T00:00:00.000Z], to [null], doc_count [37]

Ip Range Aggregation

Here is how you can use {ref}/search-aggregations-bucket-iprange-aggregation.html[Ip Range Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregatorBuilder<?> aggregation =
        AggregationBuilders
                .ipRange("agg")
                .field("ip")
                .addUnboundedTo("192.168.1.0")             // from -infinity to 192.168.1.0 (excluded)
                .addRange("192.168.1.0", "192.168.2.0")    // from 192.168.1.0 to 192.168.2.0 (excluded)
                .addUnboundedFrom("192.168.2.0");          // from 192.168.2.0 to +infinity

Note that you could also use ip masks as ranges:

AggregatorBuilder<?> aggregation =
        AggregationBuilders
                .ipRange("agg")
                .field("ip")
                .addMaskRange("192.168.0.0/32")
                .addMaskRange("192.168.0.0/24")
                .addMaskRange("192.168.0.0/16");
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();            // Ip range as key
    String fromAsString = entry.getFromAsString();  // Ip bucket from as a String
    String toAsString = entry.getToAsString();      // Ip bucket to as a String
    long docCount = entry.getDocCount();            // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, fromAsString, toAsString, docCount);
}

This will basically produce for the first example:

key [*-192.168.1.0], from [null], to [192.168.1.0], doc_count [13]
key [192.168.1.0-192.168.2.0], from [192.168.1.0], to [192.168.2.0], doc_count [14]
key [192.168.2.0-*], from [192.168.2.0], to [null], doc_count [23]

And for the second one (using Ip masks):

key [192.168.0.0/32], from [192.168.0.0], to [192.168.0.1], doc_count [0]
key [192.168.0.0/24], from [192.168.0.0], to [192.168.1.0], doc_count [13]
key [192.168.0.0/16], from [192.168.0.0], to [192.169.0.0], doc_count [50]

Histogram Aggregation

Here is how you can use {ref}/search-aggregations-bucket-histogram-aggregation.html[Histogram Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .histogram("agg")
                .field("height")
                .interval(1);
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.histogram.Histogram;
// sr is here your SearchResponse object
Histogram agg = sr.getAggregations().get("agg");

// For each entry
for (Histogram.Bucket entry : agg.getBuckets()) {
    Number key = (Number) entry.getKey();   // Key
    long docCount = entry.getDocCount();    // Doc count

    logger.info("key [{}], doc_count [{}]", key, docCount);
}
Order

Supports the same order functionality as the Terms Aggregation.

Date Histogram Aggregation

Here is how you can use {ref}/search-aggregations-bucket-datehistogram-aggregation.html[Date Histogram Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .dateHistogram("agg")
                .field("dateOfBirth")
                .dateHistogramInterval(DateHistogramInterval.YEAR);

Or if you want to set an interval of 10 days:

AggregationBuilder aggregation =
        AggregationBuilders
                .dateHistogram("agg")
                .field("dateOfBirth")
                .dateHistogramInterval(DateHistogramInterval.days(10));
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.histogram.Histogram;
// sr is here your SearchResponse object
Histogram agg = sr.getAggregations().get("agg");

// For each entry
for (Histogram.Bucket entry : agg.getBuckets()) {
    DateTime key = (DateTime) entry.getKey();    // Key
    String keyAsString = entry.getKeyAsString(); // Key as String
    long docCount = entry.getDocCount();         // Doc count

    logger.info("key [{}], date [{}], doc_count [{}]", keyAsString, key.getYear(), docCount);
}

This will basically produce for the first example:

key [1942-01-01T00:00:00.000Z], date [1942], doc_count [1]
key [1945-01-01T00:00:00.000Z], date [1945], doc_count [1]
key [1946-01-01T00:00:00.000Z], date [1946], doc_count [1]
...
key [2005-01-01T00:00:00.000Z], date [2005], doc_count [1]
key [2007-01-01T00:00:00.000Z], date [2007], doc_count [2]
key [2008-01-01T00:00:00.000Z], date [2008], doc_count [3]
Order

Supports the same order functionality as the Terms Aggregation.

Geo Distance Aggregation

Here is how you can use {ref}/search-aggregations-bucket-geodistance-aggregation.html[Geo Distance Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .geoDistance("agg", new GeoPoint(48.84237171118314,2.33320027692004))
                .field("address.location")
                .unit(DistanceUnit.KILOMETERS)
                .addUnboundedTo(3.0)
                .addRange(3.0, 10.0)
                .addRange(10.0, 500.0);
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.range.Range;
// sr is here your SearchResponse object
Range agg = sr.getAggregations().get("agg");

// For each entry
for (Range.Bucket entry : agg.getBuckets()) {
    String key = entry.getKeyAsString();    // key as String
    Number from = (Number) entry.getFrom(); // bucket from value
    Number to = (Number) entry.getTo();     // bucket to value
    long docCount = entry.getDocCount();    // Doc count

    logger.info("key [{}], from [{}], to [{}], doc_count [{}]", key, from, to, docCount);
}

This will basically produce:

key [*-3.0], from [0.0], to [3.0], doc_count [161]
key [3.0-10.0], from [3.0], to [10.0], doc_count [460]
key [10.0-500.0], from [10.0], to [500.0], doc_count [4925]

Geo Hash Grid Aggregation

Here is how you can use {ref}/search-aggregations-bucket-geohashgrid-aggregation.html[Geo Hash Grid Aggregation] with Java API.

Prepare aggregation request

Here is an example on how to create the aggregation request:

AggregationBuilder aggregation =
        AggregationBuilders
                .geohashGrid("agg")
                .field("address.location")
                .precision(4);
Use aggregation response

Import Aggregation definition classes:

import org.elasticsearch.search.aggregations.bucket.geogrid.GeoHashGrid;
// sr is here your SearchResponse object
GeoHashGrid agg = sr.getAggregations().get("agg");

// For each entry
for (GeoHashGrid.Bucket entry : agg.getBuckets()) {
    String keyAsString = entry.getKeyAsString(); // key as String
    GeoPoint key = (GeoPoint) entry.getKey();    // key as geo point
    long docCount = entry.getDocCount();         // Doc count

    logger.info("key [{}], point {}, doc_count [{}]", keyAsString, key, docCount);
}

This will basically produce:

key [gbqu], point [47.197265625, -1.58203125], doc_count [1282]
key [gbvn], point [50.361328125, -4.04296875], doc_count [1248]
key [u1j0], point [50.712890625, 7.20703125], doc_count [1156]
key [u0j2], point [45.087890625, 7.55859375], doc_count [1138]
...

Query DSL

Elasticsearch provides a full Java query dsl in a similar manner to the REST {ref}/query-dsl.html[Query DSL]. The factory for query builders is QueryBuilders. Once your query is ready, you can use the Search API.

To use QueryBuilders just import them in your class:

import static org.elasticsearch.index.query.QueryBuilders.*;

Note that you can easily print (aka debug) JSON generated queries using toString() method on QueryBuilder object.

The QueryBuilder can then be used with any API that accepts a query, such as count and search.

Match All Query

See {ref}/query-dsl-match-all-query.html[Match All Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[match_all]

Full text queries

The high-level full text queries are usually used for running full text queries on full text fields like the body of an email. They understand how the field being queried is analyzed and will apply each field’s analyzer (or search_analyzer) to the query string before executing.

The queries in this group are:

match query

The standard query for performing full text queries, including fuzzy matching and phrase or proximity queries.

multi_match query

The multi-field version of the match query.

common_terms query

A more specialized query which gives more preference to uncommon words.

query_string query

Supports the compact Lucene query string syntax, allowing you to specify AND|OR|NOT conditions and multi-field search within a single query string. For expert users only.

simple_query_string

A simpler, more robust version of the query_string syntax suitable for exposing directly to users.

Match Query

See {ref}/query-dsl-match-query.html[Match Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[match]
  1. field

  2. text

Multi Match Query

See {ref}/query-dsl-multi-match-query.html[Multi Match Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[multi_match]
  1. text

  2. fields

Common Terms Query

See {ref}/query-dsl-common-terms-query.html[Common Terms Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[common_terms]
  1. field

  2. value

Query String Query

See {ref}/query-dsl-query-string-query.html[Query String Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[query_string]

Simple Query String Query

See {ref}/query-dsl-simple-query-string-query.html[Simple Query String Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[simple_query_string]

Term level queries

While the full text queries will analyze the query string before executing, the term-level queries operate on the exact terms that are stored in the inverted index.

These queries are usually used for structured data like numbers, dates, and enums, rather than full text fields. Alternatively, they allow you to craft low-level queries, foregoing the analysis process.

The queries in this group are:

term query

Find documents which contain the exact term specified in the field specified.

terms query

Find documents which contain any of the exact terms specified in the field specified.

range query

Find documents where the field specified contains values (dates, numbers, or strings) in the range specified.

exists query

Find documents where the field specified contains any non-null value.

prefix query

Find documents where the field specified contains terms which being with the exact prefix specified.

wildcard query

Find documents where the field specified contains terms which match the pattern specified, where the pattern supports single character wildcards (?) and multi-character wildcards (*)

regexp query

Find documents where the field specified contains terms which match the regular expression specified.

fuzzy query

Find documents where the field specified contains terms which are fuzzily similar to the specified term. Fuzziness is measured as a Levenshtein edit distance of 1 or 2.

type query

Find documents of the specified type.

ids query

Find documents with the specified type and IDs.

Term Query

See {ref}/query-dsl-term-query.html[Term Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[term]
  1. field

  2. text

Terms Query

See {ref}/query-dsl-terms-query.html[Terms Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[terms]
  1. field

  2. values

Range Query

See {ref}/query-dsl-range-query.html[Range Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[range]
  1. field

  2. from

  3. to

  4. include lower value means that from is gt when false or gte when true

  5. include upper value means that to is lt when false or lte when true

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[range_simplified]
  1. field

  2. set from to 10 and includeLower to true

  3. set to to 20 and includeUpper to false

Exists Query

See {ref}/query-dsl-exists-query.html[Exists Query].

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[exists]
  1. field

Prefix Query

See {ref}/query-dsl-prefix-query.html[Prefix Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[prefix]
  1. field

  2. prefix

Wildcard Query

See {ref}/query-dsl-wildcard-query.html[Wildcard Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[wildcard]
  1. field

  2. wildcard expression

Regexp Query

See {ref}/query-dsl-regexp-query.html[Regexp Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[regexp]
  1. field

  2. regexp

Fuzzy Query

See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[fuzzy]
  1. field

  2. text

Type Query

See {ref}/query-dsl-type-query.html[Type Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[type]
  1. type

Ids Query

See {ref}/query-dsl-ids-query.html[Ids Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[ids]
  1. type is optional

Compound queries

Compound queries wrap other compound or leaf queries, either to combine their results and scores, to change their behaviour, or to switch from query to filter context.

The queries in this group are:

constant_score query

A query which wraps another query, but executes it in filter context. All matching documents are given the same `constant'' `_score.

bool query

The default query for combining multiple leaf or compound query clauses, as must, should, must_not, or filter clauses. The must and should clauses have their scores combined — the more matching clauses, the better — while the must_not and filter clauses are executed in filter context.

dis_max query

A query which accepts multiple queries, and returns any documents which match any of the query clauses. While the bool query combines the scores from all matching queries, the dis_max query uses the score of the single best- matching query clause.

function_score query

Modify the scores returned by the main query with functions to take into account factors like popularity, recency, distance, or custom algorithms implemented with scripting.

boosting query

Return documents which match a positive query, but reduce the score of documents which also match a negative query.

Constant Score Query

See {ref}/query-dsl-constant-score-query.html[Constant Score Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[constant_score]
  1. your query

  2. query score ==== Bool Query

See {ref}/query-dsl-bool-query.html[Bool Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[bool]
  1. must query

  2. must not query

  3. should query

  4. a query that must appear in the matching documents but doesn’t contribute to scoring. ==== Dis Max Query

See {ref}/query-dsl-dis-max-query.html[Dis Max Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[dis_max]
  1. add your queries

  2. add your queries

  3. boost factor

  4. tie breaker ==== Function Score Query

See {ref}/query-dsl-function-score-query.html[Function Score Query].

To use ScoreFunctionBuilders just import them in your class:

import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.*;
include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[function_score]
  1. Add a first function based on a query

  2. And randomize the score based on a given seed

  3. Add another function based on the age field ==== Boosting Query

See {ref}/query-dsl-boosting-query.html[Boosting Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[boosting]
  1. query that will promote documents

  2. query that will demote documents

  3. negative boost

Joining queries

Performing full SQL-style joins in a distributed system like Elasticsearch is prohibitively expensive. Instead, Elasticsearch offers two forms of join which are designed to scale horizontally.

nested query

Documents may contains fields of type nested. These fields are used to index arrays of objects, where each object can be queried (with the nested query) as an independent document.

has_child and has_parent queries

A parent-child relationship can exist between two document types within a single index. The has_child query returns parent documents whose child documents match the specified query, while the has_parent query returns child documents whose parent document matches the specified query.

Nested Query

See {ref}/query-dsl-nested-query.html[Nested Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[nested]
  1. path to nested document

  2. your query. Any fields referenced inside the query must use the complete path (fully qualified).

  3. score mode could be ScoreMode.Max, ScoreMode.Min, ScoreMode.Total, ScoreMode.Avg or ScoreMode.None

Has Child Query

See {ref}/query-dsl-has-child-query.html[Has Child Query]

When using the has_child query it is important to use the PreBuiltTransportClient instead of the regular client:

Settings settings = Settings.builder().put("cluster.name", "elasticsearch").build();
TransportClient client = new PreBuiltTransportClient(settings);
client.addTransportAddress(new TransportAddress(new InetSocketAddress(InetAddresses.forString("127.0.0.1"), 9300)));

Otherwise the parent-join module doesn’t get loaded and the has_child query can’t be used from the transport client.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[has_child]
  1. child type to query against

  2. query

  3. score mode can be ScoreMode.Avg, ScoreMode.Max, ScoreMode.Min, ScoreMode.None or ScoreMode.Total

Has Parent Query

See {ref}/query-dsl-has-parent-query.html[Has Parent]

When using the has_parent query it is important to use the PreBuiltTransportClient instead of the regular client:

Settings settings = Settings.builder().put("cluster.name", "elasticsearch").build();
TransportClient client = new PreBuiltTransportClient(settings);
client.addTransportAddress(new TransportAddress(new InetSocketAddress(InetAddresses.forString("127.0.0.1"), 9300)));

Otherwise the parent-join module doesn’t get loaded and the has_parent query can’t be used from the transport client.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[has_parent]
  1. parent type to query against

  2. query

  3. whether the score from the parent hit should propagate to the child hit

Geo queries

Elasticsearch supports two types of geo data: geo_point fields which support lat/lon pairs, and geo_shape fields, which support points, lines, circles, polygons, multi-polygons etc.

The queries in this group are:

geo_shape query

Find document with geo-shapes which either intersect, are contained by, or do not intersect with the specified geo-shape.

geo_bounding_box query

Finds documents with geo-points that fall into the specified rectangle.

geo_distance query

Finds document with geo-points within the specified distance of a central point.

geo_polygon query

Find documents with geo-points within the specified polygon.

GeoShape Query

See {ref}/query-dsl-geo-shape-query.html[Geo Shape Query]

Note: the geo_shape type uses Spatial4J and JTS, both of which are optional dependencies. Consequently you must add Spatial4J and JTS to your classpath in order to use this type:

<dependency>
    <groupId>org.locationtech.spatial4j</groupId>
    <artifactId>spatial4j</artifactId>
    <version>0.7</version>                        (1)
</dependency>

<dependency>
    <groupId>org.locationtech.jts</groupId>
    <artifactId>jts-core</artifactId>
    <version>1.15.0</version>                         (2)
    <exclusions>
        <exclusion>
            <groupId>xerces</groupId>
            <artifactId>xercesImpl</artifactId>
        </exclusion>
    </exclusions>
</dependency>
  1. check for updates in Maven Central

  2. check for updates in Maven Central

// Import ShapeRelation and ShapeBuilder
import org.elasticsearch.common.geo.ShapeRelation;
import org.elasticsearch.common.geo.builders.ShapeBuilder;
include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[geo_shape]
  1. field

  2. shape

  3. relation can be ShapeRelation.CONTAINS, ShapeRelation.WITHIN, ShapeRelation.INTERSECTS or ShapeRelation.DISJOINT

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[indexed_geo_shape]
  1. field

  2. The ID of the document that containing the pre-indexed shape.

  3. Index type where the pre-indexed shape is.

  4. relation

  5. Name of the index where the pre-indexed shape is. Defaults to 'shapes'.

  6. The field specified as path containing the pre-indexed shape. Defaults to 'shape'.

Geo Bounding Box Query

See {ref}/query-dsl-geo-bounding-box-query.html[Geo Bounding Box Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[geo_bounding_box]
  1. field

  2. bounding box top left point

  3. bounding box bottom right point

Geo Distance Query

See {ref}/query-dsl-geo-distance-query.html[Geo Distance Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[geo_distance]
  1. field

  2. center point

  3. distance from center point

Geo Polygon Query

See {ref}/query-dsl-geo-polygon-query.html[Geo Polygon Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[geo_polygon]
  1. add your polygon of points a document should fall within

  2. initialise the query with field and points

Specialized queries

This group contains queries which do not fit into the other groups:

more_like_this query

This query finds documents which are similar to the specified text, document, or collection of documents.

script query

This query allows a script to act as a filter. Also see the function_score query.

percolate query

This query finds percolator queries based on documents.

wrapper query

A query that accepts other queries as json or yaml string.

More Like This Query

See {ref}/query-dsl-mlt-query.html[More Like This Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[more_like_this]
  1. fields

  2. text

  3. ignore threshold

  4. max num of Terms in generated queries

Script Query

See {ref}/query-dsl-script-query.html[Script Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[script_inline]
  1. inlined script

If you have stored on each data node a script named myscript.painless with:

doc['num1'].value > params.param1

You can use it then with:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[script_file]
  1. Script type: either ScriptType.FILE, ScriptType.INLINE or ScriptType.INDEXED

  2. Scripting engine

  3. Script name

  4. Parameters as a Map<String, Object>

Percolate Query

See: * {ref}/query-dsl-percolate-query.html[Percolate Query]

Settings settings = Settings.builder().put("cluster.name", "elasticsearch").build();
TransportClient client = new PreBuiltTransportClient(settings);
client.addTransportAddress(new TransportAddress(new InetSocketAddress(InetAddresses.forString("127.0.0.1"), 9300)));

Before the percolate query can be used an percolator mapping should be added and a document containing a percolator query should be indexed:

// create an index with a percolator field with the name 'query':
client.admin().indices().prepareCreate("myIndexName")
                        .addMapping("_doc", "query", "type=percolator", "content", "type=text")
                        .get();

//This is the query we're registering in the percolator
QueryBuilder qb = termQuery("content", "amazing");

//Index the query = register it in the percolator
client.prepareIndex("myIndexName", "_doc", "myDesignatedQueryName")
    .setSource(jsonBuilder()
        .startObject()
            .field("query", qb) // Register the query
        .endObject())
    .setRefreshPolicy(RefreshPolicy.IMMEDIATE) // Needed when the query shall be available immediately
    .get();

This indexes the above term query under the name myDesignatedQueryName.

In order to check a document against the registered queries, use this code:

//Build a document to check against the percolator
XContentBuilder docBuilder = XContentFactory.jsonBuilder().startObject();
docBuilder.field("content", "This is amazing!");
docBuilder.endObject(); //End of the JSON root object

PercolateQueryBuilder percolateQuery = new PercolateQueryBuilder("query", "_doc", BytesReference.bytes(docBuilder));

// Percolate, by executing the percolator query in the query dsl:
SearchResponse response = client().prepareSearch("myIndexName")
        .setQuery(percolateQuery))
        .get();
//Iterate over the results
for(SearchHit hit : response.getHits()) {
    // Percolator queries as hit
}

Wrapper Query

See {ref}/query-dsl-wrapper-query.html[Wrapper Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[wrapper]
  1. query defined as query builder

Span queries

Span queries are low-level positional queries which provide expert control over the order and proximity of the specified terms. These are typically used to implement very specific queries on legal documents or patents.

Span queries cannot be mixed with non-span queries (with the exception of the span_multi query).

The queries in this group are:

span_term query

The equivalent of the term query but for use with other span queries.

span_multi query

Wraps a term, range, prefix, wildcard, regexp, or fuzzy query.

span_first query

Accepts another span query whose matches must appear within the first N positions of the field.

span_near query

Accepts multiple span queries whose matches must be within the specified distance of each other, and possibly in the same order.

span_or query

Combines multiple span queries — returns documents which match any of the specified queries.

span_not query

Wraps another span query, and excludes any documents which match that query.

span_containing query

Accepts a list of span queries, but only returns those spans which also match a second span query.

span_within query

The result from a single span query is returned as long is its span falls within the spans returned by a list of other span queries.

Span Term Query

See {ref}/query-dsl-span-term-query.html[Span Term Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_term]
  1. field

  2. value

Span Multi Term Query

See {ref}/query-dsl-span-multi-term-query.html[Span Multi Term Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_multi]
  1. Can be any builder extending the MultiTermQueryBuilder class. For example: FuzzyQueryBuilder, PrefixQueryBuilder, RangeQueryBuilder, RegexpQueryBuilder or WildcardQueryBuilder.

Span First Query

See {ref}/query-dsl-span-first-query.html[Span First Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_first]
  1. query

  2. max end position

Span Near Query

See {ref}/query-dsl-span-near-query.html[Span Near Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_near]
  1. span term queries

  2. slop factor: the maximum number of intervening unmatched positions

  3. whether matches are required to be in-order

Span Or Query

See {ref}/query-dsl-span-or-query.html[Span Or Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_or]
  1. span term queries

Span Not Query

See {ref}/query-dsl-span-not-query.html[Span Not Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_not]
  1. span query whose matches are filtered

  2. span query whose matches must not overlap those returned

Span Containing Query

See {ref}/query-dsl-span-containing-query.html[Span Containing Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_containing]
  1. big part

  2. little part

Span Within Query

See {ref}/query-dsl-span-within-query.html[Span Within Query]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/QueryDSLDocumentationTests.java[span_within]
  1. big part

  2. little part

Java API Administration

Elasticsearch provides a full Java API to deal with administration tasks.

To access them, you need to call admin() method from a client to get an AdminClient:

AdminClient adminClient = client.admin();
Note
In the rest of this guide, we will use client.admin().

Indices Administration

To access indices Java API, you need to call indices() method from an AdminClient:

IndicesAdminClient indicesAdminClient = client.admin().indices();
Note
In the rest of this guide, we will use client.admin().indices().

Create Index

Using an IndicesAdminClient, you can create an index with all default settings and no mapping:

client.admin().indices().prepareCreate("twitter").get();
Index Settings

Each index created can have specific settings associated with it.

client.admin().indices().prepareCreate("twitter")
        .setSettings(Settings.builder()             (1)
                .put("index.number_of_shards", 3)
                .put("index.number_of_replicas", 2)
        )
        .get();                                     (2)
  1. Settings for this index

  2. Execute the action and wait for the result

Put Mapping

You can add mappings at index creation time:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../server/src/test/java/org/elasticsearch/client/documentation/IndicesDocumentationIT.java[index-with-mapping]
  1. Creates an index called twitter

  2. Add a _doc type with a field called message that has the datatype text.

There are several variants of the above addMapping method, some taking an XContentBuilder or a Map with the mapping definition as arguments. Make sure to check the javadocs to pick the simplest one for your use case.

The PUT mapping API also allows for updating the mapping after index creation. In this case you can provide the mapping as a String similar to the REST API syntax:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-api/../../server/src/test/java/org/elasticsearch/client/documentation/IndicesDocumentationIT.java[putMapping-request-source]
  1. Puts a mapping on existing index called twitter

  2. Adds a new field name to the mapping

  3. The type can be also provided within the source

Refresh

The refresh API allows to explicitly refresh one or more index:

client.admin().indices().prepareRefresh().get(); (1)
client.admin().indices()
        .prepareRefresh("twitter")               (2)
        .get();
client.admin().indices()
        .prepareRefresh("twitter", "company")   (3)
        .get();
  1. Refresh all indices

  2. Refresh one index

  3. Refresh many indices

Get Settings

The get settings API allows to retrieve settings of index/indices:

GetSettingsResponse response = client.admin().indices()
        .prepareGetSettings("company", "employee").get();                           (1)
for (ObjectObjectCursor<String, Settings> cursor : response.getIndexToSettings()) { (2)
    String index = cursor.key;                                                      (3)
    Settings settings = cursor.value;                                               (4)
    Integer shards = settings.getAsInt("index.number_of_shards", null);             (5)
    Integer replicas = settings.getAsInt("index.number_of_replicas", null);         (6)
}
  1. Get settings for indices company and employee

  2. Iterate over results

  3. Index name

  4. Settings for the given index

  5. Number of shards for this index

  6. Number of replicas for this index ==== Update Indices Settings

You can change index settings by calling:

client.admin().indices().prepareUpdateSettings("twitter")   (1)
        .setSettings(Settings.builder()                     (2)
                .put("index.number_of_replicas", 0)
        )
        .get();
  1. Index to update

  2. Settings

Cluster Administration

To access cluster Java API, you need to call cluster() method from an AdminClient:

ClusterAdminClient clusterAdminClient = client.admin().cluster();
Note
In the rest of this guide, we will use client.admin().cluster().

Cluster Health

Health

The cluster health API allows to get a very simple status on the health of the cluster and also can give you some technical information about the cluster status per index:

ClusterHealthResponse healths = client.admin().cluster().prepareHealth().get(); (1)
String clusterName = healths.getClusterName();              (2)
int numberOfDataNodes = healths.getNumberOfDataNodes();     (3)
int numberOfNodes = healths.getNumberOfNodes();             (4)

for (ClusterIndexHealth health : healths.getIndices().values()) { (5)
    String index = health.getIndex();                       (6)
    int numberOfShards = health.getNumberOfShards();        (7)
    int numberOfReplicas = health.getNumberOfReplicas();    (8)
    ClusterHealthStatus status = health.getStatus();        (9)
}
  1. Get information for all indices

  2. Access the cluster name

  3. Get the total number of data nodes

  4. Get the total number of nodes

  5. Iterate over all indices

  6. Index name

  7. Number of shards

  8. Number of replicas

  9. Index status

Wait for status

You can use the cluster health API to wait for a specific status for the whole cluster or for a given index:

client.admin().cluster().prepareHealth()            (1)
        .setWaitForYellowStatus()                   (2)
        .get();
client.admin().cluster().prepareHealth("company")   (3)
        .setWaitForGreenStatus()                    (4)
        .get();

client.admin().cluster().prepareHealth("employee")  (5)
        .setWaitForGreenStatus()                    (6)
        .setTimeout(TimeValue.timeValueSeconds(2))  (7)
        .get();
  1. Prepare a health request

  2. Wait for the cluster being yellow

  3. Prepare the health request for index company

  4. Wait for the index being green

  5. Prepare the health request for index employee

  6. Wait for the index being green

  7. Wait at most for 2 seconds

If the index does not have the expected status and you want to fail in that case, you need to explicitly interpret the result:

ClusterHealthResponse response = client.admin().cluster().prepareHealth("company")
        .setWaitForGreenStatus()    (1)
        .get();

ClusterHealthStatus status = response.getIndices().get("company").getStatus();
if (!status.equals(ClusterHealthStatus.GREEN)) {
    throw new RuntimeException("Index is in " + status + " state"); (2)
}
  1. Wait for the index being green

  2. Throw an exception if not GREEN

Stored Scripts API

The stored script API allows one to interact with scripts and templates stored in Elasticsearch. It can be used to create, update, get, and delete stored scripts and templates.

PutStoredScriptResponse response = client.admin().cluster().preparePutStoredScript()
                .setId("script1")
                .setContent(new BytesArray("{\"script\": {\"lang\": \"painless\", \"source\": \"_score * doc['my_numeric_field'].value\"} }"), XContentType.JSON)
                .get();

GetStoredScriptResponse response = client().admin().cluster().prepareGetStoredScript()
                .setId("script1")
                .get();

DeleteStoredScriptResponse response = client().admin().cluster().prepareDeleteStoredScript()
                .setId("script1")
                .get();

To store templates simply use "mustache" for the scriptLang.

Script Language

The put stored script API allows one to set the language of the stored script. If one is not provided the default scripting language will be used.