NOTE: You are looking at documentation for an older release. For the latest information, see the current release documentation.
Preference
editPreference
editControls a preference
of which shard copies on which to execute the search.
By default, Elasticsearch selects from the available shard copies in an
unspecified order, taking the allocation awareness and
adaptive replica selection configuration into
account. However, it may sometimes be desirable to try and route certain
searches to certain sets of shard copies, for instance to make better use of
per-copy caches.
The preference
is a query string parameter which can be set to:
|
The operation will be executed only on primary shards. [6.1.0] Deprecated in 6.1.0. will be removed in 7.0. See the warning below for more information. |
|
The operation will be executed on primary shards if possible, but will fall back to other shards if not. [6.1.0] Deprecated in 6.1.0. will be removed in 7.0. See the warning below for more information. |
|
The operation will be executed only on replica shards. If there are multiple replicas then the order of preference between them is unspecified. [6.1.0] Deprecated in 6.1.0. will be removed in 7.0. See the warning below for more information. |
|
The operation will be executed on replica shards if possible, but will fall back to other shards if not. If there are multiple replicas then the order of preference between them is unspecified. [6.1.0] Deprecated in 6.1.0. will be removed in 7.0. See the warning below for more information. |
|
The operation will be executed only on shards allocated to the local node. |
|
The operation will be executed on shards allocated to the local node if possible, and will fall back to other shards if not. |
|
The operation will be executed on nodes with one of the provided node
ids ( |
|
Restricts the operation to the specified shards. ( |
|
Restricts the operation to nodes specified according to the node specification. If suitable shard copies exist on more than one of the selected nodes then the order of preference between these copies is unspecified. |
Custom (string) value |
Any value that does not start with |
For instance, use the user’s session ID xyzabc123
as follows:
GET /_search?preference=xyzabc123 { "query": { "match": { "title": "elasticsearch" } } }
The _only_local
preference guarantees only to use shard copies on the
local node, which is sometimes useful for troubleshooting. All other options do
not fully guarantee that any particular shard copies are used in a search,
and on a changing index this may mean that repeated searches may yield
different results if they are executed on different shard copies which are in
different refresh states.
If a node has shard allocation awareness
attributes, then it will prefer shards with the same awareness attribute values.
Because of these attributes, different coordinating nodes may route the same
search differently, even if the searches use the same custom preference
values.
In recent Elasticsearch versions, awareness attributes no longer influence search routing.
The _primary
, _primary_first
, _replica
and _replica_first
are
deprecated as their use is not recommended. They do not help to avoid
inconsistent results that arise from the use of shards that have different
refresh states, and Elasticsearch uses synchronous replication so the primary
does not in general hold fresher data than its replicas. The _primary_first
and _replica_first
preferences silently fall back to non-preferred copies if
it is not possible to search the preferred copies. The _primary
and
_replica
preferences will silently change their preferred shards if a replica
is promoted to primary, which can happen at any time. The _primary
preference
can also put undesirable extra load on the primary shards. The cache-related
benefits of these options can also be obtained using _only_nodes
,
_prefer_nodes
, or a custom string value instead.