"Fossies" - the Fresh Open Source Software Archive

Member "elasticsearch-6.8.23/docs/java-rest/index.asciidoc" (29 Dec 2021, 171 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.

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[]

Overview

The Java REST Client comes in 2 flavors:

  • Java Low Level REST Client: the official low-level client for Elasticsearch. It allows to communicate with an Elasticsearch cluster through http. Leaves requests marshalling and responses un-marshalling to users. It is compatible with all Elasticsearch versions.

  • Java High Level REST Client: the official high-level client for Elasticsearch. Based on the low-level client, it exposes API specific methods and takes care of requests marshalling and responses un-marshalling.

Java Low Level REST Client

Getting started

This section describes how to get started with the low-level REST client from getting the artifact to using it in an application.

Maven Repository

The low-level Java REST client is hosted on Maven Central. The minimum Java version required is 1.7.

The low-level REST client is subject to the same release cycle as Elasticsearch. Replace the version with the desired client version, first released with 5.0.0-alpha4. There is no relation between the client version and the Elasticsearch version that the client can communicate with. The low-level REST client is compatible with all Elasticsearch versions.

If you are looking for a SNAPSHOT version, the Elastic Maven Snapshot repository is available at https://snapshots.elastic.co/maven/.

Maven configuration

Here is how you can configure the dependency using maven as a dependency manager. Add the following to your pom.xml file:


    org.elasticsearch.client
    elasticsearch-rest-client
    {version}

Gradle configuration

Here is how you can configure the dependency using gradle as a dependency manager. Add the following to your build.gradle file:

dependencies {
    compile 'org.elasticsearch.client:elasticsearch-rest-client:{version}'
}

Dependencies

The low-level Java REST client internally uses the Apache Http Async Client to send http requests. It depends on the following artifacts, namely the async http client and its own transitive dependencies:

  • org.apache.httpcomponents:httpasyncclient

  • org.apache.httpcomponents:httpcore-nio

  • org.apache.httpcomponents:httpclient

  • org.apache.httpcomponents:httpcore

  • commons-codec:commons-codec

  • commons-logging:commons-logging

Shading

In order to avoid version conflicts, the dependencies can be shaded and packaged within the client in a single JAR file (sometimes called an "uber JAR" or "fat JAR"). Shading a dependency consists of taking its content (resources files and Java class files) and renaming some of its packages before putting them in the same JAR file as the low-level Java REST client. Shading a JAR can be accomplished by 3rd-party plugins for Gradle and Maven.

Be advised that shading a JAR also has implications. Shading the Commons Logging layer, for instance, means that 3rd-party logging backends need to be shaded as well.

Maven configuration

Here is a configuration using the Maven Shade plugin. Add the following to your pom.xml file:


    
        
            org.apache.maven.plugins
            maven-shade-plugin
            3.1.0
            
                
                    package
                    shade
                    
                        
                            
                                org.apache.http
                                hidden.org.apache.http
                            
                            
                                org.apache.logging
                                hidden.org.apache.logging
                            
                            
                                org.apache.commons.codec
                                hidden.org.apache.commons.codec
                            
                            
                                org.apache.commons.logging
                                hidden.org.apache.commons.logging
                            
                        
                    
                
            
        
    

Gradle configuration

Here is a configuration using the Gradle ShadowJar plugin. Add the following to your build.gradle file:

shadowJar {
    relocate 'org.apache.http', 'hidden.org.apache.http'
    relocate 'org.apache.logging', 'hidden.org.apache.logging'
    relocate 'org.apache.commons.codec', 'hidden.org.apache.commons.codec'
    relocate 'org.apache.commons.logging', 'hidden.org.apache.commons.logging'
}

Initialization

A RestClient instance can be built through the corresponding RestClientBuilder class, created via RestClient#builder(HttpHost…​) static method. The only required argument is one or more hosts that the client will communicate with, provided as instances of HttpHost as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init]

The RestClient class is thread-safe and ideally has the same lifecycle as the application that uses it. It is important that it gets closed when no longer needed so that all the resources used by it get properly released, as well as the underlying http client instance and its threads:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-close]

RestClientBuilder also allows to optionally set the following configuration parameters while building the RestClient instance:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init-default-headers]
  1. Set the default headers that need to be sent with each request, to prevent having to specify them with each single request

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init-max-retry-timeout]
  1. Set the timeout that should be honoured in case multiple attempts are made for the same request. The default value is 90 seconds. In case the socket timeout is set to a higher value, the max retry timeout should be adjusted accordingly. deprecated[6.7.0, max retry timeout will be removed in 7.0.0]

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init-failure-listener]
  1. Set a listener that gets notified every time a node fails, in case actions need to be taken. Used internally when sniffing on failure is enabled.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init-node-selector]
  1. Set the node selector to be used to filter the nodes the client will send requests to among the ones that are set to the client itself. This is useful for instance to prevent sending requests to dedicated master nodes when sniffing is enabled. By default the client sends requests to every configured node.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init-request-config-callback]
  1. Set a callback that allows to modify the default request configuration (e.g. request timeouts, authentication, or anything that the org.apache.http.client.config.RequestConfig.Builder allows to set)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init-client-config-callback]
  1. Set a callback that allows to modify the http client configuration (e.g. encrypted communication over ssl, or anything that the org.apache.http.impl.nio.client.HttpAsyncClientBuilder allows to set)

Performing requests

Once the RestClient has been created, requests can be sent by calling either performRequest or performRequestAsync. performRequest is synchronous and will block the calling thread and return the Response when the request is successful or throw an exception if it fails. performRequestAsync is asynchronous and accepts a ResponseListener argument that it calls with a Response when the request is successful or with an Exception if it fails.

This is synchronous:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-sync]
  1. The HTTP method (GET, POST, HEAD, etc)

  2. The endpoint on the server

And this is asynchronous:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-async]
  1. The HTTP method (GET, POST, HEAD, etc)

  2. The endpoint on the server

  3. Handle the response

  4. Handle the failure

You can add request parameters to the request object:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-parameters]

You can set the body of the request to any HttpEntity:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-body]
Important
The ContentType specified for the HttpEntity is important because it will be used to set the Content-Type header so that Elasticsearch can properly parse the content.

You can also set it to a String which will default to a ContentType of application/json.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-body-shorter]

RequestOptions

The RequestOptions class holds parts of the request that should be shared between many requests in the same application. You can make a singleton instance and share it between all requests:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-options-singleton]
  1. Add any headers needed by all requests.

  2. Customize the response consumer.

addHeader is for headers that are required for authorization or to work with a proxy in front of Elasticsearch. There is no need to set the Content-Type header because the client will automatically set that from the HttpEntity attached to the request.

You can set the NodeSelector which controls which nodes will receive requests. NodeSelector.NOT_MASTER_ONLY is a good choice.

You can also customize the response consumer used to buffer the asynchronous responses. The default consumer will buffer up to 100MB of response on the JVM heap. If the response is larger then the request will fail. You could, for example, lower the maximum size which might be useful if you are running in a heap constrained environment like the example above.

Once you’ve created the singleton you can use it when making requests:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-options-set-singleton]

You can also customize these options on a per request basis. For example, this adds an extra header:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-options-customize-header]

Multiple parallel asynchronous actions

The client is quite happy to execute many actions in parallel. The following example indexes many documents in parallel. In a real world scenario you’d probably want to use the _bulk API instead, but the example is illustrative.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-async-example]
  1. Process the returned response

  2. Handle the returned exception, due to communication error or a response with status code that indicates an error

Reading responses

The Response object, either returned by the synchronous performRequest methods or received as an argument in ResponseListener#onSuccess(Response), wraps the response object returned by the http client and exposes some additional information.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-response2]
  1. Information about the performed request

  2. The host that returned the response

  3. The response status line, from which you can for instance retrieve the status code

  4. The response headers, which can also be retrieved by name though getHeader(String)

  5. The response body enclosed in an org.apache.http.HttpEntity object

When performing a request, an exception is thrown (or received as an argument in ResponseListener#onFailure(Exception) in the following scenarios:

IOException

communication problem (e.g. SocketTimeoutException)

ResponseException

a response was returned, but its status code indicated an error (not 2xx). A ResponseException originates from a valid http response, hence it exposes its corresponding Response object which gives access to the returned response.

Note
A ResponseException is not thrown for HEAD requests that return a 404 status code because it is an expected HEAD response that simply denotes that the resource is not found. All other HTTP methods (e.g., GET) throw a ResponseException for 404 responses unless the ignore parameter contains 404. ignore is a special client parameter that doesn’t get sent to Elasticsearch and contains a comma separated list of error status codes. It allows to control whether some error status code should be treated as an expected response rather than as an exception. This is useful for instance with the get api as it can return 404 when the document is missing, in which case the response body will not contain an error but rather the usual get api response, just without the document as it was not found.

Note that the low-level client doesn’t expose any helper for json marshalling and un-marshalling. Users are free to use the library that they prefer for that purpose.

The underlying Apache Async Http Client ships with different org.apache.http.HttpEntity implementations that allow to provide the request body in different formats (stream, byte array, string etc.). As for reading the response body, the HttpEntity#getContent method comes handy which returns an InputStream reading from the previously buffered response body. As an alternative, it is possible to provide a custom org.apache.http.nio.protocol.HttpAsyncResponseConsumer that controls how bytes are read and buffered.

Logging

The Java REST client uses the same logging library that the Apache Async Http Client uses: Apache Commons Logging, which comes with support for a number of popular logging implementations. The java packages to enable logging for are org.elasticsearch.client for the client itself and org.elasticsearch.client.sniffer for the sniffer.

The request tracer logging can also be enabled to log every request and corresponding response in curl format. That comes handy when debugging, for instance in case a request needs to be manually executed to check whether it still yields the same response as it did. Enable trace logging for the tracer package to have such log lines printed out. Do note that this type of logging is expensive and should not be enabled at all times in production environments, but rather temporarily used only when needed.

Common configuration

As explained in Initialization, the RestClientBuilder supports providing both a RequestConfigCallback and an HttpClientConfigCallback which allow for any customization that the Apache Async Http Client exposes. Those callbacks make it possible to modify some specific behaviour of the client without overriding every other default configuration that the RestClient is initialized with. This section describes some common scenarios that require additional configuration for the low-level Java REST Client.

Timeouts

Configuring requests timeouts can be done by providing an instance of RequestConfigCallback while building the RestClient through its builder. The interface has one method that receives an instance of org.apache.http.client.config.RequestConfig.Builder as an argument and has the same return type. The request config builder can be modified and then returned. In the following example we increase the connect timeout (defaults to 1 second) and the socket timeout (defaults to 30 seconds).

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-config-timeouts]

Number of threads

The Apache Http Async Client starts by default one dispatcher thread, and a number of worker threads used by the connection manager, as many as the number of locally detected processors (depending on what Runtime.getRuntime().availableProcessors() returns). The number of threads can be modified as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-config-threads]

Basic authentication

Configuring basic authentication can be done by providing an HttpClientConfigCallback while building the RestClient through its builder. The interface has one method that receives an instance of org.apache.http.impl.nio.client.HttpAsyncClientBuilder as an argument and has the same return type. The http client builder can be modified and then returned. In the following example we set a default credentials provider that requires basic authentication.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-config-basic-auth]

Preemptive Authentication can be disabled, which means that every request will be sent without authorization headers to see if it is accepted and, upon receiving an HTTP 401 response, it will resend the exact same request with the basic authentication header. If you wish to do this, then you can do so by disabling it via the HttpAsyncClientBuilder:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-config-disable-preemptive-auth]
  1. Disable preemptive authentication

Encrypted communication

Encrypted communication can also be configured through the HttpClientConfigCallback. The org.apache.http.impl.nio.client.HttpAsyncClientBuilder received as an argument exposes multiple methods to configure encrypted communication: setSSLContext, setSSLSessionStrategy and setConnectionManager, in order of precedence from the least important. The following is an example:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-config-encrypted-communication]

If no explicit configuration is provided, the system default configuration will be used.

Others

For any other required configuration needed, the Apache HttpAsyncClient docs should be consulted: https://hc.apache.org/httpcomponents-asyncclient-4.1.x/ .

Note
If your application runs under the security manager you might be subject to the JVM default policies of caching positive hostname resolutions indefinitely and negative hostname resolutions for ten seconds. If the resolved addresses of the hosts to which you are connecting the client to vary with time then you might want to modify the default JVM behavior. These can be modified by adding networkaddress.cache.ttl=<timeout> and networkaddress.cache.negative.ttl=<timeout> to your Java security policy.

Node selector

The client sends each request to one of the configured nodes in round-robin fashion. Nodes can optionally be filtered through a node selector that needs to be provided when initializing the client. This is useful when sniffing is enabled, in case only dedicated master nodes should be hit by HTTP requests. For each request the client will run the eventually configured node selector to filter the node candidates, then select the next one in the list out of the remaining ones.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest/src/test/java/org/elasticsearch/client/documentation/RestClientDocumentation.java[rest-client-init-allocation-aware-selector]
  1. Set an allocation aware node selector that allows to pick a node in the local rack if any available, otherwise go to any other node in any rack. It acts as a preference rather than a strict requirement, given that it goes to another rack if none of the local nodes are available, rather than returning no nodes in such case which would make the client forcibly revive a local node whenever none of the nodes from the preferred rack is available.

Warning
Node selectors that do not consistently select the same set of nodes will make round-robin behaviour unpredictable and possibly unfair. The preference example above is fine as it reasons about availability of nodes which already affects the predictability of round-robin. Node selection should not depend on other external factors or round-robin will not work properly.

Sniffer

Minimal library that allows to automatically discover nodes from a running Elasticsearch cluster and set them to an existing RestClient instance. It retrieves by default the nodes that belong to the cluster using the Nodes Info api and uses jackson to parse the obtained json response.

Compatible with Elasticsearch 2.x and onwards.

Maven Repository

The REST client sniffer is subject to the same release cycle as Elasticsearch. Replace the version with the desired sniffer version, first released with 5.0.0-alpha4. There is no relation between the sniffer version and the Elasticsearch version that the client can communicate with. Sniffer supports fetching the nodes list from Elasticsearch 2.x and onwards.

If you are looking for a SNAPSHOT version, the Elastic Maven Snapshot repository is available at https://snapshots.elastic.co/maven/.

Maven configuration

Here is how you can configure the dependency using maven as a dependency manager. Add the following to your pom.xml file:


    org.elasticsearch.client
    elasticsearch-rest-client-sniffer
    {version}

Gradle configuration

Here is how you can configure the dependency using gradle as a dependency manager. Add the following to your build.gradle file:

dependencies {
    compile 'org.elasticsearch.client:elasticsearch-rest-client-sniffer:{version}'
}

Usage

Once a RestClient instance has been created as shown in Initialization, a Sniffer can be associated to it. The Sniffer will make use of the provided RestClient to periodically (every 5 minutes by default) fetch the list of current nodes from the cluster and update them by calling RestClient#setNodes.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/sniffer/src/test/java/org/elasticsearch/client/sniff/documentation/SnifferDocumentation.java[sniffer-init]

It is important to close the Sniffer so that its background thread gets properly shutdown and all of its resources are released. The Sniffer object should have the same lifecycle as the RestClient and get closed right before the client:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/sniffer/src/test/java/org/elasticsearch/client/sniff/documentation/SnifferDocumentation.java[sniffer-close]

The Sniffer updates the nodes by default every 5 minutes. This interval can be customized by providing it (in milliseconds) as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/sniffer/src/test/java/org/elasticsearch/client/sniff/documentation/SnifferDocumentation.java[sniffer-interval]

It is also possible to enable sniffing on failure, meaning that after each failure the nodes list gets updated straightaway rather than at the following ordinary sniffing round. In this case a SniffOnFailureListener needs to be created at first and provided at RestClient creation. Also once the Sniffer is later created, it needs to be associated with that same SniffOnFailureListener instance, which will be notified at each failure and use the Sniffer to perform the additional sniffing round as described.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/sniffer/src/test/java/org/elasticsearch/client/sniff/documentation/SnifferDocumentation.java[sniff-on-failure]
  1. Set the failure listener to the RestClient instance

  2. When sniffing on failure, not only do the nodes get updated after each failure, but an additional sniffing round is also scheduled sooner than usual, by default one minute after the failure, assuming that things will go back to normal and we want to detect that as soon as possible. Said interval can be customized at Sniffer creation time through the setSniffAfterFailureDelayMillis method. Note that this last configuration parameter has no effect in case sniffing on failure is not enabled like explained above.

  3. Set the Sniffer instance to the failure listener

The Elasticsearch Nodes Info api doesn’t return the protocol to use when connecting to the nodes but only their host:port key-pair, hence http is used by default. In case https should be used instead, the ElasticsearchNodesSniffer instance has to be manually created and provided as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/sniffer/src/test/java/org/elasticsearch/client/sniff/documentation/SnifferDocumentation.java[sniffer-https]

In the same way it is also possible to customize the sniffRequestTimeout, which defaults to one second. That is the timeout parameter provided as a querystring parameter when calling the Nodes Info api, so that when the timeout expires on the server side, a valid response is still returned although it may contain only a subset of the nodes that are part of the cluster, the ones that have responded until then.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/sniffer/src/test/java/org/elasticsearch/client/sniff/documentation/SnifferDocumentation.java[sniff-request-timeout]

Also, a custom NodesSniffer implementation can be provided for advanced use-cases that may require fetching the `Node`s from external sources rather than from Elasticsearch:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/sniffer/src/test/java/org/elasticsearch/client/sniff/documentation/SnifferDocumentation.java[custom-nodes-sniffer]
  1. Fetch the hosts from the external source

License

Copyright 2013-2019 Elasticsearch

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Java High Level REST Client

Getting started

This section describes how to get started with the high-level REST client from getting the artifact to using it in an application.

Compatibility

The Java High Level REST Client requires at least Java 1.8 and depends on the Elasticsearch core project. The client version is the same as the Elasticsearch version that the client was developed for. It accepts the same request arguments as the TransportClient and returns the same response objects. See the Migration Guide if you need to migrate an application from TransportClient to the new REST client.

The High Level Client is guaranteed to be able to communicate with any Elasticsearch node running on the same major version and greater or equal minor version. It doesn’t need to be in the same minor version as the Elasticsearch nodes it communicates with, as it is forward compatible meaning that it supports communicating with later versions of Elasticsearch than the one it was developed for.

The 6.0 client is able to communicate with any 6.x Elasticsearch node, while the 6.1 client is for sure able to communicate with 6.1, 6.2 and any later 6.x version, but there may be incompatibility issues when communicating with a previous Elasticsearch node version, for instance between 6.1 and 6.0, in case the 6.1 client supports new request body fields for some APIs that are not known by the 6.0 node(s).

It is recommended to upgrade the High Level Client when upgrading the Elasticsearch cluster to a new major version, as REST API breaking changes may cause unexpected results depending on the node that is hit by the request, and newly added APIs will only be supported by the newer version of the client. The client should always be updated last, once all of the nodes in the cluster have been upgraded to the new major version.

Maven Repository

The high-level Java REST client is hosted on Maven Central. The minimum Java version required is 1.8.

