Skip to content

Commit

Permalink
[DOCS] Relocate search API's request body parameters (#56304)
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@jrodewig
jrodewig authored May 7, 2020
1 parent 883bb29 commit b5f219c
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 106 deletions.
99 changes: 1 addition & 98 deletions docs/reference/search/request-body.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ GET /twitter/_search
[[search-request-body-api-request]]
==== {api-request-title}


`GET /<index>/_search
{
"query": {<parameters>}
Expand All @@ -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 <<ccs-network-delays>>. 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 <<shard-request-cache>>.

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 <<search-search-api-request-body,request body parameters>>.

==== Fast check for any matching docs

Expand Down
150 changes: 142 additions & 8 deletions docs/reference/search/search.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,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 <<ccs-network-delays>>. Defaults to `true`.

`docvalue_fields`::
(Optional, string) A comma-separated list of fields to return as the docvalue
Expand All @@ -75,6 +77,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
Expand Down Expand Up @@ -121,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 <<shard-request-cache>>. Defaults to index
level settings.

`rest_total_hits_as_int`::
(Optional, boolean) Indicates whether hits.total should be rendered as an
Expand All @@ -139,7 +150,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 <field>:<direction> pairs.
Expand Down Expand Up @@ -171,12 +190,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, <<time-units, time units>>) 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, <<time-units, time units>>) 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
Expand All @@ -201,11 +237,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, <<query-dsl,query object>>) Defines the search definition using the
<<query-dsl,Query DSL>>.

`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, <<time-units, time units>>) 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}
Expand Down Expand Up @@ -422,3 +505,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/]

0 comments on commit b5f219c

Please sign in to comment.