From 5c5af7756594842dd0f2adf37fdd94e434ce3ae3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Wed, 4 Sep 2019 10:52:17 +0200 Subject: [PATCH] [DOCS] Reformats request body search API (#46254) * [DOCS] Reformats request body search API. Co-Authored-By: James Rodewig --- docs/reference/search/request-body.asciidoc | 170 +++++++++++--------- 1 file changed, 92 insertions(+), 78 deletions(-) diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc index cd9ee8592c4..b84d695e9f1 100644 --- a/docs/reference/search/request-body.asciidoc +++ b/docs/reference/search/request-body.asciidoc @@ -1,9 +1,7 @@ [[search-request-body]] === Request Body Search -The search request can be executed with a search DSL, which includes the -<>, within its body. Here is an -example: +Specifies search criteria as request body parameters. [source,js] -------------------------------------------------- @@ -17,7 +15,94 @@ GET /twitter/_search // CONSOLE // TEST[setup:twitter] -And here is a sample response: + +[[search-request-body-api-request]] +==== {api-request-title} + + +`GET //_search +{ + "query": {} +}` + + +[[search-request-body-api-desc]] +==== {api-description-title} + +The search request can be executed with a search DSL, which includes the +<>, within its body. + + +[[search-request-body-api-path-params]] +==== {api-path-parms-title} + +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 <> for more. 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=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,js] +-------------------------------------------------- +GET /twitter/_search +{ + "query" : { + "term" : { "user" : "kimchy" } + } +} +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + + +The API returns the following response: [source,js] -------------------------------------------------- @@ -55,81 +140,7 @@ And here is a sample response: -------------------------------------------------- // TESTRESPONSE[s/"took": 1/"took": $body.took/] -[float] -==== Parameters -[horizontal] -`timeout`:: - - A search timeout, bounding the search request to be executed within the - specified time value and bail with the hits accumulated up to that point - when expired. Search requests are canceled after the timeout is reached using - the <> mechanism. - Defaults to no timeout. See <>. - -`from`:: - - To retrieve hits from a certain offset. Defaults to `0`. - -`size`:: - - The number of hits to return. Defaults to `10`. If you do not care about - getting some hits back but only about the number of matches and/or - aggregations, setting the value to `0` will help performance. - -`search_type`:: - - The type of the search operation to perform. Can be - `dfs_query_then_fetch` or `query_then_fetch`. - Defaults to `query_then_fetch`. - See <> for more. - -`request_cache`:: - - Set to `true` or `false` to enable or disable the caching - of search results for requests where `size` is 0, ie - aggregations and suggestions (no top hits returned). - See <>. - -`allow_partial_search_results`:: - - Set to `false` to return an overall failure if the request would produce partial - results. Defaults to true, which will allow partial results in the case of timeouts - or partial failures. This default can be controlled using the cluster-level setting - `search.default_allow_partial_results`. - -`terminate_after`:: - - The maximum number of documents to collect for each shard, - upon reaching which the query execution will terminate early. If set, the - response will have a boolean field `terminated_early` to indicate whether - the query execution has actually terminated_early. Defaults to no - terminate_after. - -`batched_reduce_size`:: - - 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`:: - - Defaults to `true`. Set to `false` to disable minimizing network round-trips - between the coordinating node and the remote clusters when executing - {ccs} requests. See <> for more. - - -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. - -[float] ==== Fast check for any matching docs NOTE: `terminate_after` is always applied **after** the `post_filter` and stops @@ -151,6 +162,7 @@ GET /_search?q=message:number&size=0&terminate_after=1 // CONSOLE // TEST[setup:twitter] + The response will not contain any hits as the `size` was set to `0`. The `hits.total` will be either equal to `0`, indicating that there were no matching documents, or greater than `0` meaning that there were at least @@ -182,6 +194,7 @@ be set to `true` in the response. -------------------------------------------------- // TESTRESPONSE[s/"took": 3/"took": $body.took/] + The `took` time in the response contains the milliseconds that this request took for processing, beginning quickly after the node received the query, up until all search related work is done and before the above JSON is returned @@ -189,6 +202,7 @@ to the client. This means it includes the time spent waiting in thread pools, executing a distributed search across the whole cluster and gathering all the results. + include::request/docvalue-fields.asciidoc[] include::request/explain.asciidoc[]