mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-05 20:48:22 +00:00
79db16f9bb
Global search timeouts and timeouts specified in the search request body use the same internal mechanism as search cancellation. Therefore the same caveats apply, mostly around the responsiveness of the timeout which gets only checked by a running search on segment boundaries by default. Closes #31263
191 lines
6.2 KiB
Plaintext
191 lines
6.2 KiB
Plaintext
[[search]]
|
|
= Search APIs
|
|
|
|
[partintro]
|
|
--
|
|
|
|
Most search APIs are <<search-multi-index-type,multi-index, multi-type>>, with the
|
|
exception of the <<search-explain>> endpoints.
|
|
|
|
[float]
|
|
[[search-routing]]
|
|
== Routing
|
|
|
|
When executing a search, Elasticsearch will pick the "best" copy of the data
|
|
based on the <<search-adaptive-replica,adaptive replica selection>> formula.
|
|
Which shards will be searched on can also 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/_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]
|
|
[[search-adaptive-replica]]
|
|
== Adaptive Replica Selection
|
|
|
|
By default, Elasticsearch will use what is called adaptive replica selection.
|
|
This allows the coordinating node to send the request to the copy deemed "best"
|
|
based on a number of criteria:
|
|
|
|
- Response time of past requests between the coordinating node and the node
|
|
containing the copy of the data
|
|
- Time past search requests took to execute on the node containing the data
|
|
- The queue size of the search threadpool on the node containing the data
|
|
|
|
This can be turned off by changing the dynamic cluster setting
|
|
`cluster.routing.use_adaptive_replica_selection` from `true` to `false`:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT /_cluster/settings
|
|
{
|
|
"transient": {
|
|
"cluster.routing.use_adaptive_replica_selection": false
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
If adaptive replica selection is turned off, searches are sent to the
|
|
index/indices shards in a round robin fashion between all copies of the data
|
|
(primaries and replicas).
|
|
|
|
[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 request body. These requests will be cancelled after
|
|
the specified time using the mechanism described in the following section on
|
|
<<global-search-cancellation>>. Therefore the same caveats about timeout
|
|
responsiveness apply.
|
|
|
|
The setting key is `search.default_search_timeout` and can be set using the
|
|
<<cluster-update-settings>> endpoints. The default value is no global timeout.
|
|
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.
|
|
|
|
[float]
|
|
[[search-concurrency-and-parallelism]]
|
|
== Search concurrency and parallelism
|
|
|
|
By default Elasticsearch doesn't reject any search requests based on the number
|
|
of shards the request hits. While Elasticsearch will optimize the search
|
|
execution on the coordinating node a large number of shards can have a
|
|
significant impact CPU and memory wise. It is usually a better idea to organize
|
|
data in such a way that there are fewer larger shards. In case you would like to
|
|
configure a soft limit, you can update the `action.search.shard_count.limit`
|
|
cluster setting in order to reject search requests that hit too many shards.
|
|
|
|
The request parameter `max_concurrent_shard_requests` can be used to control the
|
|
maximum number of concurrent shard requests the search API will execute for the
|
|
request. This parameter should be used to protect a single request from
|
|
overloading a cluster (e.g., a default request will hit all indices in a cluster
|
|
which could cause shard request rejections if the number of shards per node is
|
|
high). This default is based on the number of data nodes in the cluster but at
|
|
most `256`.
|
|
|
|
--
|
|
|
|
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-caps.asciidoc[]
|
|
|
|
include::search/rank-eval.asciidoc[]
|