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

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

Controls a `preference` of which shard copies on which to execute the
search. By default, the operation is randomized among the available shard 
copies, unless allocation awareness is used.

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

[horizontal]
`_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|_local`

`_only_nodes`::
    Restricts the operation to nodes specified in <<cluster,node specification>>

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