The High Level REST Client is subject to the same release cycle as Elasticsearch. Replace the version with the desired client version.

If you are looking for a SNAPSHOT version, the Elastic Maven Snapshot repository is available at https://snapshots.elastic.co/maven/.

Maven configuration

Here is how you can configure the dependency using maven as a dependency manager. Add the following to your pom.xml file:


    org.elasticsearch.client
    elasticsearch-rest-high-level-client
    {version}

Gradle configuration

Here is how you can configure the dependency using gradle as a dependency manager. Add the following to your build.gradle file:

dependencies {
    compile 'org.elasticsearch.client:elasticsearch-rest-high-level-client:{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'
}

Dependencies

The High Level Java REST Client depends on the following artifacts and their transitive dependencies:

  • org.elasticsearch.client:elasticsearch-rest-client

  • org.elasticsearch:elasticsearch

Initialization

A RestHighLevelClient instance needs a REST low-level client builder to be built as follows:

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

The high-level client will internally create the low-level client used to perform requests based on the provided builder. That low-level client maintains a pool of connections and starts some threads so you should close the high-level client when you are well and truly done with it and it will in turn close the internal low-level client to free those resources. This can be done through the close:

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

In the rest of this documentation about the Java High Level Client, the RestHighLevelClient instance will be referenced as client.

RequestOptions

All APIs in the RestHighLevelClient accept a RequestOptions which you can use to customize the request in ways that won’t change how Elasticsearch executes the request. For example, this is the place where you’d specify a NodeSelector to control which node receives the request. See the low level client documentation for more examples of customizing the options.

Document APIs

The Java High Level REST Client supports the following Document APIs:

Index API

Index Request

An {request} requires the following arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-string]
  1. Index

  2. Type

  3. Document id

  4. Document source provided as a String

Providing the document source

The document source can be provided in different ways in addition to the String example shown above:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-map]
  1. Document source provided as a Map which gets automatically converted to JSON format

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-xcontent]
  1. Document source provided as an XContentBuilder object, the Elasticsearch built-in helpers to generate JSON content

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-shortcut]
  1. Document source provided as Object key-pairs, which gets converted to JSON format

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-routing]
  1. Routing value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-parent]
  1. Parent value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for primary shard to become available as a TimeValue

  2. Timeout to wait for primary shard to become available as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Refresh policy as a WriteRequest.RefreshPolicy instance

  2. Refresh policy as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-version]
  1. Version

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

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-op-type]
  1. Operation type provided as an DocWriteRequest.OpType value

  2. Operation type provided as a String: can be create or update (default)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-pipeline]
  1. The name of the ingest pipeline to be executed before indexing the document

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Handle (if needed) the case where the document was created for the first time

  2. Handle (if needed) the case where the document was rewritten as it was already existing

  3. Handle the situation where number of successful shards is less than total shards

  4. Handle the potential failures

If there is a version conflict, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-conflict]
  1. The raised exception indicates that a version conflict error was returned

Same will happen in case opType was set to create and a document with same index, type and id already existed:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-optype]
  1. The raised exception indicates that a version conflict error was returned

Get API

Get Request

A {request} requires the following arguments:

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

  2. Type

  3. Document id

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-no-source]
  1. Disable source retrieval, enabled by default

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-source-include]
  1. Configure source inclusion for specific fields

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-source-exclude]
  1. Configure source exclusion for specific fields

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-stored]
  1. Configure retrieval for specific stored fields (requires fields to be stored separately in the mappings)

  2. Retrieve the message stored field (requires the field to be stored separately in the mappings)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-routing]
  1. Routing value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-parent]
  1. Parent value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-preference]
  1. Preference value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-realtime]
  1. Set realtime flag to false (true by default)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Perform a refresh before retrieving the document (false by default)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-version]
  1. Version

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

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Response

The returned {response} allows to retrieve the requested document along with its metadata and eventually stored fields.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Retrieve the document as a String

  2. Retrieve the document as a Map<String, Object>

  3. Retrieve the document as a byte[]

  4. Handle the scenario where the document was not found. Note that although the returned response has 404 status code, a valid {response} is returned rather than an exception thrown. Such response does not hold any source document and its isExists method returns false.

When a get request is performed against an index that does not exist, the response has 404 status code, an ElasticsearchException gets thrown which needs to be handled as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-indexnotfound]
  1. Handle the exception thrown because the index does not exist

In case a specific document version has been requested, and the existing document has a different version number, a version conflict is raised:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-conflict]
  1. The raised exception indicates that a version conflict error was returned

Exists API

The exists API returns true if a document exists, and false otherwise.

Exists Request

It uses {request} just like the Get API. All of its optional arguments are supported. Since exists() only returns true or false, we recommend turning off fetching _source and any stored fields so the request is slightly lighter:

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

  2. Type

  3. Document id

  4. Disable fetching _source.

  5. Disable fetching stored fields.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Source exists request

A variant of the exists request is existsSource method which has the additional check that the document in question has stored the source. If the mapping for the index has opted to remove support for storing JSON source in documents then this method will return false for documents in this index.

Delete API

Delete Request

A {request} has no arguments

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

  2. Type

  3. Document id

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-routing]
  1. Routing value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-parent]
  1. Parent value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for primary shard to become available as a TimeValue

  2. Timeout to wait for primary shard to become available as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Refresh policy as a WriteRequest.RefreshPolicy instance

  2. Refresh policy as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-version]
  1. Version

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

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Handle the situation where number of successful shards is less than total shards

  2. Handle the potential failures

It is also possible to check whether the document was found or not:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-notfound]
  1. Do something if the document to be deleted was not found

If there is a version conflict, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-conflict]
  1. The raised exception indicates that a version conflict error was returned

Update API

Update Request

An {request} requires the following arguments:

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

  2. Type

  3. Document id

The Update API allows to update an existing document by using a script or by passing a partial document.

Updates with a script

The script can be provided as an inline script:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-with-inline-script]
  1. Script parameters provided as a Map of objects

  2. Create an inline script using the painless language and the previous parameters

  3. Sets the script to the update request

Or as a stored script:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-with-stored-script]
  1. Reference to a script stored under the name increment-field in the painless language

  2. Sets the script in the update request

Updates with a partial document

When using updates with a partial document, the partial document will be merged with the existing document.

The partial document can be provided in different ways:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-with-doc-as-string]
  1. Partial document source provided as a String in JSON format

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-with-doc-as-map]
  1. Partial document source provided as a Map which gets automatically converted to JSON format

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-with-doc-as-xcontent]
  1. Partial document source provided as an XContentBuilder object, the Elasticsearch built-in helpers to generate JSON content

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-shortcut]
  1. Partial document source provided as Object key-pairs, which gets converted to JSON format

Upserts

If the document does not already exist, it is possible to define some content that will be inserted as a new document using the upsert method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-upsert]
  1. Upsert document source provided as a String

Similarly to the partial document updates, the content of the upsert document can be defined using methods that accept String, Map, XContentBuilder or Object key-pairs.

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-routing]
  1. Routing value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-parent]
  1. Parent value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for primary shard to become available as a TimeValue

  2. Timeout to wait for primary shard to become available as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Refresh policy as a WriteRequest.RefreshPolicy instance

  2. Refresh policy as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-retry]
  1. How many times to retry the update operation if the document to update has been changed by another operation between the get and indexing phases of the update operation

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-no-source]
  1. Enable source retrieval, disabled by default

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-source-include]
  1. Configure source inclusion for specific fields

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-source-exclude]
  1. Configure source exclusion for specific fields

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-version]
  1. Version

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-detect-noop]
  1. Disable the noop detection

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-scripted-upsert]
  1. Indicate that the script must run regardless of whether the document exists or not, ie the script takes care of creating the document if it does not already exist.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-doc-upsert]
  1. Indicate that the partial document must be used as the upsert document if it does not exist yet.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-active-shards]
  1. Sets the number of shard copies that must be active before proceeding with the update operation.

  2. Number of shard copies provided as a ActiveShardCount: can be ActiveShardCount.ALL, ActiveShardCount.ONE or ActiveShardCount.DEFAULT (default)

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Update Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Handle the case where the document was created for the first time (upsert)

  2. Handle the case where the document was updated

  3. Handle the case where the document was deleted

  4. Handle the case where the document was not impacted by the update, ie no operation (noop) was executed on the document

When the source retrieval is enabled in the UpdateRequest through the fetchSource method, the response contains the source of the updated document:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-getresult]
  1. Retrieve the updated document as a GetResult

  2. Retrieve the source of the updated document as a String

  3. Retrieve the source of the updated document as a Map<String, Object>

  4. Retrieve the source of the updated document as a byte[]

  5. Handle the scenario where the source of the document is not present in the response (this is the case by default)

It is also possible to check for shard failures:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-failure]
  1. Handle the situation where number of successful shards is less than total shards

  2. Handle the potential failures

When a UpdateRequest is performed against a document that does not exist, the response has 404 status code, an ElasticsearchException gets thrown which needs to be handled as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-docnotfound]
  1. Handle the exception thrown because the document not exist

If there is a version conflict, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-conflict]
  1. The raised exception indicates that a version conflict error was returned.

Term Vectors API

Term Vectors API returns information and statistics on terms in the fields of a particular document. The document could be stored in the index or artificially provided by the user.

Term Vectors Request

A {request} expects an index, a type and an id to specify a certain document, and fields for which the information is retrieved.

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

Term vectors can also be generated for artificial documents, that is for documents not present in the index:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-artificial]
  1. An artificial document is provided as an XContentBuilder object, the Elasticsearch built-in helper to generate JSON content.

Optional arguments
include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-optional-arguments]
  1. Set fieldStatistics to false (default is true) to omit document count, sum of document frequencies, sum of total term frequencies.

  2. Set termStatistics to true (default is false) to display total term frequency and document frequency.

  3. Set positions to false (default is true) to omit the output of positions.

  4. Set offsets to false (default is true) to omit the output of offsets.

  5. Set payloads to false (default is true) to omit the output of payloads.

  6. Set filterSettings to filter the terms that can be returned based on their tf-idf scores.

  7. Set perFieldAnalyzer to specify a different analyzer than the one that the field has.

  8. Set realtime to false (default is true) to retrieve term vectors near realtime.

  9. Set a routing parameter

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Term Vectors Response

{response} contains the following information:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. The index name of the document.

  2. The type name of the document.

  3. The id of the document.

  4. Indicates whether or not the document found.

Inspecting Term Vectors

If {response} contains non-null list of term vectors, more information about each term vector can be obtained using the following:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-term-vectors]
  1. The name of the current field

  2. Fields statistics for the current field - document count

  3. Fields statistics for the current field - sum of total term frequencies

  4. Fields statistics for the current field - sum of document frequencies

  5. Terms for the current field

  6. The name of the term

  7. Term frequency of the term

  8. Document frequency of the term

  9. Total term frequency of the term

  10. Score of the term

  11. Tokens of the term

  12. Position of the token

  13. Start offset of the token

  14. End offset of the token

  15. Payload of the token

Bulk API

Note
The Java High Level REST Client provides the [java-rest-high-document-{api}-processor] to assist with bulk requests.

Bulk Request

A {request} can be used to execute multiple index, update and/or delete operations using a single request.

It requires at least one operation to be added to the Bulk request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request]
  1. Creates the {request}

  2. Adds a first IndexRequest to the Bulk request. See Index API for more information on how to build IndexRequest.

  3. Adds a second IndexRequest

  4. Adds a third IndexRequest

Warning
The Bulk API supports only documents encoded in JSON or SMILE. Providing documents in any other format will result in an error.

And different operation types can be added to the same {request}:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-with-mixed-operations]
  1. Adds a DeleteRequest to the {request}. See Delete API for more information on how to build DeleteRequest.

  2. Adds an UpdateRequest to the {request}. See Update API for more information on how to build UpdateRequest.

  3. Adds an IndexRequest using the SMILE format

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the bulk request to be performed as a TimeValue

  2. Timeout to wait for the bulk request to be performed as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Refresh policy as a WriteRequest.RefreshPolicy instance

  2. Refresh policy as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-active-shards]
  1. Sets the number of shard copies that must be active before proceeding with the index/update/delete operations.

  2. Number of shard copies provided as a ActiveShardCount: can be ActiveShardCount.ALL, ActiveShardCount.ONE or ActiveShardCount.DEFAULT (default)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[bulk-request-pipeline]
  1. Global pipelineId used on all sub requests, unless overridden on a sub request

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[bulk-request-routing]
  1. Global routingId used on all sub requests, unless overridden on a sub request

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[bulk-request-index-type]
  1. A bulk request with global index and type used on all sub requests, unless overridden on a sub request. Both parameters are @Nullable and can only be set during BulkRequest creation.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Bulk Response

The returned {response} contains information about the executed operations and allows to iterate over each result as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Iterate over the results of all operations

  2. Retrieve the response of the operation (successful or not), can be IndexResponse, UpdateResponse or DeleteResponse which can all be seen as DocWriteResponse instances

  3. Handle the response of an index operation

  4. Handle the response of a update operation

  5. Handle the response of a delete operation

The Bulk response provides a method to quickly check if one or more operation has failed:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-has-failures]
  1. This method returns true if at least one operation failed

In such situation it is necessary to iterate over all operation results in order to check if the operation failed, and if so, retrieve the corresponding failure:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-errors]
  1. Indicate if a given operation failed

  2. Retrieve the failure of the failed operation

Bulk Processor

The BulkProcessor simplifies the usage of the Bulk API by providing a utility class that allows index/update/delete operations to be transparently executed as they are added to the processor.

In order to execute the requests, the BulkProcessor requires the following components:

RestHighLevelClient

This client is used to execute the {request} and to retrieve the BulkResponse

BulkProcessor.Listener

This listener is called before and after every {request} execution or when a {request} failed

Then the BulkProcessor.builder method can be used to build a new BulkProcessor:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-processor-init]
  1. Create the BulkProcessor.Listener

  2. This method is called before each execution of a {request}

  3. This method is called after each execution of a {request}

  4. This method is called when a {request} failed

  5. Create the BulkProcessor by calling the build() method from the BulkProcessor.Builder. The RestHighLevelClient.bulkAsync() method will be used to execute the {request} under the hood.

The BulkProcessor.Builder provides methods to configure how the BulkProcessor should handle requests execution:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-processor-options]
  1. Set when to flush a new bulk request based on the number of actions currently added (defaults to 1000, use -1 to disable it)

  2. Set when to flush a new bulk request based on the size of actions currently added (defaults to 5Mb, use -1 to disable it)

  3. Set the number of concurrent requests allowed to be executed (default to 1, use 0 to only allow the execution of a single request)

  4. Set a flush interval flushing any {request} pending if the interval passes (defaults to not set)

  5. Set a constant back off policy that initially waits for 1 second and retries up to 3 times. See BackoffPolicy.noBackoff(), BackoffPolicy.constantBackoff() and BackoffPolicy.exponentialBackoff() for more options.

Once the BulkProcessor is created requests can be added to it:

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

The requests will be executed by the BulkProcessor, which takes care of calling the BulkProcessor.Listener for every bulk request.

The listener provides methods to access to the {request} and the {response}:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-processor-listener]
  1. Called before each execution of a {request}, this method allows to know the number of operations that are going to be executed within the {request}

  2. Called after each execution of a {request}, this method allows to know if the {response} contains errors

  3. Called if the {request} failed, this method allows to know the failure

Once all requests have been added to the BulkProcessor, its instance needs to be closed using one of the two available closing methods.

The awaitClose() method can be used to wait until all requests have been processed or the specified waiting time elapses:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-processor-await]
  1. The method returns true if all bulk requests completed and false if the waiting time elapsed before all the bulk requests completed

The close() method can be used to immediately close the BulkProcessor:

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

Both methods flush the requests added to the processor before closing the processor and also forbid any new request to be added to it.

Multi-Get API

The multiGet API executes multiple get requests in a single http request in parallel.

Multi-Get Request

A {request} is built empty and you add `MultiGetRequest.Item`s to configure what to fetch:

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

  2. Type

  3. Document id

  4. Add another item to fetch

Optional arguments

multiGet supports the same optional arguments that the get API supports. You can set most of these on the Item:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-no-source]
  1. Disable source retrieval, enabled by default

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-source-include]
  1. Configure source inclusion for specific fields

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-source-exclude]
  1. Configure source exclusion for specific fields

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-stored]
  1. Configure retrieval for specific stored fields (requires fields to be stored separately in the mappings)

  2. Retrieve the foo stored field (requires the field to be stored separately in the mappings)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-item-extras]
  1. Routing value

  2. Parent value

  3. Version

  4. Version type

{ref}/search-request-preference.html[preference], {ref}/docs-get.html#realtime[realtime] and {ref}/docs-get.html#get-refresh[refresh] can be set on the main request but not on any items:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-top-level-extras]
  1. Preference value

  2. Set realtime flag to false (true by default)

  3. Perform a refresh before retrieving the document (false by default)

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Multi Get Response

The returned {response} contains a list of MultiGetItemResponse`s in `getResponses in the same order that they were requested. MultiGetItemResponse contains either a GetResponse if the get succeeded or a MultiGetResponse.Failure if it failed. A success looks just like a normal GetResponse.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. getFailure returns null because there isn’t a failure.

  2. getResponse returns the GetResponse.

  3. Retrieve the document as a String

  4. Retrieve the document as a Map<String, Object>

  5. Retrieve the document as a byte[]

  6. Handle the scenario where the document was not found. Note that although the returned response has 404 status code, a valid GetResponse is returned rather than an exception thrown. Such response does not hold any source document and its isExists method returns false.

When one of the subrequests as performed against an index that does not exist getFailure will contain an exception:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-indexnotfound]
  1. getResponse is null.

  2. getFailure isn’t and contains an Exception.

  3. That Exception is actually an ElasticsearchException

  4. and it has a status of NOT_FOUND. It’d have been an HTTP 404 if this wasn’t a multi get.

  5. getMessage explains the actual cause, no such index.

