[[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]
--------------------------------------------------
POST /twitter/tweet?routing=kimchy
{
    "user" : "kimchy",
    "postDate" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}
--------------------------------------------------
// CONSOLE

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]
--------------------------------------------------
POST /twitter/tweet/_search?routing=kimchy
{
    "query": {
        "bool" : {
            "must" : {
                "query_string" : {
                    "query" : "some query string here"
                }
            },
            "filter" : {
                "term" : { "user" : "kimchy" }
            }
        }
    }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

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]
--------------------------------------------------
POST /_search
{
    "query" : {
        "match_all" : {}
    },
    "stats" : ["group1", "group2"]
}
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]

[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.

[float]
[[global-search-cancellation]]
== Search Cancellation

Searches can be cancelled using standard <<task-cancellation,task cancellation>>
mechanism. By default, a running search only checks if it is cancelled or
not on segment boundaries, therefore the cancellation can be delayed by large
segments. The search cancellation responsiveness can be improved by setting
the dynamic cluster-level setting `search.low_level_cancellation` to `true`.
However, it comes with an additional overhead of more frequent cancellation
checks that can be noticeable on large fast running search queries. Changing this
setting only affects the searches that start after the change is made.

--

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/validate.asciidoc[]

include::search/explain.asciidoc[]

include::search/profile.asciidoc[]

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

include::search/rank-eval.asciidoc[]