[[search]]
= Search APIs

[partintro]
--

Most search APIs are <<search-multi-index-type,multi-index&#44; multi-type>>, with the
exception of the <<search-explain>> endpoints.

[float]
[[search-routing]]
== Routing

When executing a search, it will be broadcast to all the index/indices
shards (round robin between replicas). Which shards will be searched on
can be controlled by providing the `routing` parameter. For example,
when indexing tweets, the routing value can be the user name:

[source,js]
--------------------------------------------------
$ curl -XPOST 'http://localhost:9200/twitter/tweet?routing=kimchy' -d '{
    "user" : "kimchy",
    "postDate" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}
'
--------------------------------------------------

In such a case, if we want to search only on the tweets for a specific
user, we can specify it as the routing, resulting in the search hitting
only the relevant shard:

[source,js]
--------------------------------------------------
$ curl -XGET 'http://localhost:9200/twitter/tweet/_search?routing=kimchy' -d '{
    "query": {
        "bool" : {
            "must" : {
                "query_string" : {
                    "query" : "some query string here"
                }
            },
            "filter" : {
                "term" : { "user" : "kimchy" }
            }
        }
    }
}
'
--------------------------------------------------

The routing parameter can be multi valued represented as a comma
separated string. This will result in hitting the relevant shards where
the routing values match to.

[float]
[[stats-groups]]
== Stats Groups

A search can be associated with stats groups, which maintains a
statistics aggregation per group. It can later be retrieved using the
<<indices-stats,indices stats>> API
specifically. For example, here is a search body request that associate
the request with two different groups:

[source,js]
--------------------------------------------------
{
    "query" : {
        "match_all" : {}
    },
    "stats" : ["group1", "group2"]
}
--------------------------------------------------

[float]
[[global-search-timeout]]
== Global Search Timeout

Individual searches can have a timeout as part of the
<<search-request-body>>. Since search requests can originate from many
sources, Elasticsearch has a dynamic cluster-level setting for a global
search timeout that applies to all search requests that do not set a
timeout in the <<search-request-body>>. The default value is no global
timeout. The setting key is `search.default_search_timeout` and can be
set using the <<cluster-update-settings>> endpoints. Setting this value
to `-1` resets the global search timeout to no timeout.

--

include::search/search.asciidoc[]

include::search/uri-request.asciidoc[]

include::search/request-body.asciidoc[]

include::search/search-template.asciidoc[]

include::search/search-shards.asciidoc[]

include::search/suggesters.asciidoc[]

include::search/multi-search.asciidoc[]

include::search/count.asciidoc[]

include::search/exists.asciidoc[]

include::search/validate.asciidoc[]

include::search/explain.asciidoc[]

include::search/profile.asciidoc[]

include::search/percolate.asciidoc[]

include::search/field-stats.asciidoc[]