From df2053bc74482f7dc438fcc72f0d9ddc3a300bd1 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 6 May 2020 16:18:41 -0400 Subject: [PATCH 1/2] [DOCS] Relocate search API's request body parameters Changes: * Moves the document request body parameters for the search API from the Request body search page to the Search API reference page. * Relocates a search request body example from the Request body search page to the Search API reference page. * Adds a note to any duplicated query and request body parameters. --- docs/reference/search/request-body.asciidoc | 99 +------------- docs/reference/search/search.asciidoc | 140 +++++++++++++++++++- 2 files changed, 137 insertions(+), 102 deletions(-) diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc index 999ee05cb9dca..408eda2b6f3bd 100644 --- a/docs/reference/search/request-body.asciidoc +++ b/docs/reference/search/request-body.asciidoc @@ -18,7 +18,6 @@ GET /twitter/_search [[search-request-body-api-request]] ==== {api-request-title} - `GET //_search { "query": {} @@ -37,106 +36,10 @@ The search request can be executed with a search DSL, which includes the include::{docdir}/rest-api/common-parms.asciidoc[tag=index] - [[search-request-body-api-request-body]] ==== {api-request-body-title} -`allow_partial_search_results`:: - (Optional, boolean) Set to `false` to fail the request if only partial results - are available. Defaults to `true`, which returns partial results in the event - of timeouts or partial failures You can override the default behavior for all - requests by setting `search.default_allow_partial_results` to `false` in the - cluster settings. - -`batched_reduce_size`:: - (Optional, integer) The number of shard results that should be reduced at once - on the coordinating node. This value should be used as a protection mechanism - to reduce the memory overhead per search request if the potential number of - shards in the request can be large. - -[[ccs-minimize-roundtrips]] -`ccs_minimize_roundtrips`:: - (Optional, boolean) If `true`, the network round-trips between the - coordinating node and the remote clusters ewill be minimized when executing - {ccs} requests. See <>. Defaults to `true`. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=from] - -`request_cache`:: - (Optional, boolean) If `true`, the caching of search results is enabled for - requests where `size` is `0`. See <>. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type] - -`size`:: - (Optional, integer) The number of hits to return. Defaults to `10`. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=search_timeout] - - -Out of the above, the `search_type`, `request_cache` and the -`allow_partial_search_results` settings must be passed as query-string -parameters. The rest of the search request should be passed within the body -itself. The body content can also be passed as a REST parameter named `source`. - -Both HTTP GET and HTTP POST can be used to execute search with body. Since not -all clients support GET with body, POST is allowed as well. - - -[[search-request-body-api-example]] -==== {api-examples-title} - -[source,console] --------------------------------------------------- -GET /twitter/_search -{ - "query" : { - "term" : { "user" : "kimchy" } - } -} --------------------------------------------------- -// TEST[setup:twitter] - - -The API returns the following response: - -[source,console-result] --------------------------------------------------- -{ - "took": 1, - "timed_out": false, - "_shards":{ - "total" : 1, - "successful" : 1, - "skipped" : 0, - "failed" : 0 - }, - "hits":{ - "total" : { - "value": 1, - "relation": "eq" - }, - "max_score": 1.3862942, - "hits" : [ - { - "_index" : "twitter", - "_id" : "0", - "_score": 1.3862942, - "_source" : { - "user" : "kimchy", - "message": "trying out Elasticsearch", - "date" : "2009-11-15T14:12:12", - "likes" : 0 - } - } - ] - } -} --------------------------------------------------- -// TESTRESPONSE[s/"took": 1/"took": $body.took/] - +See the search API's <>. ==== Fast check for any matching docs diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 5c81b1cf228ee..8189450198bde 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -58,6 +58,7 @@ To override the default for this field, set the to reduce the memory overhead per search request if the potential number of shards in the request can be large. Defaults to `512`. +[[ccs-minimize-roundtrips]] `ccs_minimize_roundtrips`:: (Optional, boolean) Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution. Defaults to `true`. @@ -75,6 +76,14 @@ Defaults to `open`. computation as part of a hit. Defaults to `false`. include::{docdir}/rest-api/common-parms.asciidoc[tag=from] ++ +-- +[IMPORTANT] +==== +You can also specify this value using the `from` request body parameter. If +both parameters are specified, only the query parameter is used. +==== +-- `ignore_throttled`:: (Optional, boolean) If `true`, concrete, expanded or aliased indices will be @@ -139,7 +148,15 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type] last modification of each hit. `size`:: - (Optional, integer) Defines the number of hits to return. Defaults to `10`. +(Optional, integer) Defines the number of hits to return. Defaults to `10`. ++ +-- +[IMPORTANT] +==== +You can also specify this value using the `size` request body parameter. If +both parameters are specified, only the query parameter is used. +==== +-- `sort`:: (Optional, string) A comma-separated list of : pairs. @@ -171,12 +188,29 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes] include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after] + +-- Defaults to `0`, which does not terminate query execution early. +[IMPORTANT] +==== +You can also specify this value using the `terminate_after` request body +parameter. If both parameters are specified, only the query parameter is used. +==== +-- + `timeout`:: - (Optional, <>) Specifies the period of time to wait - for a response. If no response is received before the timeout expires, the - request fails and returns an error. Defaults to no timeout. ++ +-- +(Optional, <>) Specifies the period of time to wait +for a response. If no response is received before the timeout expires, the +request fails and returns an error. Defaults to no timeout. + +[IMPORTANT] +==== +You can also specify this value using the `timeout` request body +parameter. If both parameters are specified, only the query parameter is used. +==== +-- `track_scores`:: (Optional, boolean) If `true`, calculate and return document scores, even if @@ -201,11 +235,58 @@ include the total number of hits matching the query. [[search-search-api-request-body]] ==== {api-request-body-title} +include::{docdir}/rest-api/common-parms.asciidoc[tag=from] ++ +-- +[IMPORTANT] +==== +You can also specify this value using the `from` query parameter. If both +parameters are specified, only the query parameter is used. +==== +-- + [[search-api-request-body-query]] `query`:: (Optional, <>) Defines the search definition using the <>. +`size`:: +(Optional, integer) The number of hits to return. Defaults to `10`. ++ +-- +[IMPORTANT] +==== +You can also specify this value using the `size` query parameter. If both +parameters are specified, only the query parameter is used. +==== +-- + +include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after] ++ +-- +Defaults to `0`, which does not terminate query execution early. + +[IMPORTANT] +==== +You can also specify this value using the `terminate_after` query parameter. If +both parameters are specified, only the query parameter is used. +==== +-- + +`timeout`:: ++ +-- +(Optional, <>) Specifies the period of time to wait +for a response. If no response is received before the timeout expires, the +request fails and returns an error. Defaults to no timeout. + +[IMPORTANT] +==== +You can also specify this value using the `timeout` query parameter. If both +parameters are specified, only the query parameter is used. +==== +-- + [role="child_attributes"] [[search-api-response-body]] ==== {api-response-body-title} @@ -422,3 +503,54 @@ GET /_all/_search?q=user:kimchy GET /*/_search?q=user:kimchy ---- // TEST[continued] + +[[search-request-body-api-example]] +===== Search an index using the `query` request body parameter + +[source,console] +-------------------------------------------------- +GET /twitter/_search +{ + "query" : { + "term" : { "user" : "kimchy" } + } +} +-------------------------------------------------- +// TEST[setup:twitter] + +The API returns the following response: + +[source,console-result] +-------------------------------------------------- +{ + "took": 1, + "timed_out": false, + "_shards":{ + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits":{ + "total" : { + "value": 1, + "relation": "eq" + }, + "max_score": 1.3862942, + "hits" : [ + { + "_index" : "twitter", + "_id" : "0", + "_score": 1.3862942, + "_source" : { + "user" : "kimchy", + "message": "trying out Elasticsearch", + "date" : "2009-11-15T14:12:12", + "likes" : 0 + } + } + ] + } +} +-------------------------------------------------- +// TESTRESPONSE[s/"took": 1/"took": $body.took/] From 013cca62d65d7d585e9e91b1909a32beb13a53a6 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 7 May 2020 08:38:20 -0400 Subject: [PATCH 2/2] Update css_minimize_roundtrips and request_cache defs --- docs/reference/search/search.asciidoc | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 8189450198bde..ebef1017c52e4 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -60,8 +60,9 @@ To override the default for this field, set the [[ccs-minimize-roundtrips]] `ccs_minimize_roundtrips`:: - (Optional, boolean) Indicates whether network round-trips should be minimized - as part of cross-cluster search requests execution. Defaults to `true`. +(Optional, boolean) If `true`, network round-trips between the +coordinating node and the remote clusters are minimized when executing +{ccs} (CCS) requests. See <>. Defaults to `true`. `docvalue_fields`:: (Optional, string) A comma-separated list of fields to return as the docvalue @@ -130,8 +131,9 @@ matching the `query` request body parameter are not returned. -- `request_cache`:: - (Optional, boolean) If `true`, request cache will be used for this request. - Defaults to index level settings. +(Optional, boolean) If `true`, the caching of search results is enabled for +requests where `size` is `0`. See <>. Defaults to index +level settings. `rest_total_hits_as_int`:: (Optional, boolean) Indicates whether hits.total should be rendered as an