248 lines
6.9 KiB
Plaintext
248 lines
6.9 KiB
Plaintext
[[search-request-body]]
|
|
=== Request Body Search
|
|
|
|
Specifies search criteria as request body parameters.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /twitter/_search
|
|
{
|
|
"query" : {
|
|
"term" : { "user" : "kimchy" }
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
|
|
[[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=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/]
|
|
|
|
|
|
==== Fast check for any matching docs
|
|
|
|
NOTE: `terminate_after` is always applied **after** the `post_filter` and stops
|
|
the query as well as the aggregation executions when enough hits have been
|
|
collected on the shard. Though the doc count on aggregations may not reflect
|
|
the `hits.total` in the response since aggregations are applied **before** the
|
|
post filtering.
|
|
|
|
In case we only want to know if there are any documents matching a
|
|
specific query, we can set the `size` to `0` to indicate that we are not
|
|
interested in the search results. Also we can set `terminate_after` to `1`
|
|
to indicate that the query execution can be terminated whenever the first
|
|
matching document was found (per shard).
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_search?q=message:number&size=0&terminate_after=1
|
|
--------------------------------------------------
|
|
// 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
|
|
as many documents matching the query when it was early terminated.
|
|
Also if the query was terminated early, the `terminated_early` flag will
|
|
be set to `true` in the response.
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"took": 3,
|
|
"timed_out": false,
|
|
"terminated_early": true,
|
|
"_shards": {
|
|
"total": 1,
|
|
"successful": 1,
|
|
"skipped" : 0,
|
|
"failed": 0
|
|
},
|
|
"hits": {
|
|
"total" : {
|
|
"value": 1,
|
|
"relation": "eq"
|
|
},
|
|
"max_score": null,
|
|
"hits": []
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// 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
|
|
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[]
|
|
|
|
include::request/collapse.asciidoc[]
|
|
|
|
include::request/from-size.asciidoc[]
|
|
|
|
include::request/highlighting.asciidoc[]
|
|
|
|
include::request/index-boost.asciidoc[]
|
|
|
|
include::request/inner-hits.asciidoc[]
|
|
|
|
include::request/min-score.asciidoc[]
|
|
|
|
include::request/named-queries-and-filters.asciidoc[]
|
|
|
|
include::request/post-filter.asciidoc[]
|
|
|
|
include::request/preference.asciidoc[]
|
|
|
|
include::request/query.asciidoc[]
|
|
|
|
include::request/rescore.asciidoc[]
|
|
|
|
include::request/script-fields.asciidoc[]
|
|
|
|
include::request/scroll.asciidoc[]
|
|
|
|
include::request/search-after.asciidoc[]
|
|
|
|
include::request/search-type.asciidoc[]
|
|
|
|
include::request/seq-no.asciidoc[]
|
|
|
|
include::request/sort.asciidoc[]
|
|
|
|
include::request/source-filtering.asciidoc[]
|
|
|
|
include::request/stored-fields.asciidoc[]
|
|
|
|
include::request/track-total-hits.asciidoc[]
|
|
|
|
include::request/version.asciidoc[]
|