elasticsearch/docs/reference/search/request-body.asciidoc

[[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",
                "_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[]