In case a specific document version has been requested, and the existing document has a different version number, a version conflict is raised:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-conflict]
  1. getResponse is null.

  2. getFailure isn’t and contains an Exception.

  3. That Exception is actually an ElasticsearchException

  4. and it has a status of CONFLICT. It’d have been an HTTP 409 if this wasn’t a multi get.

  5. getMessage explains the actual cause, `

Reindex API

Reindex Request

A {request} can be used to copy documents from one or more indexes into a destination index.

It requires an existing source index and a target index which may or may not exist pre-request. Reindex does not attempt to set up the destination index. It does not copy the settings of the source index. You should set up the destination index prior to running a _reindex action, including setting up mappings, shard counts, replicas, etc.

The simplest form of a {request} looks like this:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request]
  1. Creates the {request}

  2. Adds a list of sources to copy from

  3. Adds the destination index

The dest element can be configured like the index API to control optimistic concurrency control. Just leaving out versionType (as above) or setting it to internal will cause Elasticsearch to blindly dump documents into the target. Setting versionType to external will cause Elasticsearch to preserve the version from the source, create any documents that are missing, and update any documents that have an older version in the destination index than they do in the source index.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-versionType]
  1. Set the versionType to EXTERNAL

Setting opType to create will cause _reindex to only create missing documents in the target index. All existing documents will cause a version conflict. The default opType is index.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-opType]
  1. Set the opType to create

By default version conflicts abort the _reindex process but you can just count them instead with:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-conflicts]
  1. Set proceed on version conflict

You can limit the documents by adding a type to the source or by adding a query.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-typeOrQuery]
  1. Only copy doc type

  2. Only copy documents which have field user set to kimchy

It’s also possible to limit the number of processed documents by setting size.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-size]
  1. Only copy 10 documents

By default _reindex uses batches of 1000. You can change the batch size with sourceBatchSize.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-sourceSize]
  1. Use batches of 100 documents

Reindex can also use the ingest feature by specifying a pipeline.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-pipeline]
  1. set pipeline to my_pipeline

If you want a particular set of documents from the source index you’ll need to use sort. If possible, prefer a more selective query to size and sort.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-sort]
  1. add descending sort to`field1`

  2. add ascending sort to field2

{request} also supports a script that modifies the document. It allows you to also change the document’s metadata. The following example illustrates that.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-script]
  1. setScript to increment the likes field on all documents with user kimchy.

{request} supports reindexing from a remote Elasticsearch cluster. When using a remote cluster the query should be specified inside the RemoteInfo object and not using setSourceQuery. If both the remote info and the source query are set it results in a validation error during the request. The reason for this is that the remote Elasticsearch may not understand queries built by the modern query builders. The remote cluster support works all the way back to Elasticsearch 0.90 and the query language has changed since then. When reaching older versions, it is safer to write the query by hand in JSON.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-remote]
  1. set remote elastic cluster

{request} also helps in automatically parallelizing using sliced-scroll to slice on _uid. Use setSlices to specify the number of slices to use.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-slices]
  1. set number of slices to use

{request} uses the scroll parameter to control how long it keeps the "search context" alive.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-scroll]
  1. set scroll time

Optional arguments

In addition to the options above the following arguments can optionally be also provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the reindex request to be performed as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Refresh index after calling reindex

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Reindex task submission

It is also possible to submit a {request} and not wait for it completion with the use of Task API. This is an equivalent of a REST request with wait_for_completion flag set to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/ReindexIT.java[submit-reindex-task]
  1. A {request} is constructed the same way as for the synchronous method

  2. A submit method returns a TaskSubmissionResponse which contains a task identifier.

  3. The task identifier can be used to get response from a completed task.

Reindex Response

The returned {response} contains information about the executed operations and allows to iterate over each result as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Get total time taken

  2. Check if the request timed out

  3. Get total number of docs processed

  4. Number of docs that were updated

  5. Number of docs that were created

  6. Number of docs that were deleted

  7. Number of batches that were executed

  8. Number of skipped docs

  9. Number of version conflicts

  10. Number of times request had to retry bulk index operations

  11. Number of times request had to retry search operations

  12. The total time this request has throttled itself not including the current throttle time if it is currently sleeping

  13. Remaining delay of any current throttle sleep or 0 if not sleeping

  14. Failures during search phase

  15. Failures during bulk index operation

Update By Query API

Update By Query Request

A {request} can be used to update documents in an index.

It requires an existing index (or a set of indices) on which the update is to be performed.

The simplest form of a {request} looks like this:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request]
  1. Creates the {request} on a set of indices.

By default version conflicts abort the {request} process but you can just count them instead with:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-conflicts]
  1. Set proceed on version conflict

You can limit the documents by adding a query.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-query]
  1. Only copy documents which have field user set to kimchy

It’s also possible to limit the number of processed documents by setting size.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-size]
  1. Only copy 10 documents

By default {request} uses batches of 1000. You can change the batch size with setBatchSize.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-scrollSize]
  1. Use batches of 100 documents

Update by query can also use the ingest feature by specifying a pipeline.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-pipeline]
  1. set pipeline to my_pipeline

{request} also supports a script that modifies the document:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-script]
  1. setScript to increment the likes field on all documents with user kimchy.

{request} can be parallelized using sliced-scroll with setSlices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-slices]
  1. set number of slices to use

UpdateByQueryRequest uses the scroll parameter to control how long it keeps the "search context" alive.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-scroll]
  1. set scroll time

If you provide routing then the routing is copied 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-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-routing]
  1. set routing

Optional arguments

In addition to the options above the following arguments can optionally be also provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the update by query request to be performed as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Refresh index after calling update by query

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-indicesOptions]
  1. Set indices options

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Update By Query Response

The returned {response} contains information about the executed operations and allows to iterate over each result as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Get total time taken

  2. Check if the request timed out

  3. Get total number of docs processed

  4. Number of docs that were updated

  5. Number of docs that were deleted

  6. Number of batches that were executed

  7. Number of skipped docs

  8. Number of version conflicts

  9. Number of times request had to retry bulk index operations

  10. Number of times request had to retry search operations

  11. The total time this request has throttled itself not including the current throttle time if it is currently sleeping

  12. Remaining delay of any current throttle sleep or 0 if not sleeping

  13. Failures during search phase

  14. Failures during bulk index operation

Delete By Query API

Delete By Query Request

A {request} can be used to delete documents from an index. It requires an existing index (or a set of indices) on which deletion is to be performed.

The simplest form of a {request} looks like this and deletes all documents in an index:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request]
  1. Creates the {request} on a set of indices.

By default version conflicts abort the {request} process but you can just count them with this:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-conflicts]
  1. Set proceed on version conflict

You can limit the documents by adding a query.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-query]
  1. Only copy documents which have field user set to kimchy

It’s also possible to limit the number of processed documents by setting size.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-size]
  1. Only copy 10 documents

By default {request} uses batches of 1000. You can change the batch size with setBatchSize.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-scrollSize]
  1. Use batches of 100 documents

{request} can also be parallelized using sliced-scroll with setSlices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-slices]
  1. set number of slices to use

{request} uses the scroll parameter to control how long it keeps the "search context" alive.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-scroll]
  1. set scroll time

If you provide routing then the routing is copied 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-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-routing]
  1. set routing

Optional arguments

In addition to the options above the following arguments can optionally be also provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the delete by query request to be performed as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-refresh]
  1. Refresh index after calling delete by query

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-indicesOptions]
  1. Set indices options

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete By Query Response

The returned {response} contains information about the executed operations and allows to iterate over each result as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Get total time taken

  2. Check if the request timed out

  3. Get total number of docs processed

  4. Number of docs that were deleted

  5. Number of batches that were executed

  6. Number of skipped docs

  7. Number of version conflicts

  8. Number of times request had to retry bulk index operations

  9. Number of times request had to retry search operations

  10. The total time this request has throttled itself not including the current throttle time if it is currently sleeping

  11. Remaining delay of any current throttle sleep or 0 if not sleeping

  12. Failures during search phase

  13. Failures during bulk index operation

Rethrottle API

Rethrottle Request

A {request} can be used to change the current throttling on a running reindex, update-by-query or delete-by-query task or to disable throttling of the task entirely. It requires the task Id of the task to change.

In its simplest form, you can use it to disable throttling of a running task using the following:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-disable-request]
  1. Create a {request} that disables throttling for a specific task id

By providing a requestsPerSecond argument, the request will change the existing task throttling to the specified value:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request]
  1. Request to change the throttling of a task to 100 requests per second

The rethrottling request can be executed by using one of the three appropriate methods depending on whether a reindex, update-by-query or delete-by-query task should be rethrottled:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-execution]
  1. Execute reindex rethrottling request

  2. The same for update-by-query

  3. The same for delete-by-query

Asynchronous Execution

The asynchronous execution of a rethrottle request requires both the {request} instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. Execute reindex rethrottling asynchronously

  2. The same for update-by-query

  3. The same for delete-by-query

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. A typical listener looks like this:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-async-listener]
  1. Code executed when the request is successfully completed

  2. Code executed when the request fails with an exception

Rethrottle Response

Rethrottling returns the task that has been rethrottled in the form of a {response}. The structure of this response object is described in detail in this section.

Multi Term Vectors API

Multi Term Vectors API allows to get multiple term vectors at once.

Multi Term Vectors Request

There are two ways to create a {request}.

The first way is to create an empty {request}, and then add individual term vectors requests to it.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request]
  1. Create an empty {request}.

  2. Add the first {tvrequest} to the {request}.

  3. Add the second {tvrequest} for an artificial doc to the {request}.

The second way can be used when all term vectors requests share the same arguments, such as index, type, and other settings. In this case, a template {tvrequest} can be created with all necessary settings set, and this template request can be passed to {request} along with all documents' ids for which to execute these requests.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-request-template]
  1. Create a template {tvrequest}.

  2. Pass documents' ids and the template to the {request}.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Multi Term Vectors Response

{response} allows to get the list of term vectors responses, each of which can be inspected as described in Term Vectors API.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java[{api}-response]
  1. Get a list of TermVectorsResponse

Search APIs

The Java High Level REST Client supports the following Search APIs:

Search Request

The {request} is used for any operation that has to do with searching documents, aggregations, suggestions and also offers ways of requesting highlighting on the resulting documents.

In its most basic form, we can add a query to the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-basic]
  1. Creates the SearchRequest. Without arguments this runs against all indices.

  2. Most search parameters are added to the SearchSourceBuilder. It offers setters for everything that goes into the search request body.

  3. Add a match_all query to the SearchSourceBuilder.

  4. Add the SearchSourceBuilder to the SearchRequest.

Optional arguments

Let’s first look at some of the optional arguments of a {request}:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-indices]
  1. Restricts the request to an index

There are a couple of other interesting optional parameters:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-routing]
  1. Set a routing parameter

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-preference]
  1. Use the preference parameter e.g. to execute the search to prefer local shards. The default is to randomize across shards.

Using the SearchSourceBuilder

Most options controlling the search behavior can be set on the SearchSourceBuilder, which contains more or less the equivalent of the options in the search request body of the Rest API.

Here are a few examples of some common options:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-source-basics]
  1. Create a SearchSourceBuilder with default options.

  2. Set the query. Can be any type of QueryBuilder

  3. Set the from option that determines the result index to start searching from. Defaults to 0.

  4. Set the size option that determines the number of search hits to return. Defaults to 10.

  5. Set an optional timeout that controls how long the search is allowed to take.

After this, the SearchSourceBuilder only needs to be added to the {request}:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-source-setter]
Building queries

Search queries are created using QueryBuilder objects. A QueryBuilder exists for every search query type supported by Elasticsearch’s {ref}/query-dsl.html[Query DSL].

A QueryBuilder can be created using its constructor:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-query-builder-ctor]
  1. Create a full text {ref}/query-dsl-match-query.html[Match Query] that matches the text "kimchy" over the field "user".

Once created, the QueryBuilder object provides methods to configure the options of the search query it creates:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-query-builder-options]
  1. Enable fuzzy matching on the match query

  2. Set the prefix length option on the match query

  3. Set the max expansion options to control the fuzzy process of the query

QueryBuilder objects can also be created using the QueryBuilders utility class. This class provides helper methods that can be used to create QueryBuilder objects using a fluent programming style:

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

Whatever the method used to create it, the QueryBuilder object must be added to the SearchSourceBuilder as follows:

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

The Building Queries page gives a list of all available search queries with their corresponding QueryBuilder objects and QueryBuilders helper methods.

Specifying Sorting

The SearchSourceBuilder allows to add one or more SortBuilder instances. There are four special implementations (Field-, Score-, GeoDistance- and ScriptSortBuilder).

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-source-sorting]
  1. Sort descending by _score (the default)

  2. Also sort ascending by _id field

Source filtering

By default, search requests return the contents of the document _source but like in the Rest API you can overwrite this behavior. For example, you can turn off _source retrieval completely:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-source-filtering-off]

The method also accepts an array of one or more wildcard patterns to control which fields get included or excluded in a more fine grained way:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-source-filtering-includes]
Requesting Highlighting

Highlighting search results can be achieved by setting a HighlightBuilder on the SearchSourceBuilder. Different highlighting behaviour can be defined for each fields by adding one or more HighlightBuilder.Field instances to a HighlightBuilder.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-highlighting]
  1. Creates a new HighlightBuilder

  2. Create a field highlighter for the title field

  3. Set the field highlighter type

  4. Add the field highlighter to the highlight builder

There are many options which are explained in detail in the Rest API documentation. The Rest API parameters (e.g. pre_tags) are usually changed by setters with a similar name (e.g. #preTags(String …​)).

Highlighted text fragments can later be retrieved from the {response}.

Requesting Aggregations

Aggregations can be added to the search by first creating the appropriate AggregationBuilder and then setting it on the SearchSourceBuilder. In the following example we create a terms aggregation on company names with a sub-aggregation on the average age of employees in the company:

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

The Building Aggregations page gives a list of all available aggregations with their corresponding AggregationBuilder objects and AggregationBuilders helper methods.

We will later see how to access aggregations in the {response}.

Requesting Suggestions

To add Suggestions to the search request, use one of the SuggestionBuilder implementations that are easily accessible from the SuggestBuilders factory class. Suggestion builders need to be added to the top level SuggestBuilder, which itself can be set on the SearchSourceBuilder.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-suggestion]
  1. Creates a new TermSuggestionBuilder for the user field and the text kmichy

  2. Adds the suggestion builder and names it suggest_user

We will later see how to retrieve suggestions from the {response}.

Profiling Queries and Aggregations

The {ref}/search-profile.html[Profile API] can be used to profile the execution of queries and aggregations for a specific search request. in order to use it, the profile flag must be set to true on the SearchSourceBuilder:

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

Once the {request} is executed the corresponding {response} will contain the profiling results.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

SearchResponse

The {response} that is returned by executing the search provides details about the search execution itself as well as access to the documents returned. First, there is useful information about the request execution itself, like the HTTP status code, execution time or whether the request terminated early or timed out:

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

Second, the response also provides information about the execution on the shard level by offering statistics about the total number of shards that were affected by the search, and the successful vs. unsuccessful shards. Possible failures can also be handled by iterating over an array off ShardSearchFailures like in the following example:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-response-2]
Retrieving SearchHits

To get access to the returned documents, we need to first get the SearchHits contained in the response:

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

The SearchHits provides global information about all hits, like total number of hits or the maximum score:

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

Nested inside the SearchHits are the individual search results that can be iterated over:

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

The SearchHit provides access to basic information like index, type, docId and score of each search hit:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-hits-singleHit-properties]

Furthermore, it lets you get back the document source, either as a simple JSON-String or as a map of key/value pairs. In this map, regular fields are keyed by the field name and contain the field value. Multi-valued fields are returned as lists of objects, nested objects as another key/value map. These cases need to be cast accordingly:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-hits-singleHit-source]
Retrieving Highlighting

If requested, highlighted text fragments can be retrieved from each SearchHit in the result. The hit object offers access to a map of field names to HighlightField instances, each of which contains one or many highlighted text fragments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-highlighting-get]
  1. Get the highlighting for the title field

  2. Get one or many fragments containing the highlighted field content

Retrieving Aggregations

Aggregations can be retrieved from the {response} by first getting the root of the aggregation tree, the Aggregations object, and then getting the aggregation by name.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-aggregations-get]
  1. Get the by_company terms aggregation

  2. Get the buckets that is keyed with Elastic

  3. Get the average_age sub-aggregation from that bucket

Note that if you access aggregations by name, you need to specify the aggregation interface according to the type of aggregation you requested, otherwise a ClassCastException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-request-aggregations-get-wrongCast]
  1. This will throw an exception because "by_company" is a terms aggregation but we try to retrieve it as a range aggregation

It is also possible to access all aggregations as a map that is keyed by the aggregation name. In this case, the cast to the proper aggregation interface needs to happen explicitly:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-aggregations-asMap]

There are also getters that return all top level aggregations as a list:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-aggregations-asList]

And last but not least you can iterate over all aggregations and then e.g. decide how to further process them based on their type:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-aggregations-iterator]
Retrieving Suggestions

To get back the suggestions from a {response}, use the Suggest object as an entry point and then retrieve the nested suggestion objects:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-suggestion-get]
  1. Use the Suggest class to access suggestions

  2. Suggestions can be retrieved by name. You need to assign them to the correct type of Suggestion class (here TermSuggestion), otherwise a ClassCastException is thrown

  3. Iterate over the suggestion entries

  4. Iterate over the options in one entry

Retrieving Profiling Results

Profiling results are retrieved from a {response} using the getProfileResults() method. This method returns a Map containing a ProfileShardResult object for every shard involved in the {request} execution. ProfileShardResult are stored in the Map using a key that uniquely identifies the shard the profile result corresponds to.

Here is a sample code that shows how to iterate over all the profiling results of every shard:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-profiling-get]
  1. Retrieve the Map of ProfileShardResult from the {response}

  2. Profiling results can be retrieved by shard’s key if the key is known, otherwise it might be simpler to iterate over all the profiling results

  3. Retrieve the key that identifies which shard the ProfileShardResult belongs to

  4. Retrieve the ProfileShardResult for the given shard

The ProfileShardResult object itself contains one or more query profile results, one for each query executed against the underlying Lucene index:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-profiling-queries]
  1. Retrieve the list of QueryProfileShardResult

  2. Iterate over each QueryProfileShardResult

Each QueryProfileShardResult gives access to the detailed query tree execution, returned as a list of ProfileResult objects:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-profiling-queries-results]
  1. Iterate over the profile results

  2. Retrieve the name of the Lucene query

  3. Retrieve the time in millis spent executing the Lucene query

  4. Retrieve the profile results for the sub-queries (if any)

The Rest API documentation contains more information about {ref}/search-profile-queries.html[Profiling Queries] with a description of the query profiling information.

The QueryProfileShardResult also gives access to the profiling information for the Lucene collectors:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-profiling-queries-collectors]
  1. Retrieve the profiling result of the Lucene collector

  2. Retrieve the name of the Lucene collector

  3. Retrieve the time in millis spent executing the Lucene collector

  4. Retrieve the profile results for the sub-collectors (if any)

The Rest API documentation contains more information about profiling information for Lucene collectors. See {ref}/search-profile-queries.html[Profiling queries].

In a very similar manner to the query tree execution, the QueryProfileShardResult objects gives access to the detailed aggregations tree execution:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-profiling-aggs]
  1. Retrieve the AggregationProfileShardResult

  2. Iterate over the aggregation profile results

  3. Retrieve the type of the aggregation (corresponds to Java class used to execute the aggregation)

  4. Retrieve the time in millis spent executing the Lucene collector

  5. Retrieve the profile results for the sub-aggregations (if any)

The Rest API documentation contains more information about {ref}/search-profile-aggregations.html[Profiling aggregations].

Search Scroll API

The Scroll API can be used to retrieve a large number of results from a search request.

In order to use scrolling, the following steps need to be executed in the given order.

Initialize the search scroll context

An initial search request with a scroll parameter must be executed to initialize the scroll session through the Search API. When processing this SearchRequest, Elasticsearch detects the presence of the scroll parameter and keeps the search context alive for the corresponding time interval.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-scroll-init]
  1. Create the SearchRequest and its corresponding SearchSourceBuilder. Also optionally set the size to control how many results to retrieve at a time.

  2. Set the scroll interval

  3. Read the returned scroll id, which points to the search context that’s being kept alive and will be needed in the following search scroll call

  4. Retrieve the first batch of search hits

Retrieve all the relevant documents

As a second step, the received scroll identifier must be set to a SearchScrollRequest along with a new scroll interval and sent through the searchScroll method. Elasticsearch returns another batch of results with a new scroll identifier. This new scroll identifier can then be used in a subsequent SearchScrollRequest to retrieve the next batch of results, and so on. This process should be repeated in a loop until no more results are returned, meaning that the scroll has been exhausted and all the matching documents have been retrieved.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-scroll2]
  1. Create the SearchScrollRequest by setting the required scroll id and the scroll interval

  2. Read the new scroll id, which points to the search context that’s being kept alive and will be needed in the following search scroll call

  3. Retrieve another batch of search hits <4>

Clear the scroll context

Finally, the last scroll identifier can be deleted using the Clear Scroll API in order to release the search context. This happens automatically when the scroll expires, but it’s good practice to do it as soon as the scroll session is completed.

Optional arguments

The following arguments can optionally be provided when constructing the SearchScrollRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[scroll-request-arguments]
  1. Scroll interval as a TimeValue

  2. Scroll interval as a String

If no scroll value is set for the SearchScrollRequest, the search context will expire once the initial scroll time expired (ie, the scroll time set in the initial search request).

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-scroll-execute-sync]

Asynchronous Execution

The asynchronous execution of a search scroll request requires both the SearchScrollRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-scroll-execute-async]
  1. The SearchScrollRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for SearchResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-scroll-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Response

The search scroll API returns a SearchResponse object, same as the Search API.

Full example

The following is a complete example of a scrolled search.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-scroll-example]
  1. Initialize the search context by sending the initial SearchRequest

  2. Retrieve all the search hits by calling the Search Scroll api in a loop until no documents are returned

  3. Process the returned search results

  4. Create a new SearchScrollRequest holding the last returned scroll identifier and the scroll interval

  5. Clear the scroll context once the scroll is completed

Clear Scroll API

The search contexts used by the Search Scroll API are automatically deleted when the scroll times out. But it is advised to release search contexts as soon as they are not necessary anymore using the Clear Scroll API.

Clear Scroll Request

A ClearScrollRequest can be created as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[clear-scroll-request]
  1. Create a new ClearScrollRequest

  2. Adds a scroll id to the list of scroll identifiers to clear

Providing the scroll identifiers

The ClearScrollRequest allows to clear one or more scroll identifiers in a single request.

The scroll identifiers can be added to the request one by one:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[clear-scroll-add-scroll-id]

Or all together using:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[clear-scroll-add-scroll-ids]

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[clear-scroll-execute]

Asynchronous Execution

The asynchronous execution of a clear scroll request requires both the ClearScrollRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[clear-scroll-execute-async]
  1. The ClearScrollRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for ClearScrollResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[clear-scroll-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Clear Scroll Response

The returned ClearScrollResponse allows to retrieve information about the released search contexts:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[clear-scroll-response]
  1. Return true if the request succeeded

  2. Return the number of released search contexts === Multi-Search API

The multiSearch API executes multiple search requests in a single http request in parallel.

Multi-Search Request

The MultiSearchRequest is built empty and you add all of the searches that you wish to execute to it:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-request-basic]
  1. Create an empty MultiSearchRequest.

  2. Create an empty SearchRequest and populate it just like you would for a regular search.

  3. Add the SearchRequest to the MultiSearchRequest.

  4. Build a second SearchRequest and add it to the MultiSearchRequest.

Optional arguments

The SearchRequest`s inside of `MultiSearchRequest support all of search's optional arguments. For example:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-request-indices]
  1. Restricts the request to an index

Synchronous Execution

The multiSearch method executes `MultiSearchRequest`s synchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-execute]

Asynchronous Execution

The multiSearchAsync method executes MultiSearchRequest`s asynchronously, calling the provided `ActionListener when the response is ready.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-execute-async]
  1. The MultiSearchRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for MultiSearchResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole SearchRequest fails.

MultiSearchResponse

The MultiSearchResponse that is returned by executing the multiSearch method contains a MultiSearchResponse.Item for each SearchRequest in the MultiSearchRequest. Each MultiSearchResponse.Item contains an exception in getFailure if the request failed or a SearchResponse in getResponse if the request succeeded:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-response]
  1. The item for the first search.

  2. It succeeded so getFailure returns null.

  3. And there is a SearchResponse in getResponse.

  4. The item for the second search. === Search Template API

The search template API allows for searches to be executed from a template based on the mustache language, and also for previewing rendered templates.

Search Template Request

Inline Templates

In the most basic form of request, the search template is specified inline:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-template-request-inline]
  1. The search is executed against the posts index.

  2. The template defines the structure of the search source. It is passed as a string because mustache templates are not always valid JSON.

  3. Before running the search, the template is rendered with the provided parameters.

Registered Templates

Search templates can be registered in advance through stored scripts API. Note that the stored scripts API is not yet available in the high-level REST client, so in this example we use the low-level REST client.

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

Instead of providing an inline script, we can refer to this registered template in the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-template-request-stored]
Rendering Templates

Given parameter values, a template can be rendered without executing a search:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[render-search-template-request]
  1. Setting simulate to true causes the search template to only be rendered.

Both inline and pre-registered templates can be rendered.

Optional Arguments

As in standard search requests, the explain and profile options are supported:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-template-request-options]
Additional References

The {ref}/search-template.html[Search Template documentation] contains further examples of how search requests can be templated.

Synchronous Execution

The searchTemplate method executes the request synchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-template-execute]

Asynchronous Execution

A search template request can be executed asynchronously through the searchTemplateAsync method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-template-execute-async]
  1. The SearchTemplateRequest to execute and the ActionListener to call when the execution completes.

The asynchronous method does not block and returns immediately. Once the request completes, the ActionListener is called back using the onResponse method if the execution completed successfully, or using the onFailure method if it failed.

A typical listener for SearchTemplateResponse is constructed as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-template-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole SearchTemplateRequest fails.

Search Template Response

For a standard search template request, the response contains a SearchResponse object with the result of executing the search:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[search-template-response]

If simulate was set to true in the request, then the response will contain the rendered search source instead of a SearchResponse:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[render-search-template-response]
  1. The rendered source in bytes, in our example {"query": { "match" : { "title" : "elasticsearch" }}, "size" : 5}. === Multi-Search-Template API

The multiSearchTemplate API executes multiple search template requests in a single http request in parallel.

Multi-Search-Template Request

The MultiSearchTemplateRequest is built empty and you add all of the searches that you wish to execute to it:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-template-request-inline]
  1. Create an empty MultiSearchTemplateRequest.

  2. Create one or more SearchTemplateRequest objects and populate them just like you would for a regular search template.

  3. Add the SearchTemplateRequest to the MultiSearchTemplateRequest.

Optional arguments

The multiSearchTemplate’s max_concurrent_searches request parameter can be used to control the maximum number of concurrent searches the multi search api will execute. This default is based on the number of data nodes and the default search thread pool size.

Synchronous Execution

The multiSearchTemplate method executes `MultiSearchTemplateRequest`s synchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-template-request-sync]

Asynchronous Execution

The multiSearchTemplateAsync method executes MultiSearchTemplateRequest`s asynchronously, calling the provided `ActionListener when the response is ready.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-template-execute-async]

The parameters are the MultiSearchTemplateRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for MultiSearchTemplateResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-template-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole MultiSearchTemplateRequest fails.

MultiSearchTemplateResponse

The MultiSearchTemplateResponse that is returned by executing the multiSearchTemplate method contains a MultiSearchTemplateResponse.Item for each SearchTemplateRequest in the MultiSearchTemplateRequest. Each MultiSearchTemplateResponse.Item contains an exception in getFailure if the request failed or a SearchResponse in getResponse if the request succeeded:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[multi-search-template-response]
  1. An array of responses is returned - one response for each request

  2. Failed search template requests have error messages

  3. Successful requests contain a SearchResponse in getResponse.

    === Field Capabilities API

The field capabilities API allows for retrieving the capabilities of fields across multiple indices.

Field Capabilities Request

A FieldCapabilitiesRequest contains a list of fields to get capabilities for, should be returned, plus an optional list of target indices. If no indices are provided, the request will be executed on all indices.

Note that fields parameter supports wildcard notation. For example, providing text_* will cause all fields that match the expression to be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[field-caps-request]
Optional arguments
include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[field-caps-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded.

Synchronous Execution

The fieldCaps method executes the request synchronously:

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

Asynchronous Execution

The fieldCapsAsync method executes the request asynchronously, calling the provided ActionListener when the response is ready:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[field-caps-execute-async]
  1. The FieldCapabilitiesRequest to execute and the ActionListener to use when the execution completes.

The asynchronous method does not block and returns immediately. Once the request completes, the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for FieldCapabilitiesResponse is constructed as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[field-caps-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole FieldCapabilitiesRequest fails.

FieldCapabilitiesResponse

For each requested field, the returned FieldCapabilitiesResponse contains its type and whether or not it can be searched or aggregated on. The response also gives information about how each index contributes to the field’s capabilities.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[field-caps-response]
  1. A map with entries for the field’s possible types, in this case keyword and text.

  2. All indices where the user field has type keyword.

  3. The subset of these indices where the user field isn’t searchable, or null if it’s always searchable.

  4. Another subset of these indices where the user field isn’t aggregatable, or null if it’s always aggregatable. === Ranking Evaluation API

The rankEval method allows to evaluate the quality of ranked search results over a set of search request. Given sets of manually rated documents for each search request, ranking evaluation performs a multi search request and calculates information retrieval metrics like mean reciprocal rank, precision or discounted cumulative gain on the returned results.

Ranking Evaluation Request

In order to build a RankEvalRequest, you first need to create an evaluation specification (RankEvalSpec). This specification requires to define the evaluation metric that is going to be calculated, as well as a list of rated documents per search requests. Creating the ranking evaluation request then takes the specification and a list of target indices as arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[rank-eval-request-basic]
  1. Define the metric used in the evaluation

  2. Add rated documents, specified by index name, id and rating

  3. Create the search query to evaluate

  4. Combine the three former parts into a RatedRequest

  5. Create the ranking evaluation specification

  6. Create the ranking evaluation request

Synchronous Execution

The rankEval method executes `RankEvalRequest`s synchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[rank-eval-execute]

Asynchronous Execution

The rankEvalAsync method executes RankEvalRequest`s asynchronously, calling the provided `ActionListener when the response is ready.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[rank-eval-execute-async]
  1. The RankEvalRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for RankEvalResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[rank-eval-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole RankEvalRequest fails.

RankEvalResponse

The RankEvalResponse that is returned by executing the request contains information about the overall evaluation score, the scores of each individual search request in the set of queries and detailed information about search hits and details about the metric calculation per partial result.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[rank-eval-response]
  1. The overall evaluation result

  2. Partial results that are keyed by their query id

  3. The metric score for each partial result

  4. Rated search hits contain a fully fledged SearchHit

  5. Rated search hits also contain an Optional<Integer> rating that is not present if the document did not get a rating in the request

  6. Metric details are named after the metric used in the request

  7. After casting to the metric used in the request, the metric details offers insight into parts of the metric calculation

    === Explain API

The explain api computes a score explanation for a query and a specific document. This can give useful feedback whether a document matches or didn’t match a specific query.

Explain Request

An ExplainRequest expects an index, a type and an id to specify a certain document, and a query represented by QueryBuilder to run against it (the way of building queries).

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-request]
Optional arguments
include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-request-routing]
  1. Set a routing parameter

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-request-preference]
  1. Use the preference parameter e.g. to execute the search to prefer local shards. The default is to randomize across shards.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-request-source]
  1. Set to true to retrieve the _source of the document explained. You can also retrieve part of the document by using _source_include & _source_exclude (see Get API for more details)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-request-stored-field]
  1. Allows to control which stored fields to return as part of the document explained (requires the field to be stored separately in the mappings).

Synchronous Execution

The explain method executes the request synchronously:

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

Asynchronous Execution

The explainAsync method executes the request asynchronously, calling the provided ActionListener when the response is ready:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-execute-async]
  1. The ExplainRequest to execute and the ActionListener to use when the execution completes.

The asynchronous method does not block and returns immediately. Once the request completes, the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for ExplainResponse is constructed as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole ExplainRequest fails.

ExplainResponse

The ExplainResponse contains the following information:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[explain-response]
  1. The index name of the explained document.

  2. The type name of the explained document.

  3. The id of the explained document.

  4. Indicates whether or not the explained document exists.

  5. Indicates whether or not there is a match between the explained document and the provided query (the match is retrieved from the lucene Explanation behind the scenes if the lucene Explanation models a match, it returns true, otherwise it returns false).

  6. Indicates whether or not there exists a lucene Explanation for this request.

  7. Get the lucene Explanation object if there exists.

  8. Get the GetResult object if the _source or the stored fields are retrieved.

The GetResult contains two maps internally to store the fetched _source and stored fields. You can use the following methods to get them:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[get-result]
  1. Retrieve the _source as a map.

  2. Retrieve the specified stored fields as a map.

Count API

Count Request

The {request} is used to execute a query and get the number of matches for the query. The query to use in {request} can be set in similar way as query in SearchRequest using SearchSourceBuilder.

In its most basic form, we can add a query to the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-basic]
  1. Creates the {request}. Without arguments this runs against all indices.

  2. Most search parameters are added to the SearchSourceBuilder.

  3. Add a match_all query to the SearchSourceBuilder.

  4. Add the SearchSourceBuilder to the {request}.

Count Request optional arguments

Let’s first look at some of the optional arguments of a {request}:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-indices-types]
  1. Restricts the request to an index

  2. Limits the request to a type

There are a couple of other interesting optional parameters:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-routing]
  1. Set a routing parameter

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-request-preference]
  1. Use the preference parameter e.g. to execute the search to prefer local shards. The default is to randomize across shards.

Using the SearchSourceBuilder in CountRequest

Both in search and count API calls, most options controlling the search behavior can be set on the SearchSourceBuilder, which contains more or less the equivalent of the options in the search request body of the Rest API.

Here are a few examples of some common options:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-source-basics]
  1. Create a SearchSourceBuilder with default options.

  2. Set the query. Can be any type of QueryBuilder

After this, the SearchSourceBuilder only needs to be added to the {request}:

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

Note subtle difference when using SearchSourceBuilder in SearchRequest and using SearchSourceBuilder in {request} - using SearchSourceBuilder in SearchRequest one can use SearchSourceBuilder.size() and SearchSourceBuilder.from() methods to set the number of search hits to return, and the starting index. In {request} we’re interested in total number of matches and these methods have no meaning.

The Building Queries page gives a list of all available search queries with their corresponding QueryBuilder objects and QueryBuilders helper methods.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

CountResponse

The {response} that is returned by executing the count API call provides total count of hits and details about the count execution itself, like the HTTP status code, or whether the request terminated early:

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

The response also provides information about the execution on the shard level by offering statistics about the total number of shards that were affected by the underlying search, and the successful vs. unsuccessful shards. Possible failures can also be handled by iterating over an array off ShardSearchFailures like in the following example:

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

Miscellaneous APIs

The Java High Level REST Client supports the following Miscellaneous APIs:

Info API

Execution

Cluster information can be retrieved using the info() method:

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

Response

The returned MainResponse provides various kinds of information about the cluster:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[main-response]
  1. Retrieve the name of the cluster as a ClusterName

  2. Retrieve the unique identifier of the cluster

  3. Retrieve the name of the node the request has been executed on

  4. Retrieve the version of the node the request has been executed on

  5. Retrieve the build information of the node the request has been executed on === Ping API

Execution

The ping() method checks if the cluster is up and available to process requests and returns a boolean:

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

X-Pack Info API

Execution

General information about the installed {xpack} features can be retrieved using the xPackInfo() method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-info-execute]
  1. Enable verbose mode. The default is false but true will return more information.

  2. Set the categories of information to retrieve. The default is to return no information which is useful for checking if {xpack} is installed but not much else.

Response

The returned XPackInfoResponse can contain BuildInfo, LicenseInfo, and FeatureSetsInfo depending on the categories requested.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-info-response]
  1. BuildInfo contains the commit hash from which Elasticsearch was built and the timestamp that the x-pack module was created.

  2. LicenseInfo contains the type of license that the cluster is using and its expiration date.

  3. Basic licenses do not expire and will return this constant.

  4. FeatureSetsInfo contains a Map from the name of a feature to information about a feature like whether or not it is available under the current license.

Asynchronous Execution

This request can be executed asynchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-info-execute-async]
  1. The XPackInfoRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for XPackInfoResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-info-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument === X-Pack Usage API

Execution

Detailed information about the usage of features from {xpack} can be retrieved using the usage() method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-usage-execute]

Response

The returned XPackUsageResponse contains a Map keyed by feature name. Every feature map has an available key, indicating whether that feature is available given the current license, and an enabled key, indicating whether that feature is currently enabled. Other keys are specific to each feature.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-usage-response]

Asynchronous Execution

This request can be executed asynchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-usage-execute-async]
  1. The call to execute the usage api and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for XPackUsageResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java[x-pack-usage-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Indices APIs

The Java High Level REST Client supports the following Indices APIs:

Analyze API

Analyze Request

An {request} contains the text to analyze, and one of several options to specify how the analysis should be performed.

The simplest version uses a built-in analyzer:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-builtin-request]
  1. The text to include. Multiple strings are treated as a multi-valued field

  2. A built-in analyzer

You can configure a custom analyzer:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-custom-request]
  1. Configure char filters

  2. Configure the tokenizer

  3. Add a built-in tokenfilter

  4. Configuration for a custom tokenfilter

  5. Add the custom tokenfilter

You can also build a custom normalizer, by including only charfilters and tokenfilters:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-custom-normalizer-request]

You can analyze text using an analyzer defined in an existing index:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-index-request]
  1. The index containing the mappings

  2. The analyzer defined on this index to use

Or you can use a normalizer:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-index-normalizer-request]
  1. The index containing the mappings

  2. The normalizer defined on this index to use

You can analyze text using the mappings for a particular field in an index:

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

Optional arguments

The following arguments can also optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-explain]
  1. Setting explain to true will add further details to the response

  2. Setting attributes allows you to return only token attributes that you are interested in

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Analyze Response

The returned {response} allows you to retrieve details of the analysis as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response-tokens]
  1. AnalyzeToken holds information about the individual tokens produced by analysis

If explain was set to true, then information is instead returned from the detail() method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response-detail]
  1. DetailAnalyzeResponse holds more detailed information about tokens produced by the various substeps in the analysis chain.

Create Index API

Create Index Request

A {request} requires an index argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index to create

Index settings

Each index created can have specific settings associated with it.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-settings]
  1. Settings for this index

Index mappings

An index may be created with mappings for its document types

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-mappings]
  1. The type to define

  2. The mapping for this type, provided as a JSON string

The mapping source can be provided in different ways in addition to the String example shown above:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-mappings-map]
  1. Mapping source provided as a Map which gets automatically converted to JSON format

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-mappings-xcontent]
  1. Mapping source provided as an XContentBuilder object, the Elasticsearch built-in helpers to generate JSON content

Index aliases

Aliases can be set 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-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-aliases]
  1. The alias to define

Providing the whole source

The whole source including all of its sections (mappings, settings and aliases) can also be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-whole-source]
  1. The source provided as a JSON string. It can also be provided as a Map or an XContentBuilder.

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index creation as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-waitForActiveShards]
  1. The number of active shard copies to wait for before the create index API returns a response, as an int

  2. The number of active shard copies to wait for before the create index API returns a response, as an ActiveShardCount

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Create Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates whether the requisite number of shard copies were started for each shard in the index before timing out

Delete Index API

Delete Index Request

A {request} requires an index argument:

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

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index deletion as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the index deletion as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

If the index was not found, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-notfound]
  1. Do something if the index to be deleted was not found

Indices Exists API

Indices Exists Request

The high-level REST client uses a {request} for Indices Exists API. The index name (or indices' names) are required.

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

Optional arguments

Indices Exists API also accepts following optional arguments, through a {request}:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-optionals]
  1. Whether to return local information or retrieve the state from master node

  2. Return result in a format suitable for humans

  3. Whether to return all default setting for each of the indices

  4. Controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Response

The response is a {response} value, indicating whether the index (or indices) exist.

Open Index API

Open Index Request

An {request} requires an index argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index to open

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index is opened as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the index is opened as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-waitForActiveShards]
  1. The number of active shard copies to wait for before the open index API returns a response, as an int

  2. The number of active shard copies to wait for before the open index API returns a response, as an ActiveShardCount

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Open Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates whether the requisite number of shard copies were started for each shard in the index before timing out

Close Index API

Close Index Request

A {request} requires an index argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index to close

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index is closed as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the index is closed as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Close Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

Shrink Index API

Resize Request

The Shrink API requires a {request} instance. A {request} requires two string arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The target index (first argument) to shrink the source index (second argument) into

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index is opened as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the index is opened as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-waitForActiveShards]
  1. The number of active shard copies to wait for before the shrink index API returns a response, as an int

  2. The number of active shard copies to wait for before the shrink index API returns a response, as an ActiveShardCount

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-copySettings]
  1. Use true to copy the settings from the source index to the target index. This cannot be false. If this method is not used, default behavior is not to copy. This parameter will be removed in 8.0.0.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-settings]
  1. The settings to apply to the target index, which include the number of shards to create for it

  2. Remove the allocation requirement copied from the source index

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-aliases]
  1. The aliases to associate the target index with

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Shrink Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates whether the requisite number of shard copies were started for each shard in the index before timing out

Split Index API

Resize Request

The Split API requires a {request} instance. A {request} requires two string arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The target index (first argument) to split the source index (second argument) into

  2. The resize type needs to be set to SPLIT

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index is opened as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the index is opened as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-waitForActiveShards]
  1. The number of active shard copies to wait for before the split index API returns a response, as an int

  2. The number of active shard copies to wait for before the split index API returns a response, as an ActiveShardCount

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-settings]
  1. The settings to apply to the target index, which include the number of shards to create for it

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-aliases]
  1. The aliases to associate the target index with

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Split Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates whether the requisite number of shard copies were started for each shard in the index before timing out

Refresh API

Refresh Request

A {request} can be applied to one or more indices, or even on _all the indices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. Refresh one index

  2. Refresh multiple indices

  3. Refresh all the indices

Optional arguments

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Refresh Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Total number of shards hit by the refresh request

  2. Number of shards where the refresh has succeeded

  3. Number of shards where the refresh has failed

  4. A list of failures if the operation failed on one or more shards

By default, if the indices were not found, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-notfound]
  1. Do something if the indices to be refreshed were not found

Flush API

Flush Request

A {request} can be applied to one or more indices, or even on _all the indices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. Flush one index

  2. Flush multiple indices

  3. Flush all the indices

Optional arguments

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-wait]
  1. Set the wait_if_ongoing flag to true

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-force]
  1. Set the force flag to true

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Flush Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Total number of shards hit by the flush request

  2. Number of shards where the flush has succeeded

  3. Number of shards where the flush has failed

  4. A list of failures if the operation failed on one or more shards

By default, if the indices were not found, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-notfound]
  1. Do something if the indices to be flushed were not found

Flush Synced API

Flush Synced Request

A {request} can be applied to one or more indices, or even on _all the indices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. Flush synced one index

  2. Flush synced multiple indices

  3. Flush synced all the indices

Optional arguments

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Flush Synced Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Total number of shards hit by the flush request

  2. Number of shards where the flush has succeeded

  3. Number of shards where the flush has failed

  4. Name of the index whose results we are about to calculate.

  5. Total number of shards for index mentioned in 4.

  6. Successful shards for index mentioned in 4.

  7. Failed shards for index mentioned in 4.

  8. One of the failed shard ids of the failed index mentioned in 4.

  9. Reason for failure of copies of the shard mentioned in 8.

  10. JSON represented by a Map<String, Object>. Contains shard related information like id, state, version etc. for the failed shard copies. If the entire shard failed then this returns an empty map.

By default, if the indices were not found, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-notfound]
  1. Do something if the indices to be flushed were not found

Clear Cache API

Clear Cache Request

A {request} can be applied to one or more indices, or even on _all the indices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. Clears the cache of one index

  2. Clears the cache of multiple indices

  3. Clears the cache of all the indices

Optional arguments

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-query]
  1. Set the query flag to true

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-fielddata]
  1. Set the fielddata flag to true

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-request]
  1. Set the request flag to true

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-fields]
  1. Set the fields parameter

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Clear Cache Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Total number of shards hit by the clear cache request

  2. Number of shards where the clear cache has succeeded

  3. Number of shards where the clear cache has failed

  4. A list of failures if the operation failed on one or more shards

By default, if the indices were not found, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-notfound]
  1. Do something if the indices to be cleared were not found

Force Merge API

Force merge Request

A {request} can be applied to one or more indices, or even on _all the indices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. Force merge one index

  2. Force merge multiple indices

  3. Force merge all the indices

Optional arguments

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-segments-num]
  1. Set max_num_segments to control the number of segments to merge down to.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-only-expunge-deletes]
  1. Set the only_expunge_deletes flag to true

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-flush]
  1. Set the flush flag to true

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Force Merge Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Total number of shards hit by the force merge request

  2. Number of shards where the force merge has succeeded

  3. Number of shards where the force merge has failed

  4. A list of failures if the operation failed on one or more shards

By default, if the indices were not found, an ElasticsearchException will be thrown:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-notfound]
  1. Do something if the indices to be force merged were not found

Rollover Index API

Rollover Request

The Rollover Index API requires a {request} instance. A {request} requires two string arguments at construction time, and one or more conditions that determine when the index has to be rolled over:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The alias (first argument) that points to the index to rollover, and the name of the new index in case the rollover operation is performed. The new index argument is optional, and can be set to null

  2. Condition on the age of the index

  3. Condition on the number of documents in the index

  4. Condition on the size of the index

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-dryRun]
  1. Whether the rollover should be performed (default) or only simulated

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index is opened as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-waitForActiveShards]
  1. Sets the number of active shard copies to wait for before the rollover index API returns a response

  2. Resets the number of active shard copies to wait for to the default value

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-settings]
  1. Add the settings to apply to the new index, which include the number of shards to create for it

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-mapping]
  1. Add the mappings to associate the new index with. See Index mappings for examples on the different ways to provide mappings

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-alias]
  1. Add the aliases to associate the new index with

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Rollover Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates whether the requisite number of shard copies were started for each shard in the index before timing out

  3. The name of the old index, eventually rolled over

  4. The name of the new index

  5. Whether the index has been rolled over

  6. Whether the operation was performed or it was a dry run

  7. The different conditions and whether they were matched or not

Put Mapping API

Put Mapping Request

A {request} requires an index argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index to add the mapping to

Mapping source

A description of the fields to create on the mapping; if not defined, the mapping will default to empty.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-source]
  1. Mapping source provided as a String

Providing the mapping source

The mapping source can be provided in different ways in addition to the String example shown above:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-map]
  1. Mapping source provided as a Map which gets automatically converted to JSON format

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-xcontent]
  1. Mapping source provided as an XContentBuilder object, the Elasticsearch built-in helpers to generate JSON content

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index creation as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Put Mapping Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

Get Mappings API

Get Mappings Request

A {request} can have an optional list of indices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. An empty request that will return all indices

  2. Setting the indices to fetch mapping for

Optional arguments

The following arguments can also optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Options for expanding indices names

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Mappings Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Returning all indices' mappings

  2. Retrieving the mappings for a particular index

  3. Getting the mappings as a Java Map

Get Field Mappings API

Get Field Mappings Request

A {request} can have an optional list of indices, optional list of types and the list of fields:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. An empty request

  2. Setting the indices to fetch mapping for

  3. The fields to be returned

Optional arguments

The following arguments can also optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-local]
  1. The local flag (defaults to false) controls whether the aliases need to be looked up in the local cluster state or in the cluster state held by the elected master node

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Field Mappings Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Returning all requested indices fields' mappings

  2. Retrieving the mappings for a particular index

  3. Getting the mappings metadata for the message field

  4. Getting the full name of the field

  5. Getting the mapping source of the field

Index Aliases API

Indices Aliases Request

The Index Aliases API allows aliasing an index with a name, with all APIs automatically converting the alias name to the actual index name.

An {request} must have at least one AliasActions:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. Creates an IndicesAliasesRequest

  2. Creates an AliasActions that aliases index test1 with alias1

  3. Adds the alias action to the request

The following action types are supported: add - alias an index, remove - removes the alias associated with the index, and remove_index - deletes the index.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request2]
  1. Creates an alias alias1 with an optional filter on field year

  2. Creates an alias alias2 associated with two indices and with an optional routing

  3. Removes the associated alias alias3

  4. remove_index is just like Delete Index API

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the operation as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the operation as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Indices Aliases Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

Exists Alias API

Exists Alias Request

The Exists Alias API uses {request} as its request object. One or more aliases can be optionally provided either at construction time or later on through the relevant setter method.

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

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-alias]
  1. One or more aliases to look for

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indices]
  1. The index or indices that the alias is associated with

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-local]
  1. The local flag (defaults to false) controls whether the aliases need to be looked up in the local cluster state or in the cluster state held by the elected master node

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Exists Alias Response

The Exists Alias API returns a {response} that indicates whether the provided alias (or aliases) was found or not.

Get Alias API

Get Alias Request

The Get Alias API uses {request} as its request object. One or more aliases can be optionally provided either at construction time or later on through the relevant setter method.

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

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-alias]
  1. One or more aliases to retrieve

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indices]
  1. The index or indices that the alias is associated with

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded when looking for aliases that belong to specified indices.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-local]
  1. The local flag (defaults to false) controls whether the aliases need to be looked up in the local cluster state or in the cluster state held by the elected master node

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Alias Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Retrieves a map of indices and their aliases

Update Indices Settings API

The Update Indices Settings API allows to change specific index level settings.

Update Indices Settings Request

An {request}:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. Update settings for one index

  2. Update settings for multiple indices

  3. Update settings for all indices

Indices Settings

At least one setting to be updated must be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-create-settings]
  1. Sets the index settings to be applied

Providing the Settings

The settings to be applied can be provided in different ways:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-create-settings]
  1. Creates a setting as Settings

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-settings-builder]
  1. Settings provided as Settings.Builder

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-settings-source]
  1. Settings provided as String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-settings-map]
  1. Settings provided as a Map

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-preserveExisting]
  1. Whether to update existing settings. If set to true existing settings on an index remain unchanged, the default is false

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the new setting as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the new setting as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Update Indices Settings Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

Get Settings API

Get Settings Request

A {request} requires one or more index arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index whose settings we should retrieve

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-names]
  1. One or more settings that be the only settings retrieved. If unset, all settings will be retrieved

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-include-defaults]
  1. If true, defaults will be returned for settings not explicitly set on the index

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Settings Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. We can retrieve the setting value for a particular index directly from the response as a string

  2. We can also retrieve the Settings object for a particular index for further examination

  3. The returned Settings object provides convenience methods for non String types

If the includeDefaults flag was set to true in the {request} the behavior of {response} will differ somewhat.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-defaults-response]
  1. Individual default setting values may be retrieved directly from the {response}

  2. We may retrieve a Settings object for an index that contains those settings with default values

Put Template API

Put Index Template Request

A {request} specifies the name of a template and patterns which controls whether the template should be applied to the new index.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The name of the template

  2. The patterns of the template

Settings

The settings of the template will be applied to the new index whose name matches the template’s patterns.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-settings]
  1. Settings for this template

Mappings

The mapping of the template will be applied to the new index whose name matches the template’s patterns.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-mappings-json]
  1. The mapping, provided as a JSON string

The mapping source can be provided in different ways in addition to the String example shown above:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-mappings-map]
  1. Mapping source provided as a Map which gets automatically converted to JSON format

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-mappings-xcontent]
  1. Mapping source provided as an XContentBuilder object, the Elasticsearch built-in helpers to generate JSON content

Aliases

The aliases of the template will define aliasing to the index whose name matches the template’s patterns. A placeholder {index} can be used in an alias of a template.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-aliases]
  1. The alias to define

  2. The alias to define with placeholder

Order

In case multiple templates match an index, the orders of matching templates determine the sequence that settings, mappings, and alias of each matching template is applied. Templates with lower orders are applied first, and higher orders override them.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-order]
  1. The order of the template

Version

A template can optionally specify a version number which can be used to simplify template management by external systems.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-version]
  1. The version number of the template

Providing the whole source

The whole source including all of its sections (mappings, settings and aliases) can also be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-whole-source]
  1. The source provided as a JSON string. It can also be provided as a Map or an XContentBuilder.

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-create]
  1. To force to only create a new template; do not overwrite the existing template

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Put Index Template Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

Validate Query API

Validate Query Request

A {request} requires one or more indices on which the query is validated. If no index is provided the request is executed on all indices.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index on which to run the request.

In addition it also needs the query that needs to be validated. The query can be built using the QueryBuilders utility class. The following code snippet builds a sample boolean query.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-query]
  1. Build the desired query.

  2. Set it to the request.

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-explain]
  1. The explain parameter can be set to true to get more detailed information about why a query failed

By default, the request is executed on a single shard only, which is randomly selected. The detailed explanation of the query may depend on which shard is being hit, and therefore may vary from one request to another. So, in case of query rewrite the allShards parameter should be used to get response from all available shards.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-allShards]
  1. Set the allShards parameter.

When the query is valid, the explanation defaults to the string representation of that query. With rewrite set to true, the explanation is more detailed showing the actual Lucene query that will be executed

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-rewrite]
  1. Set the rewrite parameter.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Validate Query Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Check if the query is valid or not.

  2. Get total number of shards.

  3. Get number of shards that were successful.

  4. Get number of shards that failed.

  5. Get the shard failures as DefaultShardOperationFailedException.

  6. Get the index of a failed shard.

  7. Get the shard id of a failed shard.

  8. Get the reason for shard failure.

  9. Get the detailed explanation for the shards (if explain was set to true).

  10. Get the index to which a particular explanation belongs.

  11. Get the shard id to which a particular explanation belongs.

  12. Get the actual explanation string.

Get Templates API

The Get Templates API allows to retrieve a list of index templates by name.

Get Index Templates Request

A {request} specifies one or several names of the index templates to get.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. A single index template name

  2. Multiple index template names

  3. An index template name using wildcard

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Templates Response

The returned {response} consists a list of matching index templates.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. A list of matching index templates

Templates Exist API

Templates Exist Request

The Templates Exist API uses {request} as its request object. One or more index template names can be provided at construction.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. A single index template name

  2. Multiple index template names

  3. An index template name using wildcard

Optional arguments

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-optionals]
  1. If true, reads templates from the node’s local cluster state. Otherwise reads from the cluster state of the elected master node

  2. Timeout to connect to the master node as a TimeValue

  3. Timeout to connect to the master node as a String

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Response

The response is a {response} value, true if any of the request’s template names match existing templates and false otherwise

Get Index API

Get Index Request

A {request} requires one or more index arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index whose information we want to retrieve

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-includeDefaults]
  1. If true, defaults will be returned for settings not explicitly set on the index

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Retrieve a Map of different types to MappingMetadata for index.

  2. Retrieve a Map for the properties for document type doc.

  3. Get the list of aliases for index.

  4. Get the value for the setting string index.number_of_shards for index. If the setting was not explicitly specified but was part of the default settings (and includeDefault was true) then the default setting would be retrieved.

  5. Retrieve all settings for index.

  6. The Settings objects gives more flexibility. Here it is used to extract the setting index.number_of_shards as an integer.

  7. Get the default setting index.refresh_interval (if includeDefault was set to true). If includeDefault was set to false, getIndexResponse.defaultSettings() will return an empty map.

Freeze Index API

Freeze Index Request

An {request} requires an index argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index to freeze

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index is frozen as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-waitForActiveShards]
  1. The number of active shard copies to wait for before the freeze index API returns a response, as an ActiveShardCount

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Freeze Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates whether the requisite number of shard copies were started for each shard in the index before timing out

Unfreeze Index API

Unfreeze Index Request

An {request} requires an index argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The index to unfreeze

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the index is frozen as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-waitForActiveShards]
  1. The number of active shard copies to wait for before the unfreeze index API returns a response, as an ActiveShardCount

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request-indicesOptions]
  1. Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Unfreeze Index Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates whether the requisite number of shard copies were started for each shard in the index before timing out

Delete Template API

Request

The Delete Template API allows you to delete an index template.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-request]
  1. The name of an index template to delete.

Response

The returned {response} indicates if the delete template request was received.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-response]
  1. Whether or not the delete template request was acknowledged.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Cluster APIs

The Java High Level REST Client supports the following Cluster APIs:

Cluster Update Settings API

The Cluster Update Settings API allows to update cluster wide settings.

Cluster Update Settings Request

A {request}:

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

Cluster Settings

At least one setting to be updated must be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-cluster-settings]
  1. Sets the transient settings to be applied

  2. Sets the persistent setting to be applied

Providing the Settings

The settings to be applied can be provided in different ways:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-create-settings]
  1. Creates a transient setting as Settings

  2. Creates a persistent setting as Settings

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-settings-builder]
  1. Settings provided as Settings.Builder

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-settings-source]
  1. Settings provided as String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-settings-map]
  1. Settings provided as a Map

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the settings were applied as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the settings were applied as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Cluster Update Settings Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response]
  1. Indicates whether all of the nodes have acknowledged the request

  2. Indicates which transient settings have been applied

  3. Indicates which persistent settings have been applied

Cluster Get Settings API

The Cluster Get Settings API allows to get the cluster wide settings.

Cluster Get Settings Request

A {request}:

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

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-includeDefaults]
  1. By default only those settings that were explicitly set are returned. Setting this to true also returns the default settings.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-local]
  1. By default the request goes to the master of the cluster to get the latest results. If local is specified it gets the results from whichever node the request goes to.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Cluster Get Settings Response

The returned {response} allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response]
  1. Get the persistent settings.

  2. Get the transient settings.

  3. Get the default settings (returns empty settings if includeDefaults was not set to true).

  4. Get the value as a String for a particular setting. The order of searching is first in persistentSettings then in transientSettings and finally, if not found in either, in defaultSettings.

Cluster Health API

The Cluster Health API allows getting cluster health.

Cluster Health Request

A {request}:

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

There are no required parameters. By default, the client will check all indices and will not wait for any events.

Indices

Indices which should be checked can be passed in the constructor:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-indices-ctr]

Or using the corresponding setter method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-indices-setter]

Other parameters

Other parameters can be passed only through setter methods:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-timeout]
  1. Timeout for the request as a TimeValue. Defaults to 30 seconds

  2. As a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-master-timeout]
  1. Timeout to connect to the master node as a TimeValue. Defaults to the same as timeout

  2. As a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-wait-status]
  1. The status to wait (e.g. green, yellow, or red). Accepts a ClusterHealthStatus value.

  2. Using predefined method

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-wait-events]
  1. The priority of the events to wait for. Accepts a Priority value.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-level]
  1. The level of detail of the returned health information. Accepts a {request}.Level value.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-wait-relocation]
  1. Wait for 0 relocating shards. Defaults to false

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-wait-initializing]
  1. Wait for 0 initializing shards. Defaults to false

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-wait-nodes]
  1. Wait for N nodes in the cluster. Defaults to 0

  2. Using >=N, ⇐N, >N and <N notation

  3. Using ge(N), le(N), gt(N), lt(N) notation

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-wait-active]
  1. Wait for all shards to be active in the cluster

  2. Wait for N shards to be active in the cluster

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-request-local]
  1. Non-master node can be used for this request. Defaults to false

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Cluster Health Response

The returned {response} contains the next information about the cluster:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-general]
  1. Name of the cluster

  2. Cluster status (green, yellow or red)

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-request-status]
  1. Whether request was timed out while processing

  2. Status of the request (OK or REQUEST_TIMEOUT). Other errors will be thrown as exceptions

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-nodes]
  1. Number of nodes in the cluster

  2. Number of data nodes in the cluster

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-shards]
  1. Number of active shards

  2. Number of primary active shards

  3. Number of relocating shards

  4. Number of initializing shards

  5. Number of unassigned shards

  6. Number of unassigned shards that are currently being delayed

  7. Percent of active shards

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-task]
  1. Maximum wait time of all tasks in the queue

  2. Number of currently pending tasks

  3. Number of async fetches that are currently ongoing

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-indices]
  1. Detailed information about indices in the cluster

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-index]
  1. Detailed information about a specific index

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java[{api}-response-shard-details]
  1. Detailed information about a specific shard

Ingest APIs

The Java High Level REST Client supports the following Ingest APIs:

Put Pipeline API

Put Pipeline Request

A PutPipelineRequest requires an id argument, a source and a XContentType. The source consists of a description and a list of Processor objects.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[put-pipeline-request]
  1. The pipeline id

  2. The source for the pipeline as a ByteArray.

  3. The XContentType for the pipeline source supplied above.

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[put-pipeline-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the pipeline creation as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the pipeline creation as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[put-pipeline-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[put-pipeline-execute]
  1. Execute the request and get back the response in a WritePipelineResponse object.

Asynchronous Execution

The asynchronous execution of a put pipeline request requires both the PutPipelineRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[put-pipeline-execute-async]
  1. The PutPipelineRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for WritePipelineResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[put-pipeline-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Put Pipeline Response

The returned WritePipelineResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[put-pipeline-response]
  1. Indicates whether all of the nodes have acknowledged the request === Get Pipeline API

Get Pipeline Request

A GetPipelineRequest requires one or more pipelineIds to fetch.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[get-pipeline-request]
  1. The pipeline id to fetch

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[get-pipeline-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[get-pipeline-execute]
  1. Execute the request and get back the response in a GetPipelineResponse object.

Asynchronous Execution

The asynchronous execution of a get pipeline request requires both the GetPipelineRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[get-pipeline-execute-async]
  1. The GetPipelineRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for GetPipelineResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[get-pipeline-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Get Pipeline Response

The returned GetPipelineResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[get-pipeline-response]
  1. Check if a matching pipeline id was found or not.

  2. Get the list of pipelines found as a list of PipelineConfig objects.

  3. Get the individual configuration of each pipeline as a Map<String, Object>. === Delete Pipeline API

Delete Pipeline Request

A DeletePipelineRequest requires a pipeline id to delete.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[delete-pipeline-request]
  1. The pipeline id to delete

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[delete-pipeline-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the pipeline deletion as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the pipeline deletion as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[delete-pipeline-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[delete-pipeline-execute]
  1. Execute the request and get back the response in a WritePipelineResponse object.

Asynchronous Execution

The asynchronous execution of a delete pipeline request requires both the DeletePipelineRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[delete-pipeline-execute-async]
  1. The DeletePipelineRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for WritePipelineResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[delete-pipeline-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Delete Pipeline Response

The returned WritePipelineResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[delete-pipeline-response]
  1. Indicates whether all of the nodes have acknowledged the request === Simulate Pipeline API

Simulate Pipeline Request

A SimulatePipelineRequest requires a source and a XContentType. The source consists of the request body. See the docs for more details on the request body.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[simulate-pipeline-request]
  1. The request body as a ByteArray.

  2. The XContentType for the request body supplied above.

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[simulate-pipeline-request-pipeline-id]
  1. You can either specify an existing pipeline to execute against the provided documents, or supply a pipeline definition in the body of the request. This option sets the id for an existing pipeline.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[simulate-pipeline-request-verbose]
  1. To see the intermediate results of each processor in the simulate request, you can add the verbose parameter to the request.

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[simulate-pipeline-execute]
  1. Execute the request and get back the response in a SimulatePipelineResponse object.

Asynchronous Execution

The asynchronous execution of a simulate pipeline request requires both the SimulatePipelineRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[simulate-pipeline-execute-async]
  1. The SimulatePipelineRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for SimulatePipelineResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[simulate-pipeline-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Simulate Pipeline Response

The returned SimulatePipelineResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/IngestClientDocumentationIT.java[simulate-pipeline-response]
  1. Get results for each of the documents provided as instance of List<SimulateDocumentResult>.

  2. If the request was in verbose mode cast the response to SimulateDocumentVerboseResult.

  3. Check the result after each processor is applied.

  4. Get the ingest document for the result obtained in 3.

  5. Or get the failure for the result obtained in 3.

  6. Get the result as SimulateDocumentBaseResult if the result was not verbose.

  7. Get the ingest document for the result obtained in 6.

  8. Or get the failure for the result obtained in 6.

Snapshot APIs

The Java High Level REST Client supports the following Snapshot APIs:

Snapshot Get Repository API

The Snapshot Get Repository API allows to retrieve information about a registered repository.

Snapshot Get Repository Request

A GetRepositoriesRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-request]

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-request-repositories]
  1. Sets the repositories to retrieve

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-request-local]
  1. The local flag (defaults to false) controls whether the repositories need to be looked up in the local cluster state or in the cluster state held by the elected master node

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-execute]

Asynchronous Execution

The asynchronous execution of a snapshot get repository requires both the GetRepositoriesRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-execute-async]
  1. The GetRepositoriesRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for GetRepositoriesResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

Snapshot Get Repository Response

The returned GetRepositoriesResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-repository-response]

Snapshot Create RepositoryAPI

The Snapshot Create RepositoryAPI allows to register a snapshot repository.

Snapshot Create RepositoryRequest

A PutRepositoryRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request]

Repository Settings

Settings requirements will differ based on the repository backend chosen.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-repository-settings]
  1. Sets the repository settings

Providing the Settings

The settings to be applied can be provided in different ways:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-create-settings]
  1. Settings provided as Settings

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-settings-builder]
  1. Settings provided as Settings.Builder

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-settings-source]
  1. Settings provided as String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-settings-map]
  1. Settings provided as a Map

Required Arguments

The following arguments must be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-name]
  1. The name of the repository

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-type]
  1. The type of the repository

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the settings were applied as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the settings were applied as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-verify]
  1. Verify after creation as a Boolean

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-execute]

Asynchronous Execution

The asynchronous execution of a repository put settings requires both the PutRepositoryRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-execute-async]
  1. The PutRepositoryRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for PutRepositoryResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

Snapshot Create RepositoryResponse

The returned PutRepositoryResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-response]
  1. Indicates the node has acknowledged the request === Snapshot Delete Repository API

The Snapshot Delete Repository API allows to delete a registered repository.

Snapshot Delete Repository Request

A DeleteRepositoryRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-repository-request]

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the settings were applied as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the settings were applied as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-repository-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-repository-execute]

Asynchronous Execution

The asynchronous execution of a snapshot delete repository requires both the DeleteRepositoryRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-repository-execute-async]
  1. The DeleteRepositoryRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for DeleteRepositoryResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-repository-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

Snapshot Delete Repository Response

The returned DeleteRepositoryResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-repository-response]
  1. Indicates the node has acknowledged the request === Snapshot Verify Repository API

The Snapshot Verify Repository API allows to verify a registered repository.

Snapshot Verify Repository Request

A VerifyRepositoryRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[verify-repository-request]

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-repository-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the settings were applied as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the settings were applied as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[verify-repository-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[verify-repository-execute]

Asynchronous Execution

The asynchronous execution of a snapshot verify repository requires both the VerifyRepositoryRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[verify-repository-execute-async]
  1. The VerifyRepositoryRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for VerifyRepositoryResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[verify-repository-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

Snapshot Verify Repository Response

The returned VerifyRepositoryResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[verify-repository-response]

Create Snapshot API

Use the Create Snapshot API to create a new snapshot.

Create Snapshot Request

A CreateSnapshotRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request]

Required Arguments

The following arguments are mandatory:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-repositoryName]
  1. The name of the repository.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-snapshotName]
  1. The name of the snapshot.

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-indices]
  1. A list of indices the snapshot is applied to.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-indicesOptions]
  1. Options applied to the indices.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-partial]
  1. Set partial to true to allow a successful snapshot without the availability of all the indices primary shards. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-includeGlobalState]
  1. Set includeGlobalState to false to prevent writing the cluster’s global state as part of the snapshot. Defaults to true.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue.

  2. Timeout to connect to the master node as a String.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-request-waitForCompletion]
  1. Waits for the snapshot to be completed before a response is returned.

Synchronous Execution

Execute a CreateSnapshotRequest synchronously to receive a CreateSnapshotResponse.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-execute]

Retrieve the SnapshotInfo from a CreateSnapshotResponse when the snapshot is fully created. (The waitForCompletion parameter is true).

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-response-snapshot-info]
  1. The SnapshotInfo object.

Asynchronous Execution

The asynchronous execution of a create snapshot request requires both the CreateSnapshotRequest instance and an ActionListener instance to be passed as arguments to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-execute-async]
  1. The CreateSnapshotRequest to execute and the ActionListener to use when the execution completes.

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back with the onResponse method if the execution is successful or the onFailure method if the execution failed.

A typical listener for CreateSnapshotResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument.

  2. Called in case of a failure. The raised exception is provided as an argument.

Snapshot Create Response

Use the CreateSnapshotResponse to retrieve information about the evaluated request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[create-snapshot-response]
  1. Indicates the node has started the request. === Get Snapshots API

Use the Get Snapshot API to get snapshots.

Get Snapshots Request

A GetSnapshotsRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-request]

Required Arguments

The following arguments are mandatory:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-request-repositoryName]
  1. The name of the repository.

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-request-snapshots]
  1. An array of snapshots to get. Otherwise it will return all snapshots for a repository.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue.

  2. Timeout to connect to the master node as a String.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-request-verbose]
  1. Boolean indicating if the response should be verbose.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-request-ignore-unavailable]
  1. Boolean indicating if unavailable snapshots should be ignored. Otherwise the request will fail if any of the snapshots are unavailable.

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-execute]

Asynchronous Execution

The asynchronous execution of a get snapshots request requires both the GetSnapshotsRequest instance and an ActionListener instance to be passed as arguments to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-execute-async]
  1. The GetSnapshotsRequest to execute and the ActionListener to use when the execution completes.

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back with the onResponse method if the execution is successful or the onFailure method if the execution failed.

A typical listener for GetSnapshotsResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument.

  2. Called in case of a failure. The raised exception is provided as an argument.

Get Snapshots Response

The returned GetSnapshotsResponse allows the retrieval of information about the requested snapshots:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[get-snapshots-response]
  1. The REST status of a snapshot

  2. The snapshot id

  3. The current state of the snapshot

  4. Information about failures that occurred during the shard snapshot process.

  5. The snapshot start time

  6. The snapshot end time === Snapshots Status API

The Snapshots Status API allows to retrieve detailed information about snapshots in progress.

Snapshots Status Request

A SnapshotsStatusRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-request]

Required Arguments

The following arguments must be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-request-repository]
  1. Sets the repository to check for snapshot statuses

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-request-snapshots]
  1. The list of snapshot names to check the status of

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-request-ignoreUnavailable]
  1. The command will fail if some of the snapshots are unavailable. The ignore_unavailable flag set to true will return all snapshots that are currently available.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-execute]

Asynchronous Execution

The asynchronous execution of retrieving snapshot statuses requires both the SnapshotsStatusRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-execute-async]
  1. The SnapshotsStatusRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for SnapshotsStatusResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

Snapshots Status Response

The returned SnapshotsStatusResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[snapshots-status-response]
  1. Request contains a list of snapshot statuses

  2. Each status contains information about the snapshot

  3. Example of reading snapshot statistics about a specific index and shard === Delete Snapshot API

The Delete Snapshot API allows to delete a snapshot.

Delete Snapshot Request

A DeleteSnapshotRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-snapshot-request]

Optional Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-snapshot-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-snapshot-execute]

Asynchronous Execution

The asynchronous execution of a delete snapshot request requires both the DeleteSnapshotRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-snapshot-execute-async]
  1. The DeleteSnapshotRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for DeleteSnapshotResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-snapshot-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

Delete Snapshot Response

The returned DeleteSnapshotResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[delete-snapshot-response]
  1. Indicates the node has acknowledged the request === Restore Snapshot API

The Restore Snapshot API allows to restore a snapshot.

Restore Snapshot Request

A RestoreSnapshotRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request]

Limiting Indices to Restore

By default all indices are restored. With the indices property you can provide a list of indices that should be restored:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-indices]
  1. Request that Elasticsearch only restores "test_index".

Renaming Indices

You can rename indices using regular expressions when restoring a snapshot:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-rename]
  1. A regular expression matching the indices that should be renamed.

  2. A replacement pattern that references the group from the regular expression as $1. "test_index" from the snapshot is restored as "restored_index" in this example.

Index Settings and Options

You can also customize index settings and options when restoring:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-index-settings]
  1. Use #indexSettings() to set any specific index setting for the indices that are restored.

  2. Use #ignoreIndexSettings() to provide index settings that should be ignored from the original indices.

  3. Set IndicesOptions.Option.IGNORE_UNAVAILABLE in #indicesOptions() to have the restore succeed even if indices are missing in the snapshot.

Further Arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-waitForCompletion]
  1. Boolean indicating whether to wait until the snapshot has been restored.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-partial]
  1. Boolean indicating whether the entire snapshot should succeed although one or more indices participating in the snapshot don’t have all primary shards available.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-include-global-state]
  1. Boolean indicating whether restored templates that don’t currently exist in the cluster are added and existing templates with the same name are replaced by the restored templates. The restored persistent settings are added to the existing persistent settings.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-request-include-aliases]
  1. Boolean to control whether aliases should be restored. Set to false to prevent aliases from being restored together with associated indices.

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-execute]

Asynchronous Execution

The asynchronous execution of a restore snapshot request requires both the RestoreSnapshotRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-execute-async]
  1. The RestoreSnapshotRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for RestoreSnapshotResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument.

  2. Called in case of a failure. The raised exception is provided as an argument.

Restore Snapshot Response

The returned RestoreSnapshotResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SnapshotClientDocumentationIT.java[restore-snapshot-response]
  1. The RestoreInfo contains details about the restored snapshot like the indices or the number of successfully restored and failed shards.

Tasks APIs

The Java High Level REST Client supports the following Tasks APIs:

List Tasks API

The List Tasks API allows to get information about the tasks currently executing in the cluster.

List Tasks Request

A ListTasksRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-request]

There is no required parameters. By default the client will list all tasks and will not wait for task completion.

Parameters

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-request-filter]
  1. Request only cluster-related tasks

  2. Request all tasks running on nodes nodeId1 and nodeId2

  3. Request only children of a particular task

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-request-detailed]
  1. Should the information include detailed, potentially slow to generate data. Defaults to false

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-request-wait-completion]
  1. Should this request wait for all found tasks to complete. Defaults to false

  2. Timeout for the request as a TimeValue. Applicable only if setWaitForCompletion is true. Defaults to 30 seconds

  3. Timeout as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-execute]

Asynchronous Execution

The asynchronous execution of a cluster update settings requires both the ListTasksRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-execute-async]
  1. The ListTasksRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for ListTasksResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

List Tasks Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-response-tasks]
  1. List of currently running tasks

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-response-calc]
  1. List of tasks grouped by a node

  2. List of tasks grouped by a parent task

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[list-tasks-response-failures]
  1. List of node failures

  2. List of tasks failures === Cancel Tasks API

The Cancel Tasks API allows cancellation of a currently running task.

Cancel Tasks Request

A CancelTasksRequest:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-request]

There are no required parameters. The task cancellation command supports the same task selection parameters as the list tasks command.

Parameters

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-request-filter]
  1. Cancel a task

  2. Cancel only cluster-related tasks

  3. Cancel all tasks running on nodes nodeId1 and nodeId2

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-execute]

Asynchronous Execution

The asynchronous execution requires CancelTasksRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-execute-async]
  1. The CancelTasksRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for CancelTasksResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of a failure. The raised exception is provided as an argument

Cancel Tasks Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-response-tasks]
  1. List of cancelled tasks

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-response-calc]
  1. List of cancelled tasks grouped by a node

  2. List of cancelled tasks grouped by a parent task

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/TasksClientDocumentationIT.java[cancel-tasks-response-failures]
  1. List of node failures

  2. List of task cancellation failures

Script APIs

The Java High Level REST Client supports the following Scripts APIs:

Get Stored Script API

Get Stored Script Request

A GetStoredScriptRequest requires an id:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[get-stored-script-request]
  1. The id of the script

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[get-stored-script-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[get-stored-script-execute]

Asynchronous Execution

The asynchronous execution of a get stored script request requires both the GetStoredScriptRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[get-stored-script-execute-async]
  1. The GetStoredScriptRequest to execute and the ActionListener to use when the execution completes

Action Listener

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for GetStoredScriptResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[get-stored-script-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Get Stored Script Response

The returned GetStoredScriptResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[get-stored-script-response]
  1. The script object consists of a content and a metadata

  2. The language the script is written in, which defaults to painless.

  3. The content of the script

  4. Any named options that should be passed into the script. === Put Stored Script API

Put Stored Script Request

A PutStoredScriptRequest requires an id and content:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-request]
  1. The id of the script

  2. The content of the script

Content

The content of a script can be written in different languages and provided in different ways:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-content-painless]
  1. Specify a painless script and provided as XContentBuilder object. Note that the builder needs to be passed as a BytesReference object

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-content-mustache]
  1. Specify a mustache script and provided as XContentBuilder object. Note that value of source can be directly provided as a JSON string

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-context]
  1. The context the script should be executed in.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the script creation as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the script creation as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-execute]

Asynchronous Execution

The asynchronous execution of a put stored script request requires both the PutStoredScriptRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-execute-async]
  1. The PutStoredScriptRequest to execute and the ActionListener to use when the execution completes

Action Listener

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for AcknowledgedResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Put Stored Script Response

The returned AcknowledgedResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[put-stored-script-response]
  1. Indicates whether all of the nodes have acknowledged the request

Delete Stored Script API

Delete Stored Script Request

A DeleteStoredScriptRequest requires an id:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[delete-stored-script-request]
  1. The id of the script

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[delete-stored-script-request-timeout]
  1. Timeout to wait for the all the nodes to acknowledge the stored script is deleted as a TimeValue

  2. Timeout to wait for the all the nodes to acknowledge the stored script is deleted as a String

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[delete-stored-script-request-masterTimeout]
  1. Timeout to connect to the master node as a TimeValue

  2. Timeout to connect to the master node as a String

Synchronous Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[delete-stored-script-execute]

Asynchronous Execution

The asynchronous execution of a delete stored script request requires both the DeleteStoredScriptRequest instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[delete-stored-script-execute-async]
  1. The DeleteStoredScriptRequest to execute and the ActionListener to use when the execution completes

Action Listener

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for DeleteStoredScriptResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[delete-stored-script-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument

Delete Stored Script Response

The returned DeleteStoredScriptResponse allows to retrieve information about the executed operation as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/StoredScriptsDocumentationIT.java[delete-stored-script-response]
  1. Indicates whether all of the nodes have acknowledged the request

Licensing APIs

The Java High Level REST Client supports the following Licensing APIs:

Update License

Execution

The license can be added or updated using the putLicense() method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[put-license-execute]
  1. Set the categories of information to retrieve. The default is to return no information which is useful for checking if {xpack} is installed but not much else.

  2. A JSON document containing the license information.

Response

The returned PutLicenseResponse contains the LicensesStatus, acknowledged flag and possible acknowledge messages. The acknowledge messages are present if you previously had a license with more features than one you are trying to update and you didn’t set the acknowledge flag to true. In this case you need to display the messages to the end user and if they agree, resubmit the license with the acknowledge flag set to true. Please note that the request will still return a 200 return code even if requires an acknowledgement. So, it is necessary to check the acknowledged flag.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[put-license-response]
  1. The status of the license

  2. Make sure that the license is valid.

  3. Check the acknowledge flag. It should be true if license is acknowledged.

  4. Otherwise we can see the acknowledge messages in acknowledgeHeader()

  5. and check component-specific messages in acknowledgeMessages().

Asynchronous Execution

This request can be executed asynchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[put-license-execute-async]
  1. The PutLicenseRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for PutLicenseResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[put-license-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument === Get License

Execution

The license can be added or updated using the getLicense() method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-license-execute]

Response

The returned GetLicenseResponse contains the license in the JSON format.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-license-response]
  1. The text of the license.

Asynchronous Execution

This request can be executed asynchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-license-execute-async]
  1. The GetLicenseRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for GetLicenseResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-license-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument === Delete License

Execution

The license can be deleted using the deleteLicense() method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[delete-license-execute]

Response

The returned DeleteLicenseResponse contains the acknowledged flag, which returns true if the request was processed by all nodes.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[delete-license-response]
  1. Check the acknowledge flag. It should be true if license deletion is acknowledged.

Asynchronous Execution

This request can be executed asynchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[delete-license-execute-async]
  1. The DeleteLicenseRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for DeleteLicenseResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[delete-license-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument === Start Trial

Execution

This API creates and enables a trial license using the startTrial() method.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-trial-execute]
  1. Sets the "acknowledge" parameter to true, indicating the user has acknowledged that starting a trial license may affect commercial features

Response

The returned StartTrialResponse returns a field indicating whether the trial was started. If it was started, the response returns a the type of license started. If it was not started, it returns an error message describing why.

Acknowledgement messages may also be returned if this API was called without the acknowledge flag set to true. In this case you need to display the messages to the end user and if they agree, resubmit the request with the acknowledge flag set to true. Please note that the response will still return a 200 return code even if it requires an acknowledgement. So, it is necessary to check the acknowledged flag.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-trial-response]
  1. Whether or not the request had the acknowledge flag set

  2. Whether or not this request caused a trial to start

  3. If this request caused a trial to start, which type of license it registered

  4. If this request did not cause a trial to start, a message explaining why

  5. If the user’s request did not have the acknowledge flag set, a summary of the user’s acknowledgement required for this API

  6. If the user’s request did not have the acknowledge flag set, contains keys of commercial features and values of messages describing how they will be affected by licensing changes as the result of starting a trial

Asynchronous execution

This request can be executed asynchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-trial-execute-async]

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for StartTrialResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-trial-execute-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument === Start Basic License

Execution

This API creates and enables a basic license using the startBasic() method.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-basic-execute]

Response

The returned StartBasicResponse returns a field indicating whether the basic was started. If it was started, the response returns a the type of license started. If it was not started, it returns an error message describing why.

Acknowledgement messages may also be returned if this API was called without the acknowledge flag set to true. In this case you need to display the messages to the end user and if they agree, resubmit the request with the acknowledge flag set to true. Please note that the response will still return a 200 return code even if it requires an acknowledgement. So, it is necessary to check the acknowledged flag.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-basic-response]
  1. Whether or not the request had the acknowledge flag set

  2. Whether or not this request caused a basic to start

  3. If this request did not cause a basic to start, a message explaining why

  4. If the user’s request did not have the acknowledge flag set, a summary of the user’s acknowledgement required for this API

  5. If the user’s request did not have the acknowledge flag set, contains keys of commercial features and values of messages describing how they will be affected by licensing changes as the result of starting a basic

Asynchronous Execution

This request can be executed asynchronously:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-basic-execute-async]
  1. The StartBasicResponse to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for StartBasicResponse looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[start-basic-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument

  2. Called in case of failure. The raised exception is provided as an argument === Get Trial Status

Execution

The trial status of the license can be retrieved as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-trial-status-execute]

Response

The returned GetTrialStatusResponse holds only a boolean flag:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-trial-status-response]
  1. Whether the license is eligible to start trial or not === Get Basic Status

Execution

The basic status of the license can be retrieved as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-basic-status-execute]

Response

The returned GetTrialStatusResponse holds only a boolean flag:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/LicensingDocumentationIT.java[get-basic-status-response]
  1. Whether the license is eligible to start basic or not

Machine Learning APIs

The Java High Level REST Client supports the following Machine Learning APIs:

Put Job API

The Put Job API can be used to create a new {ml} job in the cluster. The API accepts a {request} object as a request and returns a {response}.

Put Job Request

A {request} requires the following argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The configuration of the {ml} job to create as a Job

Job Configuration

The Job object contains all the details about the {ml} job configuration.

A Job requires the following arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config]
  1. The job ID

  2. An analysis configuration

  3. A data description

  4. Optionally, a human-readable description

Analysis Configuration

The analysis configuration of the {ml} job is defined in the AnalysisConfig. AnalysisConfig reflects all the configuration settings that can be defined using the REST API.

Using the REST API, we could define this analysis configuration:

"analysis_config" : {
  "bucket_span" : "10m",
  "detectors" : [
    {
      "detector_description" : "Sum of total",
      "function" : "sum",
      "field_name" : "total"
    }
  ]
}

Using the AnalysisConfig object and the high level REST client, the list of detectors must be built first.

An example of building a Detector instance is as follows:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-detector]
  1. The function to use

  2. The field to apply the function to

  3. Optionally, a human-readable description

Then the same configuration would be:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-analysis-config]
  1. Create a list of detectors

  2. Pass the list of detectors to the analysis config builder constructor

  3. The bucket span

Data Description

After defining the analysis config, the next thing to define is the data description, using a DataDescription instance. DataDescription reflects all the configuration settings that can be defined using the REST API.

Using the REST API, we could define this metrics configuration:

"data_description" : {
  "time_field" : "timestamp"
}

Using the DataDescription object and the high level REST client, the same configuration would be:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-data-description]
  1. The time field

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Response

The returned {response} returns the full representation of the new {ml} job if it has been successfully created. This will contain the creation time and other fields initialized using default values:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The creation time is a field that was not passed in the Job object in the request

Get Job API

The Get Job API provides the ability to get {ml} jobs in the cluster. It accepts a {request} object and responds with a {response} object.

Get Job Request

A {request} object gets can have any number of jobId or groupName entries. However, they all must be non-null. An empty list is the same as requesting for all jobs.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing jobIds, can contain wildcards

  2. Whether to ignore if a wildcard expression matches no jobs. (This includes _all string or when no jobs have been specified)

Get Job Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. getCount() from the {response} indicates the number of jobs found

  2. getJobs() is the collection of {ml} Job objects found

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Job API

Delete Job Request

A {request} object requires a non-null jobId and can optionally set force.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-force]
  1. Use to forcefully delete an opened job; this method is quicker than closing and deleting the job. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-wait-for-completion]
  1. Use to set whether the request should wait until the operation has completed before returning. Defaults to true.

Delete Job Response

The returned {response} object indicates the acknowledgement of the job deletion or the deletion task depending on whether the request was set to wait for completion:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. whether was job deletion was acknowledged or not; will be null when set not to wait for completion

  2. the id of the job deletion task; will be null when set to wait for completion

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Open Job API

The Open Job API provides the ability to open {ml} jobs in the cluster. It accepts a {request} object and responds with a {response} object.

Open Job Request

An {request} object gets created with an existing non-null jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

  2. Optionally setting the timeout value for how long the execution should wait for the job to be opened.

Open Job Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isOpened() from the {response} indicates if the job was successfully opened or not.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Close Job API

The Close Job API provides the ability to close {ml} jobs in the cluster. It accepts a {request} object and responds with a {response} object.

Close Job Request

A {request} object gets created with an existing non-null jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing job IDs

  2. Optionally used to close a failed job, or to forcefully close a job which has not responded to its initial close request.

  3. Optionally set to ignore if a wildcard expression matches no jobs. (This includes _all string or when no jobs have been specified)

  4. Optionally setting the timeout value for how long the execution should wait for the job to be closed.

Close Job Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isClosed() from the {response} indicates if the job was successfully closed or not.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Update Job API

The Update Job API provides the ability to update a {ml} job. It accepts a {request} object and responds with a {response} object.

Update Job Request

An {request} object gets created with a JobUpdate object.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing a JobUpdate object

Optional Arguments

The JobUpdate object has many optional arguments with which to update an existing {ml} job. An existing, non-null jobId must be referenced in its creation.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-options]
  1. Mandatory, non-null jobId referencing an existing {ml} job

  2. Updated description

  3. Updated analysis limits

  4. Updated background persistence interval

  5. Updated analysis config’s categorization filters

  6. Updated detectors through the JobUpdate.DetectorUpdate object

  7. Updated group membership

  8. Updated result retention

  9. Updated model plot configuration

  10. Updated model snapshot retention setting

  11. Updated custom settings

  12. Updated renormalization window

Included with these options are specific optional JobUpdate.DetectorUpdate updates.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-detector-options]
  1. The index of the detector. O means unknown

  2. The optional description of the detector

  3. The DetectionRule rules that apply to this detector

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Update Job Response

A {response} contains the updated Job object

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. getResponse() returns the updated Job object

Flush Job API

The Flush Job API provides the ability to flush a {ml} job’s datafeed in the cluster. It accepts a {request} object and responds with a {response} object.

Flush Job Request

A {request} object gets created with an existing non-null jobId. All other fields are optional for the request.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-options]
  1. Set request to calculate the interim results

  2. Set the advanced time to flush to the particular time value

  3. Set the start time for the range of buckets on which to calculate the interim results (requires calc_interim to be true)

  4. Set the end time for the range of buckets on which to calculate interim results (requires calc_interim to be true)

  5. Set the skip time to skip a particular time value

Flush Job Response

A {response} contains an acknowledgement and an optional end date for the last finalized bucket

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isFlushed() indicates if the job was successfully flushed or not.

  2. getLastFinalizedBucketEnd() provides the timestamp (in milliseconds-since-the-epoch) of the end of the last bucket that was processed.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Put Datafeed API

The Put Datafeed API can be used to create a new {ml} datafeed in the cluster. The API accepts a {request} object as a request and returns a {response}.

Put Datafeed Request

A {request} requires the following argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The configuration of the {ml} datafeed to create

Datafeed Configuration

The DatafeedConfig object contains all the details about the {ml} datafeed configuration.

A DatafeedConfig requires the following arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config]
  1. The datafeed ID and the job ID

  2. The indices that contain the data to retrieve and feed into the job

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config-set-chunking-config]
  1. Specifies how data searches are split into time chunks.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config-set-frequency]
  1. The interval at which scheduled queries are made while the datafeed runs in real time.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config-set-query]
  1. A query to filter the search results by. Defaults to the 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-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config-set-query-delay]
  1. The time interval behind real time that data is queried.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config-set-delayed-data-check-config]
  1. Sets the delayed data check configuration. The window must be larger than the Job’s bucket size, but smaller than 24 hours, and span less than 10,000 buckets. Defaults to null, which causes an appropriate window span to be calculated when the datafeed runs. The default check_window span calculation is the max between 2h or 8 * bucket_span. To explicitly disable, pass DelayedDataCheckConfig.disabledDelayedDataCheckConfig().

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config-set-script-fields]
  1. Allows the use of script fields.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config-set-scroll-size]
  1. The size parameter used in the searches.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Response

The returned {response} returns the full representation of the new {ml} datafeed if it has been successfully created. This will contain the creation time and other fields initialized using default values:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The created datafeed

Update Datafeed API

The Update Datafeed API can be used to update a {ml} datafeed in the cluster. The API accepts a {request} object as a request and returns a {response}.

Update Datafeed Request

A {request} requires the following argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The updated configuration of the {ml} datafeed

Updated Datafeed Arguments

A DatafeedUpdate requires an existing non-null datafeedId and allows updating various settings.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config]
  1. Mandatory, non-null datafeedId referencing an existing {ml} datafeed

  2. Optional, set the datafeed Aggregations for data gathering

  3. Optional, the indices that contain the data to retrieve and feed into the job

  4. Optional, specifies how data searches are split into time chunks.

  5. Optional, the interval at which scheduled queries are made while the datafeed runs in real time.

  6. Optional, a query to filter the search results by. Defaults to the match_all query.

  7. Optional, the time interval behind real time that data is queried.

  8. Optional, allows the use of script fields.

  9. Optional, the size parameter used in the searches.

  10. Optional, the jobId that references the job that the datafeed should be associated with after the update.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Response

The returned {response} returns the full representation of the updated {ml} datafeed if it has been successfully updated.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The updated datafeed

Get Datafeed API

The Get Datafeed API provides the ability to get {ml} datafeeds in the cluster. It accepts a {request} object and responds with a {response} object.

Get Datafeed Request

A {request} object gets can have any number of datafeedId entries. However, they all must be non-null. An empty list is the same as requesting for all datafeeds.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing datafeedIds, can contain wildcards

  2. Whether to ignore if a wildcard expression matches no datafeeds. (This includes _all string or when no datafeeds have been specified)

Get Datafeed Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of retrieved datafeeds

  2. The retrieved datafeeds

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Datafeed API

Delete Datafeed Request

A {request} object requires a non-null datafeedId and can optionally set force.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Use to forcefully delete a started datafeed; this method is quicker than stopping and deleting the datafeed. Defaults to false.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Datafeed Response

The returned {response} object indicates the acknowledgement of the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isAcknowledged was the deletion request acknowledged or not

Preview Datafeed API

The Preview Datafeed API provides the ability to preview a {ml} datafeed’s data in the cluster. It accepts a {request} object and responds with a {response} object.

Preview Datafeed Request

A {request} object is created referencing a non-null datafeedId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing datafeedId

Preview Datafeed Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The raw BytesReference of the data preview

  2. A List<Map<String,Object>> that represents the previewed data

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Start Datafeed API

The Start Datafeed API provides the ability to start a {ml} datafeed in the cluster. It accepts a {request} object and responds with a {response} object.

Start Datafeed Request

A {request} object is created referencing a non-null datafeedId. All other fields are optional for the request.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing datafeedId

Optional Arguments

The following arguments are optional.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-options]
  1. Set when the datafeed should end, the value is exclusive. May be an epoch seconds, epoch millis or an ISO 8601 string. "now" is a special value that indicates the current time. If you do not specify an end time, the datafeed runs continuously.

  2. Set when the datafeed should start, the value is inclusive. May be an epoch seconds, epoch millis or an ISO 8601 string. If you do not specify a start time and the datafeed is associated with a new job, the analysis starts from the earliest time for which data is available.

  3. Set the timeout for the request

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Stop Datafeed API

The Stop Datafeed API provides the ability to stop a {ml} datafeed in the cluster. It accepts a {request} object and responds with a {response} object.

Stop Datafeed Request

A {request} object is created referencing any number of non-null datafeedId entries. Wildcards and _all are also accepted. All other fields are optional for the request.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing datafeedId entries.

Optional Arguments

The following arguments are optional.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-options]
  1. Whether to ignore if a wildcard expression matches no datafeeds. (This includes _all string)

  2. If true, the datafeed is stopped forcefully.

  3. Controls the amount of time to wait until a datafeed stops. The default value is 20 seconds.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Datafeed Stats API

The Get Datafeed Stats API provides the ability to get any number of {ml} datafeed’s statistics in the cluster. It accepts a {request} object and responds with a {response} object.

Get Datafeed Stats Request

A {request} object can have any number of datafeedId entries. However, they all must be non-null. An empty list is the same as requesting statistics for all datafeeds.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing datafeedIds, can contain wildcards

  2. Whether to ignore if a wildcard expression matches no datafeeds. (This includes _all string or when no datafeeds have been specified)

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Datafeed Stats Response

The returned {response} contains the requested datafeed statistics:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. count() indicates the number of datafeeds statistics found

  2. datafeedStats() is the collection of {ml} DatafeedStats objects found

Get Job Stats API

The Get Job Stats API provides the ability to get any number of {ml} job’s statistics in the cluster. It accepts a {request} object and responds with a {response} object.

Get Job Stats Request

A GetJobsStatsRequest object can have any number of jobId entries. However, they all must be non-null. An empty list is the same as requesting statistics for all jobs.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing jobIds, can contain wildcards

  2. Whether to ignore if a wildcard expression matches no jobs. (This includes _all string or when no jobs have been specified)

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Job Stats Response

The returned {response} contains the requested job statistics:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. getCount() indicates the number of jobs statistics found

  2. getJobStats() is the collection of {ml} JobStats objects found

Forecast Job API

The Forecast Job API provides the ability to forecast a {ml} job’s behavior based on historical data. It accepts a {request} object and responds with a {response} object.

Forecast Job Request

A {request} object gets created with an existing non-null jobId. All other fields are optional for the request.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-options]
  1. Set when the forecast for the job should expire

  2. Set how far into the future should the forecast predict

Forecast Job Response

A {response} contains an acknowledgement and the forecast ID

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isAcknowledged() indicates if the forecast was successful

  2. getForecastId() provides the ID of the forecast that was created

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Forecast API

The Delete Forecast API provides the ability to delete a {ml} job’s forecast in the cluster. It accepts a {request} object and responds with an {response} object.

Delete Forecast Request

A {request} object gets created with an existing non-null jobId. All other fields are optional for the request.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-options]
  1. Sets the specific forecastIds to delete, can be set to _all to indicate ALL forecasts for the given jobId

  2. Set the timeout for the request to respond, default is 30 seconds

  3. Set the allow_no_forecasts option. When true no error will be returned if an _all request finds no forecasts. It defaults to true

Delete Forecast Response

An {response} contains an acknowledgement of the forecast(s) deletion

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isAcknowledged() indicates if the forecast was successfully deleted or not.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Buckets API

The Get Buckets API retrieves one or more bucket results. It accepts a {request} object and responds with a {response} object.

Get Buckets Request

A {request} object gets created with an existing non-null jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-timestamp]
  1. The timestamp of the bucket to get. Otherwise it will return all buckets.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-anomaly-score]
  1. Buckets with anomaly scores greater or equal than this value will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-desc]
  1. If true, the buckets are sorted in descending order. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-end]
  1. Buckets with timestamps earlier than this time will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-exclude-interim]
  1. If true, interim results will be excluded. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-expand]
  1. If true, buckets will include their anomaly records. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page]
  1. The page parameters from and size. from specifies the number of buckets to skip. size specifies the maximum number of buckets to get. Defaults to 0 and 100 respectively.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-sort]
  1. The field to sort buckets on. Defaults to timestamp.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-start]
  1. Buckets with timestamps on or after this time will be returned.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Buckets Response

The returned {response} contains the requested buckets:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of buckets that were matched

  2. The buckets retrieved

Get Overall Buckets API

The Get Overall Buckets API retrieves overall bucket results that summarize the bucket results of multiple jobs. It accepts a {request} object and responds with a {response} object.

Get Overall Buckets Request

A {request} object gets created with one or more jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing job IDs jobId1 and jobId2.

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-bucket-span]
  1. The span of the overall buckets. Must be greater or equal to the jobs' largest bucket_span.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-end]
  1. Overall buckets with timestamps earlier than this time will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-exclude-interim]
  1. If true, interim results will be excluded. Overall buckets are interim if any of the job buckets within the overall bucket interval are interim. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-overall-score]
  1. Overall buckets with overall scores greater or equal than this value will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-start]
  1. Overall buckets with timestamps on or after this time will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-top-n]
  1. The number of top job bucket scores to be used in the overall_score calculation. Defaults to 1.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Overall Buckets Response

The returned {response} contains the requested buckets:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of overall buckets that were matched

  2. The overall buckets retrieved

Get Records API

The Get Records API retrieves one or more record results. It accepts a {request} object and responds with a {response} object.

Get Records Request

A {request} object gets created with an existing non-null jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-desc]
  1. If true, the records are sorted in descending order. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-end]
  1. Records with timestamps earlier than this time will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-exclude-interim]
  1. If true, interim results will be excluded. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page]
  1. The page parameters from and size. from specifies the number of records to skip. size specifies the maximum number of records to get. Defaults to 0 and 100 respectively.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-record-score]
  1. Records with record_score greater or equal than this value will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-sort]
  1. The field to sort records on. Defaults to record_score.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-start]
  1. Records with timestamps on or after this time will be returned.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Records Response

The returned {response} contains the requested records:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of records that were matched

  2. The records retrieved

Post Data API

The Post Data API provides the ability to post data to an open {ml} job in the cluster. It accepts a {request} object and responds with a {response} object.

Post Data Request

A {request} object gets created with an existing non-null jobId and the XContentType being sent. Individual docs can be added incrementally via the PostDataRequest.JsonBuilder#addDoc method. These are then serialized and sent in bulk when passed to the {request}.

Alternatively, the serialized bulk content can be set manually, along with its XContentType through one of the other {request} constructors.

Only XContentType.JSON and XContentType.SMILE are supported.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Create a new PostDataRequest.JsonBuilder object for incrementally adding documents

  2. Add a new document as a Map<String, Object> object

  3. Add a new document as a serialized JSON formatted String.

  4. Constructing a new request referencing an opened jobId, and a JsonBuilder

Optional Arguments

The following arguments are optional.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request-options]
  1. Set the start of the bucket resetting time

  2. Set the end of the bucket resetting time

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Post Data Response

A {response} contains current data processing statistics.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. getDataCounts() a DataCounts object containing the current data processing counts.

Get Influencers API

The Get Influencers API retrieves one or more influencer results. It accepts a {request} object and responds with a {response} object.

Get Influencers Request

A {request} object gets created with an existing non-null jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-desc]
  1. If true, the influencers are sorted in descending order. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-end]
  1. Influencers with timestamps earlier than this time will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-exclude-interim]
  1. If true, interim results will be excluded. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-influencer-score]
  1. Influencers with influencer_score greater or equal than this value will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page]
  1. The page parameters from and size. from specifies the number of influencers to skip. size specifies the maximum number of influencers to get. Defaults to 0 and 100 respectively.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-sort]
  1. The field to sort influencers on. Defaults to influencer_score.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-start]
  1. Influencers with timestamps on or after this time will be returned.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Influencers Response

The returned {response} contains the requested influencers:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of influencers that were matched

  2. The influencers retrieved

Get Categories API

The Get Categories API retrieves one or more category results. It accepts a {request} object and responds with a {response} object.

Get Categories Request

A {request} object gets created with an existing non-null jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-category-id]
  1. The id of the category to get. Otherwise it will return all categories.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page]
  1. The page parameters from and size. from specifies the number of categories to skip. size specifies the maximum number of categories to get. Defaults to 0 and 100 respectively.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Categories Response

The returned {response} contains the requested categories:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of categories that were matched

  2. The categories retrieved

Get Calendars API

Retrieves one or more calendar objects. It accepts a {request} and responds with a {response} object.

Get Calendars Request

By default a {request} with no calendar Id set will return all calendars. Using the literal _all also returns all calendars.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request for all calendars

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-id]
  1. Construct a request for the single calendar holidays

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page]
  1. The page parameters from and size. from specifies the number of calendars to skip. size specifies the maximum number of calendars to get. Defaults to 0 and 100 respectively.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get calendars Response

The returned {response} contains the requested calendars:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of calendars that were matched

  2. The calendars retrieved

Put Calendar API

Creates a new {ml} calendar. The API accepts a {request} and responds with a {response} object.

Put Calendar Request

A {request} is constructed with a Calendar object

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Create a request with the given Calendar

Put Calendar Response

The returned {response} contains the created Calendar:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The created Calendar

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Calendar Events API

Retrieves a calendars events. It accepts a {request} and responds with a {response} object.

Get Calendars Request

A {request} requires a non-null calendar ID. Using the literal _all returns the events for all calendars.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request for the specified calendarId

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page]
  1. The page parameters from and size. from specifies the number of events to skip. size specifies the maximum number of events to get. Defaults to 0 and 100 respectively.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-start]
  1. Specifies to get events with timestamps after this time.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-end]
  1. Specifies to get events with timestamps earlier than this time.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-jobid]
  1. Get events for the job. When this option is used calendar_id must be _all

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get calendars Response

The returned {response} contains the requested events:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of events that were matched

  2. The events retrieved

Post Calendar Event API

Adds new ScheduledEvents to an existing {ml} calendar.

The API accepts a {request} and responds with a {response} object.

Post Calendar Event Request

A {request} is constructed with a calendar ID object and a non-empty list of scheduled events.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Non-null existing calendar ID

  2. Non-null, non-empty collection of ScheduledEvent objects

Post Calendar Event Response

The returned {response} contains the added ScheduledEvent objects:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The ScheduledEvent objects that were added to the calendar

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Calendar Event API

Removes a scheduled event from an existing {ml} calendar. The API accepts a {request} and responds with a {response} object.

Delete Calendar Event Request

A {request} is constructed referencing a non-null calendar ID, and eventId which to remove from the calendar

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The ID of the calendar from which to remove the jobs

  2. The eventId to remove from the calendar

Delete Calendar Event Response

The returned {response} acknowledges the success of the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. Acknowledgement of the request and its success

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Put Calendar Job API

Adds {ml} jobs to an existing {ml} calendar. The API accepts a {request} and responds with a {response} object.

Put Calendar Job Request

A {request} is constructed referencing a non-null calendar ID, and JobIDs to which to add to the calendar

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The ID of the calendar to which to add the jobs

  2. The JobIds to add to the calendar

Put Calendar Response

The returned {response} contains the updated Calendar:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The updated Calendar

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Calendar Job API

Removes {ml} jobs from an existing {ml} calendar. The API accepts a {request} and responds with a {response} object.

Delete Calendar Job Request

A {request} is constructed referencing a non-null calendar ID, and JobIDs which to remove from the calendar

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The ID of the calendar from which to remove the jobs

  2. The JobIds to remove from the calendar

Delete Calendar Job Response

The returned {response} contains the updated Calendar:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The updated Calendar with the jobs removed

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Calendar API

Delete a {ml} calendar. The API accepts a {request} and responds with a {response} object.

Delete Calendar Request

A DeleteCalendar object requires a non-null calendarId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing Calendar

Delete Calendar Response

The returned {response} object indicates the acknowledgement of the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isAcknowledged was the deletion request acknowledged or not

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Put Filter API

The Put Filter API can be used to create a new {ml} filter in the cluster. The API accepts a {request} object as a request and returns a {response}.

Put Filter Request

A {request} requires the following argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The configuration of the {ml} filter to create as a MlFilter

Filter Configuration

The MlFilter object contains all the details about the {ml} filter configuration.

A MlFilter contains the following arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-config]
  1. Required, the filter ID

  2. Optional, the filter description

  3. Optional, the items of the filter. A wildcard * can be used at the beginning or the end of an item. Up to 10000 items are allowed in each filter.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Response

The returned {response} returns the full representation of the new {ml} filter if it has been successfully created.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The newly created MlFilter

Get Filters API

The Get Filters API retrieves one or more filter results. It accepts a {request} object and responds with a {response} object.

Get Filters Request

A {request} object gets created.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-filter-id]
  1. The id of the filter to get. Otherwise it will return all filters.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page-params]
  1. from specifies the number of filters to skip. Defaults to 0.

  2. size specifies the maximum number of filters to get. Defaults to 100.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Filters Response

The returned {response} contains the requested filters:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of filters that were matched

  2. The filters retrieved

Update Filter API

The Update Filter API can be used to update an existing {ml} filter in the cluster. The API accepts a {request} object as a request and returns a {response}.

Update Filter Request

A {request} requires the following argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. The id of the existing {ml} filter

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-description]
  1. The updated description of the {ml} filter

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-add-items]
  1. The list of items to add to the {ml} filter

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-remove-items]
  1. The list of items to remove from the {ml} filter

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Response

The returned {response} returns the full representation of the updated {ml} filter if it has been successfully updated.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The updated MlFilter

Delete Filter API

Delete a {ml} filter. The API accepts a {request} and responds with a {response} object.

Delete Filter Request

A {request} object requires a non-null filterId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing filter

Delete Filter Response

The returned {response} object indicates the acknowledgement of the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isAcknowledged was the deletion request acknowledged or not

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Model Snapshots API

The Get Model Snapshots API retrieves one or more model snapshot results. It accepts a {request} object and responds with a {response} object.

Get Model Snapshots Request

A {request} object gets created with an existing non-null jobId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing an existing jobId

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-snapshot-id]
  1. The id of the snapshot to get. Otherwise it will return all snapshots.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-desc]
  1. If true, the snapshots are sorted in descending order. Defaults to false.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-end]
  1. Snapshots with timestamps earlier than this time will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-sort]
  1. The field to sort snapshots on. Defaults to timestamp.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-start]
  1. Snapshots with timestamps on or after this time will be returned.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-page]
  1. The page parameters from and size. from specifies the number of snapshots to skip. size specifies the maximum number of snapshots to retrieve. Defaults to 0 and 100 respectively.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Model Snapshots Response

The returned {response} contains the requested snapshots:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The count of snapshots that were matched

  2. The snapshots retrieved

Delete Model Snapshot API

Delete Model Snapshot Request

A {request} object requires both a non-null jobId and a non-null snapshotId.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing jobId and snapshotId.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Model Snapshot Response

The returned {response} object indicates the acknowledgement of the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isAcknowledged was the deletion request acknowledged or not

Revert Model Snapshot API

The Revert Model Snapshot API provides the ability to revert to a previous {ml} model snapshot. It accepts a {request} object and responds with a {response} object.

Revert Model Snapshot Request

A {request} requires the following arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing jobId and snapshotId values.

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-delete-intervening-results]
  1. A flag indicating whether or not results in the period between the timestamp on the reverted snapshot and the latest results should be deleted

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Revert Job Response

A {response} contains the full representation of the reverted ModelSnapshot.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. The reverted ModelSnapshot

Update Model Snapshot API

The Update Model Snapshot API provides the ability to update a {ml} model snapshot. It accepts a {request} object and responds with a {response} object.

Update Model Snapshot Request

A {request} requires the following arguments:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing existing jobId and snapshotId values.

Optional Arguments

The following arguments are optional:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-description]
  1. The updated description of the {ml} model snapshot

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-retain]
  1. The updated retain property of the {ml} model snapshot

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Update Job Response

A {response} contains an acknowledgement of the update request and the full representation of the updated ModelSnapshot object

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. An acknowledgement of the request

  2. The updated ModelSnapshot

ML Get Info API

The ML Get API provides defaults and limits used internally by {ml}. These may be useful to a user interface that needs to interpret machine learning configurations where certain fields are missing because the end user was happy with the default value.

It accepts a {request} object and responds with a {response} object.

Get Info Request

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request

ML Get Info Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. info from the {response} contains ml info details

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Delete Expired Data API

Delete expired {ml} data. The API accepts a {request} and responds with a {response} object.

Delete Expired Data Request

A DeleteExpiredDataRequest object does not require any arguments.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request.

Delete Expired Data Response

The returned {response} object indicates the acknowledgement of the request:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. getDeleted acknowledges the deletion request.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Set Upgrade Mode API

The Set Upgrade Mode API temporarily halts all {ml} job and {dfeed} tasks when enabled=true. Their reported states remain unchanged. Consequently, when exiting upgrade mode the halted {ml} jobs and {dfeeds} will return to their previous state.

It accepts a {request} object and responds with a {response} object.

When enabled=true, no new jobs can be opened, and no job or {dfeed} tasks will be running. Be sure to set enabled=false once upgrade actions are completed.

Set Upgrade Mode Request

A {request} object gets created setting the desired enabled state.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-request]
  1. Constructing a new request referencing enabling upgrade mode

  2. Optionally setting the timeout value for how long the execution should wait.

Set Upgrade Mode Response

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-response]
  1. isAcknowledged() from the {response} indicates if the setting was set successfully.

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Migration APIs

The Java High Level REST Client supports the following Migration APIs:

Migration Get Assistance

Index Upgrade Info Request

An IndexUpgradeInfoRequest does not require any argument:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[get-assistance-request]
  1. Create a new request instance

Optional arguments

The following arguments can optionally be provided:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[get-assistance-request-indices]
  1. Set the indices to the request

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[get-assistance-request-indices-options]
  1. Set the IndicesOptions to control how unavailable indices are resolved and how wildcard expressions are expanded

Execution

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[get-assistance-execute]

Response

The returned IndexUpgradeInfoResponse contains the actions required for each index.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[get-assistance-response]
  1. Retrieve the index

  2. Retrieve the action required for the migration of the current index

Migration Upgrade

Index Upgrade Request

An {request} requires an index argument. Only one index at the time should be upgraded:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[{api}-request]
  1. Create a new request instance

Execution

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

Response

The returned {response} contains information about the executed operation

Asynchronous Execution

The asynchronous execution of an upgrade request requires both the {request} instance and an ActionListener instance to be passed to the asynchronous method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[{api}-async-listener]
  1. Called when the execution is successfully completed. The response is provided as an argument and contains a list of individual results for each operation that was executed. Note that one or more operations might have failed while the others have been successfully executed.

  2. Called when the whole {request} fails. In this case the raised exception is provided as an argument and no operation has been executed.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[{api}-async-execute]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

Migration Upgrade with Task API

Submission of upgrade request task will requires the {request} and will return {submit_response}. The {submit_response} can later be use to fetch TaskId and query the Task API for results.

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

Get Deprecation Info

Get Deprecation Info Request

A {request} can be applied to one or more indices:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[{api}-request]
  1. Create a new request instance

Synchronous Execution

When executing a {request} in the following manner, the client waits for the {response} to be returned before continuing with code execution:

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

Synchronous calls may throw an IOException in case of either failing to parse the REST response in the high-level REST client, the request times out or similar cases where there is no response coming back from the server.

In cases where the server returns a 4xx or 5xx error code, the high-level client tries to parse the response body error details instead and then throws a generic ElasticsearchException and adds the original ResponseException as a suppressed exception to it.

Asynchronous Execution

Executing a {request} can also be done in an asynchronous fashion so that the client can return directly. Users need to specify how the response or potential failures will be handled by passing the request and a listener to the asynchronous {api} method:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[{api}-execute-async]
  1. The {request} to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed. Failure scenarios and expected exceptions are the same as in the synchronous execution case.

A typical listener for {api} looks like:

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[{api}-execute-listener]
  1. Called when the execution is successfully completed.

  2. Called when the whole {request} fails.

Get Deprecation Info Response

The returned {response} contains information about deprecated features currently in use at the cluster, node, and index level.

include-tagged::/fresh_work/warex/file_cache/linux/www/elasticsearch-6.8.23-src.tar.gz/elasticsearch-6.8.23/docs/java-rest/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MigrationClientDocumentationIT.java[{api}-response]
  1. a List of Cluster deprecations

  2. a List of Node deprecations

  3. a Map of key IndexName, value List of deprecations for the index

  4. a list of Machine Learning related deprecations

Rollup APIs

The Java High Level REST Client supports the following Rollup APIs:

Put Rollup Job API

experimental::[]

The Put Rollup Job API can be used to create a new Rollup job in the cluster. The API accepts a PutRollupJobRequest object as a request and returns a PutRollupJobResponse.

<