Docs: Cut down on high level rest client copy-and-paste-ness (#34125)
* Anchors * includes * get settings * more * More
This commit is contained in:
Nik Everett
GitHub
parent
68b42f7d89
commit
47bcb56a89
|
|
@ -55,22 +55,8 @@ import static org.hamcrest.Matchers.greaterThan;
|
|||
import static org.hamcrest.Matchers.notNullValue;
|
||||
|
||||
/**
|
||||
* This class is used to generate the Java Cluster API documentation.
|
||||
* You need to wrap your code between two tags like:
|
||||
* // tag::example
|
||||
* // end::example
|
||||
*
|
||||
* Where example is your tag name.
|
||||
*
|
||||
* Then in the documentation, you can extract what is between tag and end tags with
|
||||
* ["source","java",subs="attributes,callouts,macros"]
|
||||
* --------------------------------------------------
|
||||
* include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[example]
|
||||
* --------------------------------------------------
|
||||
*
|
||||
* The column width of the code block is 84. If the code contains a line longer
|
||||
* than 84, the line will be cut and a horizontal scroll bar will be displayed.
|
||||
* (the code indentation of the tag is not included in the width)
|
||||
* Documentation for Cluster APIs in the high level java client.
|
||||
* Code wrapped in {@code tag} and {@code end} tags is included in the docs.
|
||||
*/
|
||||
public class ClusterClientDocumentationIT extends ESRestHighLevelClientTestCase {
|
||||
|
||||
|
|
|
|||
|
|
@ -1,16 +1,22 @@
|
|||
[[java-rest-high-cluster-get-settings]]
|
||||
--
|
||||
:api: get-settings
|
||||
:request: ClusterGetSettingsRequest
|
||||
:response: ClusterGetSettingsResponse
|
||||
--
|
||||
|
||||
[id="{upid}-{api}"]
|
||||
=== Cluster Get Settings API
|
||||
|
||||
The Cluster Get Settings API allows to get the cluster wide settings.
|
||||
|
||||
[[java-rest-high-cluster-get-settings-request]]
|
||||
[id="{upid}-{api}-request"]
|
||||
==== Cluster Get Settings Request
|
||||
|
||||
A `ClusterGetSettingsRequest`:
|
||||
A +{request}+:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request]
|
||||
include-tagged::{doc-tests-file}[{api}-request]
|
||||
--------------------------------------------------
|
||||
|
||||
==== Optional arguments
|
||||
|
|
@ -18,75 +24,40 @@ The following arguments can optionally be provided:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-includeDefaults]
|
||||
include-tagged::{doc-tests-file}[{api}-request-includeDefaults]
|
||||
--------------------------------------------------
|
||||
<1> By default only those settings that were explicitly set are returned. Setting this to true also returns
|
||||
the default settings.
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-local]
|
||||
include-tagged::{doc-tests-file}[{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.
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-masterTimeout]
|
||||
include-tagged::{doc-tests-file}[{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`
|
||||
|
||||
[[java-rest-high-cluster-get-settings-sync]]
|
||||
==== Synchronous Execution
|
||||
include::../execution.asciidoc[]
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute]
|
||||
--------------------------------------------------
|
||||
<1> Execute the request and get back the response in a `ClusterGetSettingsResponse` object.
|
||||
|
||||
[[java-rest-high-cluster-get-settings-async]]
|
||||
==== Asynchronous Execution
|
||||
|
||||
The asynchronous execution of a cluster get settings requires both the
|
||||
`ClusterGetSettingsRequest` instance and an `ActionListener` instance to be
|
||||
passed to the asynchronous method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The `ClusterGetSettingsRequest` 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 `ClusterGetSettingsResponse` looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-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
|
||||
|
||||
[[java-rest-high-cluster-get-settings-response]]
|
||||
[id="{upid}-{api}-response"]
|
||||
==== Cluster Get Settings Response
|
||||
|
||||
The returned `ClusterGetSettingsResponse` allows to retrieve information about the
|
||||
The returned +{response}+ allows to retrieve information about the
|
||||
executed operation as follows:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-response]
|
||||
include-tagged::{doc-tests-file}[{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`.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,16 +1,22 @@
|
|||
[[java-rest-high-cluster-health]]
|
||||
--
|
||||
:api: health
|
||||
:request: ClusterHealthRequest
|
||||
:response: ClusterHealthResponse
|
||||
--
|
||||
|
||||
[id="{upid}-{api}"]
|
||||
=== Cluster Health API
|
||||
|
||||
The Cluster Health API allows getting cluster health.
|
||||
|
||||
[[java-rest-high-cluster-health-request]]
|
||||
[id="{upid}-{api}-request"]
|
||||
==== Cluster Health Request
|
||||
|
||||
A `ClusterHealthRequest`:
|
||||
A +{request}+:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request]
|
||||
include-tagged::{doc-tests-file}[{api}-request]
|
||||
--------------------------------------------------
|
||||
There are no required parameters. By default, the client will check all indices and will not wait
|
||||
for any events.
|
||||
|
|
@ -21,14 +27,14 @@ Indices which should be checked can be passed in the constructor:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-ctr]
|
||||
include-tagged::{doc-tests-file}[{api}-request-indices-ctr]
|
||||
--------------------------------------------------
|
||||
|
||||
Or using the corresponding setter method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-setter]
|
||||
include-tagged::{doc-tests-file}[{api}-request-indices-setter]
|
||||
--------------------------------------------------
|
||||
|
||||
==== Other parameters
|
||||
|
|
@ -37,53 +43,53 @@ Other parameters can be passed only through setter methods:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-timeout]
|
||||
include-tagged::{doc-tests-file}[{api}-request-timeout]
|
||||
--------------------------------------------------
|
||||
<1> Timeout for the request as a `TimeValue`. Defaults to 30 seconds
|
||||
<2> As a `String`
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-master-timeout]
|
||||
include-tagged::{doc-tests-file}[{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`
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-status]
|
||||
include-tagged::{doc-tests-file}[{api}-request-wait-status]
|
||||
--------------------------------------------------
|
||||
<1> The status to wait (e.g. `green`, `yellow`, or `red`). Accepts a `ClusterHealthStatus` value.
|
||||
<2> Using predefined method
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-events]
|
||||
include-tagged::{doc-tests-file}[{api}-request-wait-events]
|
||||
--------------------------------------------------
|
||||
<1> The priority of the events to wait for. Accepts a `Priority` value.
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-level]
|
||||
include-tagged::{doc-tests-file}[{api}-request-level]
|
||||
--------------------------------------------------
|
||||
<1> The level of detail of the returned health information. Accepts a `ClusterHealthRequest.Level` value.
|
||||
<1> The level of detail of the returned health information. Accepts a +{request}.Level+ value.
|
||||
Default value is `cluster`.
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-relocation]
|
||||
include-tagged::{doc-tests-file}[{api}-request-wait-relocation]
|
||||
--------------------------------------------------
|
||||
<1> Wait for 0 relocating shards. Defaults to `false`
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-initializing]
|
||||
include-tagged::{doc-tests-file}[{api}-request-wait-initializing]
|
||||
--------------------------------------------------
|
||||
<1> Wait for 0 initializing shards. Defaults to `false`
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-nodes]
|
||||
include-tagged::{doc-tests-file}[{api}-request-wait-nodes]
|
||||
--------------------------------------------------
|
||||
<1> Wait for `N` nodes in the cluster. Defaults to `0`
|
||||
<2> Using `>=N`, `<=N`, `>N` and `<N` notation
|
||||
|
|
@ -91,7 +97,7 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wai
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-active]
|
||||
include-tagged::{doc-tests-file}[{api}-request-wait-active]
|
||||
--------------------------------------------------
|
||||
|
||||
<1> Wait for all shards to be active in the cluster
|
||||
|
|
@ -99,77 +105,42 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wai
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-local]
|
||||
include-tagged::{doc-tests-file}[{api}-request-local]
|
||||
--------------------------------------------------
|
||||
<1> Non-master node can be used for this request. Defaults to `false`
|
||||
|
||||
[[java-rest-high-cluster-health-sync]]
|
||||
==== Synchronous Execution
|
||||
include::../execution.asciidoc[]
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-cluster-health-async]]
|
||||
==== Asynchronous Execution
|
||||
|
||||
The asynchronous execution of a cluster health request requires both the
|
||||
`ClusterHealthRequest` instance and an `ActionListener` instance to be
|
||||
passed to the asynchronous method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The `ClusterHealthRequest` 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 `ClusterHealthResponse` looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-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
|
||||
|
||||
[[java-rest-high-cluster-health-response]]
|
||||
[id="{upid}-{api}-response"]
|
||||
==== Cluster Health Response
|
||||
|
||||
The returned `ClusterHealthResponse` contains the next information about the
|
||||
The returned +{response}+ contains the next information about the
|
||||
cluster:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-general]
|
||||
include-tagged::{doc-tests-file}[{api}-response-general]
|
||||
--------------------------------------------------
|
||||
<1> Name of the cluster
|
||||
<2> Cluster status (`green`, `yellow` or `red`)
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-request-status]
|
||||
include-tagged::{doc-tests-file}[{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
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-nodes]
|
||||
include-tagged::{doc-tests-file}[{api}-response-nodes]
|
||||
--------------------------------------------------
|
||||
<1> Number of nodes in the cluster
|
||||
<2> Number of data nodes in the cluster
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shards]
|
||||
include-tagged::{doc-tests-file}[{api}-response-shards]
|
||||
--------------------------------------------------
|
||||
<1> Number of active shards
|
||||
<2> Number of primary active shards
|
||||
|
|
@ -181,7 +152,7 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-sh
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-task]
|
||||
include-tagged::{doc-tests-file}[{api}-response-task]
|
||||
--------------------------------------------------
|
||||
<1> Maximum wait time of all tasks in the queue
|
||||
<2> Number of currently pending tasks
|
||||
|
|
@ -189,18 +160,18 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-ta
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-indices]
|
||||
include-tagged::{doc-tests-file}[{api}-response-indices]
|
||||
--------------------------------------------------
|
||||
<1> Detailed information about indices in the cluster
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-index]
|
||||
include-tagged::{doc-tests-file}[{api}-response-index]
|
||||
--------------------------------------------------
|
||||
<1> Detailed information about a specific index
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shard-details]
|
||||
include-tagged::{doc-tests-file}[{api}-response-shard-details]
|
||||
--------------------------------------------------
|
||||
<1> Detailed information about a specific shard
|
||||
|
|
@ -1,16 +1,22 @@
|
|||
[[java-rest-high-cluster-put-settings]]
|
||||
--
|
||||
:api: put-settings
|
||||
:request: ClusterUpdateSettingsRequest
|
||||
:response: ClusterUpdateSettingsResponse
|
||||
--
|
||||
|
||||
[id="{upid}-{api}"]
|
||||
=== Cluster Update Settings API
|
||||
|
||||
The Cluster Update Settings API allows to update cluster wide settings.
|
||||
|
||||
[[java-rest-high-cluster-put-settings-request]]
|
||||
[id="{upid}-{api}-request"]
|
||||
==== Cluster Update Settings Request
|
||||
|
||||
A `ClusterUpdateSettingsRequest`:
|
||||
A +{request}+:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request]
|
||||
include-tagged::{doc-tests-file}[{api}-request]
|
||||
--------------------------------------------------
|
||||
|
||||
==== Cluster Settings
|
||||
|
|
@ -18,7 +24,7 @@ At least one setting to be updated must be provided:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request-cluster-settings]
|
||||
include-tagged::{doc-tests-file}[{api}-request-cluster-settings]
|
||||
--------------------------------------------------
|
||||
<1> Sets the transient settings to be applied
|
||||
<2> Sets the persistent setting to be applied
|
||||
|
|
@ -28,26 +34,26 @@ The settings to be applied can be provided in different ways:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-create-settings]
|
||||
include-tagged::{doc-tests-file}[{api}-create-settings]
|
||||
--------------------------------------------------
|
||||
<1> Creates a transient setting as `Settings`
|
||||
<2> Creates a persistent setting as `Settings`
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-settings-builder]
|
||||
include-tagged::{doc-tests-file}[{api}-settings-builder]
|
||||
--------------------------------------------------
|
||||
<1> Settings provided as `Settings.Builder`
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-settings-source]
|
||||
include-tagged::{doc-tests-file}[{api}-settings-source]
|
||||
--------------------------------------------------
|
||||
<1> Settings provided as `String`
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-settings-map]
|
||||
include-tagged::{doc-tests-file}[{api}-settings-map]
|
||||
--------------------------------------------------
|
||||
<1> Settings provided as a `Map`
|
||||
|
||||
|
|
@ -56,7 +62,7 @@ The following arguments can optionally be provided:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request-timeout]
|
||||
include-tagged::{doc-tests-file}[{api}-request-timeout]
|
||||
--------------------------------------------------
|
||||
<1> Timeout to wait for the all the nodes to acknowledge the settings were applied
|
||||
as a `TimeValue`
|
||||
|
|
@ -65,58 +71,23 @@ as a `String`
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-request-masterTimeout]
|
||||
include-tagged::{doc-tests-file}[{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`
|
||||
|
||||
[[java-rest-high-cluster-put-settings-sync]]
|
||||
==== Synchronous Execution
|
||||
include::../execution.asciidoc[]
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-cluster-put-settings-async]]
|
||||
==== Asynchronous Execution
|
||||
|
||||
The asynchronous execution of a cluster update settings requires both the
|
||||
`ClusterUpdateSettingsRequest` instance and an `ActionListener` instance to be
|
||||
passed to the asynchronous method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The `ClusterUpdateSettingsRequest` 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 `ClusterUpdateSettingsResponse` looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-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
|
||||
|
||||
[[java-rest-high-cluster-put-settings-response]]
|
||||
[id="{upid}-{api}-response"]
|
||||
==== Cluster Update Settings Response
|
||||
|
||||
The returned `ClusterUpdateSettings` allows to retrieve information about the
|
||||
The returned +{response}+ allows to retrieve information about the
|
||||
executed operation as follows:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[put-settings-response]
|
||||
include-tagged::{doc-tests-file}[{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
|
||||
<3> Indicates which persistent settings have been applied
|
||||
|
|
|
|||
|
|
@ -0,0 +1,48 @@
|
|||
////
|
||||
This file is included by every high level rest client API documentation page
|
||||
so we don't have to copy and paste the same asciidoc over and over again. We
|
||||
*do* have to copy and paste the same Java tests over and over again. For now
|
||||
this is intentional because it forces us to *write* and execute the tests
|
||||
which, while a bit ceremonial, does force us to cover these calls in *some*
|
||||
test.
|
||||
////
|
||||
|
||||
[id="{upid}-{api}-sync"]
|
||||
==== Synchronous Execution
|
||||
|
||||
When executing a +{request}+ in the following manner, the client waits
|
||||
for the +{response}+ to be returned before continuing with code execution:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[id="{upid}-{api}-async"]
|
||||
==== 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:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{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.
|
||||
|
||||
A typical listener for +{response}+ looks like:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests-file}[{api}-execute-listener]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed.
|
||||
<2> Called when the whole +{request}+ fails.
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
[[java-rest-high]]
|
||||
:mainid: java-rest-high
|
||||
|
||||
[id="{mainid}"]
|
||||
= Java High Level REST Client
|
||||
|
||||
[partintro]
|
||||
|
|
@ -31,3 +33,4 @@ include::migration.asciidoc[]
|
|||
include::../license.asciidoc[]
|
||||
|
||||
:doc-tests!:
|
||||
:mainid!:
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ The query builders are used to create the query to execute within a search reque
|
|||
is a query builder for every type of query supported by the Query DSL. Each query builder
|
||||
implements the `QueryBuilder` interface and allows to set the specific options for a given
|
||||
type of query. Once created, the `QueryBuilder` object can be set as the query parameter of
|
||||
`SearchSourceBuilder`. The <<java-rest-high-document-search-request-building-queries, Search Request>>
|
||||
`SearchSourceBuilder`. The <<java-rest-high-search-request-building-queries, Search Request>>
|
||||
page shows an example of how to build a full search request using `SearchSourceBuilder` and
|
||||
`QueryBuilder` objects. The <<java-rest-high-query-builders, Building Search Queries>> page
|
||||
gives a list of all available search queries with their corresponding `QueryBuilder` objects
|
||||
|
|
@ -24,7 +24,7 @@ aggregation (or pipeline aggregation) supported by Elasticsearch. All builders e
|
|||
`AggregationBuilder` class (or `PipelineAggregationBuilder`class). Once created, `AggregationBuilder`
|
||||
objects can be set as the aggregation parameter of `SearchSourceBuilder`. There is a example
|
||||
of how `AggregationBuilder` objects are used with `SearchSourceBuilder` objects to define the aggregations
|
||||
to compute with a search query in <<java-rest-high-document-search-request-building-aggs, Search Request>> page.
|
||||
to compute with a search query in <<java-rest-high-search-request-building-aggs, Search Request>> page.
|
||||
The <<java-rest-high-aggregation-builders, Building Aggregations>> page gives a list of all available
|
||||
aggregations with their corresponding `AggregationBuilder` objects and `AggregationBuilders` helper methods.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,16 @@
|
|||
[[java-rest-high-search]]
|
||||
--
|
||||
:api: search
|
||||
:request: SearchRequest
|
||||
:response: SearchResponse
|
||||
--
|
||||
|
||||
[id="{upid}-{api}"]
|
||||
=== Search API
|
||||
|
||||
[[java-rest-high-document-search-request]]
|
||||
[id="{upid}-{api}-request"]
|
||||
==== Search Request
|
||||
|
||||
The `SearchRequest` is used for any operation that has to do with searching
|
||||
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.
|
||||
|
||||
|
|
@ -12,7 +18,7 @@ In its most basic form, we can add a query to the request:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-basic]
|
||||
include-tagged::{doc-tests-file}[{api}-request-basic]
|
||||
--------------------------------------------------
|
||||
|
||||
<1> Creates the `SeachRequest`. Without arguments this runs against all indices.
|
||||
|
|
@ -20,14 +26,14 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-basic]
|
|||
<3> Add a `match_all` query to the `SearchSourceBuilder`.
|
||||
<4> Add the `SearchSourceBuilder` to the `SeachRequest`.
|
||||
|
||||
[[java-rest-high-search-request-optional]]
|
||||
[id="{upid}-{api}-request-optional"]
|
||||
===== Optional arguments
|
||||
|
||||
Let's first look at some of the optional arguments of a `SearchRequest`:
|
||||
Let's first look at some of the optional arguments of a +{request}+:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-indices-types]
|
||||
include-tagged::{doc-tests-file}[{api}-request-indices-types]
|
||||
--------------------------------------------------
|
||||
<1> Restricts the request to an index
|
||||
<2> Limits the request to a type
|
||||
|
|
@ -36,20 +42,20 @@ There are a couple of other interesting optional parameters:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-routing]
|
||||
include-tagged::{doc-tests-file}[{api}-request-routing]
|
||||
--------------------------------------------------
|
||||
<1> Set a routing parameter
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-indicesOptions]
|
||||
include-tagged::{doc-tests-file}[{api}-request-indicesOptions]
|
||||
--------------------------------------------------
|
||||
<1> Setting `IndicesOptions` controls how unavailable indices are resolved and
|
||||
how wildcard expressions are expanded
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-preference]
|
||||
include-tagged::{doc-tests-file}[{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.
|
||||
|
|
@ -65,7 +71,7 @@ Here are a few examples of some common options:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-basics]
|
||||
include-tagged::{doc-tests-file}[{api}-source-basics]
|
||||
--------------------------------------------------
|
||||
<1> Create a `SearchSourceBuilder` with default options.
|
||||
<2> Set the query. Can be any type of `QueryBuilder`
|
||||
|
|
@ -77,14 +83,14 @@ Defaults to 10.
|
|||
take.
|
||||
|
||||
After this, the `SearchSourceBuilder` only needs to be added to the
|
||||
`SearchRequest`:
|
||||
+{request}+:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-setter]
|
||||
include-tagged::{doc-tests-file}[{api}-source-setter]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-document-search-request-building-queries]]
|
||||
[id="{upid}-{api}-request-building-queries"]
|
||||
===== Building queries
|
||||
|
||||
Search queries are created using `QueryBuilder` objects. A `QueryBuilder` exists
|
||||
|
|
@ -94,7 +100,7 @@ A `QueryBuilder` can be created using its constructor:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builder-ctor]
|
||||
include-tagged::{doc-tests-file}[{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".
|
||||
|
|
@ -104,7 +110,7 @@ of the search query it creates:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builder-options]
|
||||
include-tagged::{doc-tests-file}[{api}-query-builder-options]
|
||||
--------------------------------------------------
|
||||
<1> Enable fuzzy matching on the match query
|
||||
<2> Set the prefix length option on the match query
|
||||
|
|
@ -117,7 +123,7 @@ This class provides helper methods that can be used to create `QueryBuilder` obj
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builders]
|
||||
include-tagged::{doc-tests-file}[{api}-query-builders]
|
||||
--------------------------------------------------
|
||||
|
||||
Whatever the method used to create it, the `QueryBuilder` object must be added
|
||||
|
|
@ -125,10 +131,10 @@ to the `SearchSourceBuilder` as follows:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-setter]
|
||||
include-tagged::{doc-tests-file}[{api}-query-setter]
|
||||
--------------------------------------------------
|
||||
|
||||
The <<java-rest-high-query-builders, Building Queries>> page gives a list of all available search queries with
|
||||
The <<{upid}-query-builders, Building Queries>> page gives a list of all available search queries with
|
||||
their corresponding `QueryBuilder` objects and `QueryBuilders` helper methods.
|
||||
|
||||
|
||||
|
|
@ -138,7 +144,7 @@ The `SearchSourceBuilder` allows to add one or more `SortBuilder` instances. The
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-sorting]
|
||||
include-tagged::{doc-tests-file}[{api}-source-sorting]
|
||||
--------------------------------------------------
|
||||
<1> Sort descending by `_score` (the default)
|
||||
<2> Also sort ascending by `_id` field
|
||||
|
|
@ -149,17 +155,17 @@ By default, search requests return the contents of the document `_source` but li
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-filtering-off]
|
||||
include-tagged::{doc-tests-file}[{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:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-filtering-includes]
|
||||
include-tagged::{doc-tests-file}[{api}-source-filtering-includes]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-request-highlighting]]
|
||||
[id="{upid}-{api}-request-highlighting"]
|
||||
===== Requesting Highlighting
|
||||
|
||||
Highlighting search results can be achieved by setting a `HighlightBuilder` on the
|
||||
|
|
@ -168,7 +174,7 @@ fields by adding one or more `HighlightBuilder.Field` instances to a `HighlightB
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-highlighting]
|
||||
include-tagged::{doc-tests-file}[{api}-request-highlighting]
|
||||
--------------------------------------------------
|
||||
<1> Creates a new `HighlightBuilder`
|
||||
<2> Create a field highlighter for the `title` field
|
||||
|
|
@ -179,9 +185,9 @@ There are many options which are explained in detail in the Rest API documentati
|
|||
API parameters (e.g. `pre_tags`) are usually changed by
|
||||
setters with a similar name (e.g. `#preTags(String ...)`).
|
||||
|
||||
Highlighted text fragments can <<java-rest-high-retrieve-highlighting,later be retrieved>> from the `SearchResponse`.
|
||||
Highlighted text fragments can <<{upid}-{api}-response-highlighting,later be retrieved>> from the +{response}+.
|
||||
|
||||
[[java-rest-high-document-search-request-building-aggs]]
|
||||
[id="{upid}-{api}-request-building-aggs"]
|
||||
===== Requesting Aggregations
|
||||
|
||||
Aggregations can be added to the search by first creating the appropriate
|
||||
|
|
@ -191,13 +197,13 @@ sub-aggregation on the average age of employees in the company:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations]
|
||||
include-tagged::{doc-tests-file}[{api}-request-aggregations]
|
||||
--------------------------------------------------
|
||||
|
||||
The <<java-rest-high-aggregation-builders, Building Aggregations>> page gives a list of all available aggregations with
|
||||
The <<{upid}-aggregation-builders, 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 <<java-rest-high-retrieve-aggs,access aggregations>> in the `SearchResponse`.
|
||||
We will later see how to <<{upid}-{api}-response-aggs,access aggregations>> in the +{response}+.
|
||||
|
||||
===== Requesting Suggestions
|
||||
|
||||
|
|
@ -207,14 +213,14 @@ need to be added to the top level `SuggestBuilder`, which itself can be set on t
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-suggestion]
|
||||
include-tagged::{doc-tests-file}[{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 <<java-rest-high-retrieve-suggestions,retrieve suggestions>> from the
|
||||
`SearchResponse`.
|
||||
We will later see how to <<{upid}-{api}-response-suggestions,retrieve suggestions>> from the
|
||||
+{response}+.
|
||||
|
||||
===== Profiling Queries and Aggregations
|
||||
|
||||
|
|
@ -223,56 +229,18 @@ a specific search request. in order to use it, the profile flag must be set to t
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling]
|
||||
include-tagged::{doc-tests-file}[{api}-request-profiling]
|
||||
--------------------------------------------------
|
||||
|
||||
Once the `SearchRequest` is executed the corresponding `SearchResponse` will
|
||||
<<java-rest-high-retrieve-profile-results,contain the profiling results>>.
|
||||
Once the +{request}+ is executed the corresponding +{response}+ will
|
||||
<<{upid}-{api}-response-profile,contain the profiling results>>.
|
||||
|
||||
[[java-rest-high-document-search-sync]]
|
||||
==== Synchronous Execution
|
||||
include::../execution.asciidoc[]
|
||||
|
||||
When executing a `SearchRequest` in the following manner, the client waits
|
||||
for the `SearchResponse` to be returned before continuing with code execution:
|
||||
[id="{upid}-{api}-response"]
|
||||
==== {response}
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-document-search-async]]
|
||||
==== Asynchronous Execution
|
||||
|
||||
Executing a `SearchRequest` 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 listeners to the
|
||||
asynchronous search method:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute-async]
|
||||
--------------------------------------------------
|
||||
<1> The `SearchRequest` 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:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-execute-listener]
|
||||
--------------------------------------------------
|
||||
<1> Called when the execution is successfully completed.
|
||||
<2> Called when the whole `SearchRequest` fails.
|
||||
|
||||
[[java-rest-high-search-response]]
|
||||
==== SearchResponse
|
||||
|
||||
The `SearchResponse` that is returned by executing the search provides details
|
||||
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
|
||||
|
|
@ -280,7 +248,7 @@ out:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-1]
|
||||
include-tagged::{doc-tests-file}[{api}-response-1]
|
||||
--------------------------------------------------
|
||||
|
||||
Second, the response also provides information about the execution on the
|
||||
|
|
@ -291,10 +259,10 @@ failures can also be handled by iterating over an array off
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-response-2]
|
||||
include-tagged::{doc-tests-file}[{api}-response-2]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-retrieve-searchHits]]
|
||||
[id="{upid}-{api}-response-search-hits"]
|
||||
===== Retrieving SearchHits
|
||||
|
||||
To get access to the returned documents, we need to first get the `SearchHits`
|
||||
|
|
@ -302,7 +270,7 @@ contained in the response:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-get]
|
||||
include-tagged::{doc-tests-file}[{api}-hits-get]
|
||||
--------------------------------------------------
|
||||
|
||||
The `SearchHits` provides global information about all hits, like total number
|
||||
|
|
@ -310,7 +278,7 @@ of hits or the maximum score:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-info]
|
||||
include-tagged::{doc-tests-file}[{api}-hits-info]
|
||||
--------------------------------------------------
|
||||
|
||||
Nested inside the `SearchHits` are the individual search results that can
|
||||
|
|
@ -319,7 +287,7 @@ be iterated over:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit]
|
||||
include-tagged::{doc-tests-file}[{api}-hits-singleHit]
|
||||
--------------------------------------------------
|
||||
|
||||
The `SearchHit` provides access to basic information like index, type, docId and
|
||||
|
|
@ -327,7 +295,7 @@ score of each search hit:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit-properties]
|
||||
include-tagged::{doc-tests-file}[{api}-hits-singleHit-properties]
|
||||
--------------------------------------------------
|
||||
|
||||
Furthermore, it lets you get back the document source, either as a simple
|
||||
|
|
@ -338,34 +306,34 @@ cases need to be cast accordingly:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-hits-singleHit-source]
|
||||
include-tagged::{doc-tests-file}[{api}-hits-singleHit-source]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-retrieve-highlighting]]
|
||||
[id="{upid}-{api}-response-highlighting"]
|
||||
===== Retrieving Highlighting
|
||||
|
||||
If <<java-rest-high-request-highlighting,requested>>, highlighted text fragments can be retrieved from each `SearchHit` in the result. The hit object offers
|
||||
If <<{upid}-{api}-request-highlighting,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:
|
||||
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-highlighting-get]
|
||||
include-tagged::{doc-tests-file}[{api}-request-highlighting-get]
|
||||
--------------------------------------------------
|
||||
<1> Get the highlighting for the `title` field
|
||||
<2> Get one or many fragments containing the highlighted field content
|
||||
|
||||
[[java-rest-high-retrieve-aggs]]
|
||||
[id="{upid}-{api}-response-aggs"]
|
||||
===== Retrieving Aggregations
|
||||
|
||||
Aggregations can be retrieved from the `SearchResponse` by first getting the
|
||||
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.
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-get]
|
||||
include-tagged::{doc-tests-file}[{api}-request-aggregations-get]
|
||||
--------------------------------------------------
|
||||
<1> Get the `by_company` terms aggregation
|
||||
<2> Get the buckets that is keyed with `Elastic`
|
||||
|
|
@ -377,7 +345,7 @@ otherwise a `ClassCastException` will be thrown:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-get-wrongCast]
|
||||
include-tagged::{doc-tests-file}[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
|
||||
|
|
@ -388,14 +356,14 @@ needs to happen explicitly:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-asMap]
|
||||
include-tagged::{doc-tests-file}[{api}-request-aggregations-asMap]
|
||||
--------------------------------------------------
|
||||
|
||||
There are also getters that return all top level aggregations as a list:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-asList]
|
||||
include-tagged::{doc-tests-file}[{api}-request-aggregations-asList]
|
||||
--------------------------------------------------
|
||||
|
||||
And last but not least you can iterate over all aggregations and then e.g.
|
||||
|
|
@ -403,17 +371,17 @@ decide how to further process them based on their type:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-iterator]
|
||||
include-tagged::{doc-tests-file}[{api}-request-aggregations-iterator]
|
||||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-retrieve-suggestions]]
|
||||
[id="{upid}-{api}-response-suggestions"]
|
||||
===== Retrieving Suggestions
|
||||
|
||||
To get back the suggestions from a `SearchResponse`, use the `Suggest` object as an entry point and then retrieve the nested suggestion objects:
|
||||
To get back the suggestions from a +{response}+, use the `Suggest` object as an entry point and then retrieve the nested suggestion objects:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-suggestion-get]
|
||||
include-tagged::{doc-tests-file}[{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
|
||||
|
|
@ -421,21 +389,21 @@ type of Suggestion class (here `TermSuggestion`), otherwise a `ClassCastExceptio
|
|||
<3> Iterate over the suggestion entries
|
||||
<4> Iterate over the options in one entry
|
||||
|
||||
[[java-rest-high-retrieve-profile-results]]
|
||||
[id="{upid}-{api}-response-profile"]
|
||||
===== Retrieving Profiling Results
|
||||
|
||||
Profiling results are retrieved from a `SearchResponse` using the `getProfileResults()` method. This
|
||||
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
|
||||
`SearchRequest` execution. `ProfileShardResult` are stored in the `Map` using a key that uniquely
|
||||
+{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:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-get]
|
||||
include-tagged::{doc-tests-file}[{api}-request-profiling-get]
|
||||
--------------------------------------------------
|
||||
<1> Retrieve the `Map` of `ProfileShardResult` from the `SearchResponse`
|
||||
<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
|
||||
|
|
@ -446,7 +414,7 @@ executed against the underlying Lucene index:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-queries]
|
||||
include-tagged::{doc-tests-file}[{api}-request-profiling-queries]
|
||||
--------------------------------------------------
|
||||
<1> Retrieve the list of `QueryProfileShardResult`
|
||||
<2> Iterate over each `QueryProfileShardResult`
|
||||
|
|
@ -456,7 +424,7 @@ Each `QueryProfileShardResult` gives access to the detailed query tree execution
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-queries-results]
|
||||
include-tagged::{doc-tests-file}[{api}-request-profiling-queries-results]
|
||||
--------------------------------------------------
|
||||
<1> Iterate over the profile results
|
||||
<2> Retrieve the name of the Lucene query
|
||||
|
|
@ -470,7 +438,7 @@ The `QueryProfileShardResult` also gives access to the profiling information for
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-queries-collectors]
|
||||
include-tagged::{doc-tests-file}[{api}-request-profiling-queries-collectors]
|
||||
--------------------------------------------------
|
||||
<1> Retrieve the profiling result of the Lucene collector
|
||||
<2> Retrieve the name of the Lucene collector
|
||||
|
|
@ -485,7 +453,7 @@ to the detailed aggregations tree execution:
|
|||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-profiling-aggs]
|
||||
include-tagged::{doc-tests-file}[{api}-request-profiling-aggs]
|
||||
--------------------------------------------------
|
||||
<1> Retrieve the `AggregationProfileShardResult`
|
||||
<2> Iterate over the aggregation profile results
|
||||
|
|
|
|||
|
|
@ -46,6 +46,8 @@ The Java High Level REST Client supports the following Search APIs:
|
|||
* <<java-rest-high-rank-eval>>
|
||||
* <<java-rest-high-explain>>
|
||||
|
||||
:upid: {mainid}
|
||||
:doc-tests-file: {doc-tests}/SearchDocumentationIT.java
|
||||
include::search/search.asciidoc[]
|
||||
include::search/scroll.asciidoc[]
|
||||
include::search/multi-search.asciidoc[]
|
||||
|
|
@ -137,6 +139,8 @@ The Java High Level REST Client supports the following Cluster APIs:
|
|||
* <<java-rest-high-cluster-get-settings>>
|
||||
* <<java-rest-high-cluster-health>>
|
||||
|
||||
:upid: {mainid}-cluster
|
||||
:doc-tests-file: {doc-tests}/ClusterClientDocumentationIT.java
|
||||
include::cluster/put_settings.asciidoc[]
|
||||
include::cluster/get_settings.asciidoc[]
|
||||
include::cluster/health.asciidoc[]
|
||||
|
|
@ -309,3 +313,15 @@ The Java High Level REST Client supports the following Graph APIs:
|
|||
* <<java-rest-high-x-pack-graph-explore>>
|
||||
|
||||
include::graph/explore.asciidoc[]
|
||||
|
||||
////
|
||||
Clear attributes that we use to document that APIs included above so they
|
||||
don't leak into the rest of the documentation.
|
||||
////
|
||||
--
|
||||
:api!:
|
||||
:request!:
|
||||
:response!:
|
||||
:doc-tests-file!:
|
||||
:upid!:
|
||||
--
|
||||
|
|
|
|||
Loading…
Reference in New Issue