mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-07 21:48:39 +00:00
d01a62908a
The shards preference on a search request enables specifying a list of shards to hit, and then a secondary preference (e.g., "_primary") can be added. Today, the separator between the shards list and the secondary preference is ';'. Unfortunately, this is also a valid separtor for URL query parameters. This means that a preference like "_shards:0;_primary" will be parsed into two URL parameters: "_shards:0" and "_primary". With the recent change to strict URL parsing, the second parameter will be rejected, "_primary" is not a valid URL parameter on a search request. This means that this feature has never worked (unless the ';' is escaped, but no one does that because our docs do not that, and there was no indication from Elasticsearch that this did not work). This commit changes the separator to '|'. Relates #20786
66 lines
1.9 KiB
Plaintext
66 lines
1.9 KiB
Plaintext
[[search-request-preference]]
|
|
=== Preference
|
|
|
|
Controls a `preference` of which shard replicas to execute the search
|
|
request on. By default, the operation is randomized between the shard
|
|
replicas.
|
|
|
|
The `preference` is a query string parameter which can be set to:
|
|
|
|
[horizontal]
|
|
`_primary`::
|
|
The operation will go and be executed only on the primary
|
|
shards.
|
|
|
|
`_primary_first`::
|
|
The operation will go and be executed on the primary
|
|
shard, and if not available (failover), will execute on other shards.
|
|
|
|
`_replica`::
|
|
The operation will go and be executed only on a replica shard.
|
|
|
|
`_replica_first`::
|
|
The operation will go and be executed only on a replica shard, and if
|
|
not available (failover), will execute on other shards.
|
|
|
|
`_local`::
|
|
The operation will prefer to be executed on a local
|
|
allocated shard if possible.
|
|
|
|
`_prefer_nodes:abc,xyz`::
|
|
Prefers execution on the nodes with the provided
|
|
node ids (`abc` or `xyz` in this case) if applicable.
|
|
|
|
`_shards:2,3`::
|
|
Restricts the operation to the specified shards. (`2`
|
|
and `3` in this case). This preference can be combined with other
|
|
preferences but it has to appear first: `_shards:2,3|_primary`
|
|
|
|
`_only_nodes`::
|
|
Restricts the operation to nodes specified in node specification
|
|
https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.html
|
|
|
|
Custom (string) value::
|
|
A custom value will be used to guarantee that
|
|
the same shards will be used for the same custom value. This can help
|
|
with "jumping values" when hitting different shards in different refresh
|
|
states. A sample value can be something like the web session id, or the
|
|
user name.
|
|
|
|
For instance, use the user's session ID to ensure consistent ordering of results
|
|
for the user:
|
|
|
|
[source,js]
|
|
------------------------------------------------
|
|
GET /_search?preference=xyzabc123
|
|
{
|
|
"query": {
|
|
"match": {
|
|
"title": "elasticsearch"
|
|
}
|
|
}
|
|
}
|
|
------------------------------------------------
|
|
// CONSOLE
|
|
|