OpenSearch/docs/reference/search/request/preference.asciidoc

[[request-body-search-preference]]
==== Preference

Controls a `preference` of the shard copies on which to execute the search.  By
default, Elasticsearch selects from the available shard copies in an
unspecified order, taking the <<shard-allocation-awareness,allocation awareness>> and
<<search-adaptive-replica,adaptive replica selection>> configuration into
account. However, it may sometimes be desirable to try and route certain
searches to certain sets of shard copies.

A possible use case would be to make use of per-copy caches like the
<<shard-request-cache,request cache>>. Doing this, however, runs contrary to the
idea of search parallelization and can create hotspots on certain nodes because
the load might not be evenly distributed anymore.

The `preference` is a query string parameter which can be set to:

[horizontal]
`_only_local`::
	The operation will be executed only on shards allocated to the local
	node.

`_local`::
	The operation will be executed on shards allocated to the local node if
	possible, and will fall back to other shards if not.

`_prefer_nodes:abc,xyz`::
	The operation will be executed on nodes with one of the provided node
	ids (`abc` or `xyz` in this case) if possible. If suitable shard copies
	exist on more than one of the selected nodes then the order of
	preference between these copies is unspecified.

`_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|_local`

`_only_nodes:abc*,x*yz,...`::
	Restricts the operation to nodes specified according to the
	<<cluster,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 `_`. If two searches both give the same
	custom string value for their preference and the underlying cluster state
	does not change then the same ordering of shards will be used for the
	searches. This does not guarantee that the exact same shards will be used
	each time: the cluster state, and therefore the selected shards, may change
	for a number of reasons including shard relocations and shard failures, and
	nodes may sometimes reject searches causing fallbacks to alternative nodes.
	However, in practice the ordering of shards tends to remain stable for long
	periods of time. A good candidate for a custom preference value is something
	like the web session id or the user name.

For instance, use the user's session ID `xyzabc123` as follows:

[source,console]
------------------------------------------------
GET /_search?preference=xyzabc123
{
  "query": {
    "match": {
      "title": "elasticsearch"
    }
  }
}
------------------------------------------------

This can be an effective strategy to increase usage of e.g. the request cache for
unique users running similar searches repeatedly by always hitting the same cache, while
requests of different users are still spread across all shard copies.

NOTE: 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.