[DOCS] Reformats request body search API (#46254)
* [DOCS] Reformats request body search API. Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
ece9eb4acd
commit
5c5af77565
|
|
@ -1,9 +1,7 @@
|
|||
[[search-request-body]]
|
||||
=== Request Body Search
|
||||
|
||||
The search request can be executed with a search DSL, which includes the
|
||||
<<query-dsl,Query DSL>>, 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 /<index>/_search
|
||||
{
|
||||
"query": {<parameters>}
|
||||
}`
|
||||
|
||||
|
||||
[[search-request-body-api-desc]]
|
||||
==== {api-description-title}
|
||||
|
||||
The search request can be executed with a search DSL, which includes the
|
||||
<<query-dsl,Query DSL>>, 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 <<ccs-reduction>> 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 <<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=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 <<global-search-cancellation>> mechanism.
|
||||
Defaults to no timeout. See <<time-units>>.
|
||||
|
||||
`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 <<request-body-search-search-type,_Search Type_>> 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 <<shard-request-cache>>.
|
||||
|
||||
`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 <<ccs-reduction>> 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[]
|
||||
|
|
|
|||
Loading…
Reference in New Issue