From 47bcb56a89d6a00a5596dfeba46428a7d51c1c41 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Fri, 28 Sep 2018 14:48:11 -0400 Subject: [PATCH] Docs: Cut down on high level rest client copy-and-paste-ness (#34125) * Anchors * includes * get settings * more * More --- .../ClusterClientDocumentationIT.java | 18 +- .../high-level/cluster/get_settings.asciidoc | 65 ++----- .../high-level/cluster/health.asciidoc | 97 ++++------ .../high-level/cluster/put_settings.asciidoc | 73 +++---- docs/java-rest/high-level/execution.asciidoc | 48 +++++ docs/java-rest/high-level/index.asciidoc | 5 +- .../high-level/java-builders.asciidoc | 4 +- .../high-level/search/search.asciidoc | 182 ++++++++---------- .../high-level/supported-apis.asciidoc | 16 ++ 9 files changed, 221 insertions(+), 287 deletions(-) create mode 100644 docs/java-rest/high-level/execution.asciidoc diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java index 170bd435856..a9576440438 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java @@ -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 { diff --git a/docs/java-rest/high-level/cluster/get_settings.asciidoc b/docs/java-rest/high-level/cluster/get_settings.asciidoc index 999bd92d791..407d33f8fc8 100644 --- a/docs/java-rest/high-level/cluster/get_settings.asciidoc +++ b/docs/java-rest/high-level/cluster/get_settings.asciidoc @@ -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`. + diff --git a/docs/java-rest/high-level/cluster/health.asciidoc b/docs/java-rest/high-level/cluster/health.asciidoc index 192880849e2..06163fca52d 100644 --- a/docs/java-rest/high-level/cluster/health.asciidoc +++ b/docs/java-rest/high-level/cluster/health.asciidoc @@ -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 ` 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 \ No newline at end of file diff --git a/docs/java-rest/high-level/cluster/put_settings.asciidoc b/docs/java-rest/high-level/cluster/put_settings.asciidoc index dc9b1679d47..bc9abc62456 100644 --- a/docs/java-rest/high-level/cluster/put_settings.asciidoc +++ b/docs/java-rest/high-level/cluster/put_settings.asciidoc @@ -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 \ No newline at end of file +<3> Indicates which persistent settings have been applied diff --git a/docs/java-rest/high-level/execution.asciidoc b/docs/java-rest/high-level/execution.asciidoc new file mode 100644 index 00000000000..fc4f4c0ec60 --- /dev/null +++ b/docs/java-rest/high-level/execution.asciidoc @@ -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. \ No newline at end of file diff --git a/docs/java-rest/high-level/index.asciidoc b/docs/java-rest/high-level/index.asciidoc index bc4c2dd89bb..a15967e9ad7 100644 --- a/docs/java-rest/high-level/index.asciidoc +++ b/docs/java-rest/high-level/index.asciidoc @@ -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!: diff --git a/docs/java-rest/high-level/java-builders.asciidoc b/docs/java-rest/high-level/java-builders.asciidoc index 48db23c30cb..89f2de5fa9f 100644 --- a/docs/java-rest/high-level/java-builders.asciidoc +++ b/docs/java-rest/high-level/java-builders.asciidoc @@ -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 <> +`SearchSourceBuilder`. The <> page shows an example of how to build a full search request using `SearchSourceBuilder` and `QueryBuilder` objects. The <> 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 <> page. +to compute with a search query in <> page. The <> page gives a list of all available aggregations with their corresponding `AggregationBuilder` objects and `AggregationBuilders` helper methods. diff --git a/docs/java-rest/high-level/search/search.asciidoc b/docs/java-rest/high-level/search/search.asciidoc index 3e9472ff2cb..e2bcfda79e6 100644 --- a/docs/java-rest/high-level/search/search.asciidoc +++ b/docs/java-rest/high-level/search/search.asciidoc @@ -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 <> 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 <> 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 <> 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 <> 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 <> 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 -<>. +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 <>, 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 diff --git a/docs/java-rest/high-level/supported-apis.asciidoc b/docs/java-rest/high-level/supported-apis.asciidoc index 90f44852c43..8e3e8f5812b 100644 --- a/docs/java-rest/high-level/supported-apis.asciidoc +++ b/docs/java-rest/high-level/supported-apis.asciidoc @@ -46,6 +46,8 @@ The Java High Level REST Client supports the following Search APIs: * <> * <> +: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: * <> * <> +: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: * <> 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!: +--