diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc index a8b0885d1ac9b..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,107 +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", - "_type" : "_doc", - "_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 2cc137359b163..64bd8ad1b44ed 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -60,9 +60,11 @@ 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`. +(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 @@ -77,6 +79,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 @@ -123,8 +133,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 @@ -141,7 +152,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. @@ -173,12 +192,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 @@ -203,11 +239,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} @@ -430,3 +513,55 @@ 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", + "_type" : "_doc", + "_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/]