Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs for search preferences #32098

Merged
merged 3 commits into from
Jul 18, 2018
Merged

Improve docs for search preferences #32098

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e297457
Improve docs for search preferences
DaveCTurner Jul 16, 2018
cae2225
Review feedback
DaveCTurner Jul 17, 2018
872b51b
Merge branch '6.x' into 2018-07-16-preference-docs
DaveCTurner Jul 17, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 73 additions & 34 deletions docs/reference/search/request/preference.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,76 @@
[[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.
Controls 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,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, for instance to make better use of
per-copy caches.

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. deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
`_primary`::
The operation will be executed only on primary shards. deprecated[6.1.0,
will be removed in 7.0. See the warning below for more information.]

`_primary_first`::
The operation will go and be executed on the primary
shard, and if not available (failover), will execute on other shards.
deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
`_primary_first`::
The operation will be executed on primary shards if possible, but will fall
back to other shards if not. deprecated[6.1.0, will be removed in 7.0. See
the warning below for more information.]

`_replica`::
The operation will go and be executed only on a replica shard.
deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
The operation will be executed only on replica shards. If there are multiple
replicas then the order of preference between them is unspecified.
deprecated[6.1.0, will be removed in 7.0. See the warning below for more
information.]

`_replica_first`::
The operation will go and be executed only on a replica shard, and if
not available (failover), will execute on other shards.
deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
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. deprecated[6.1.0, will be removed in
7.0. See the warning below for more information.]

`_local`::
The operation will prefer to be executed on a local
allocated shard if possible.
`_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`::
Prefers execution on the nodes with the provided
node ids (`abc` or `xyz` in this case) if applicable.
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`
`_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>>
`_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::
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.
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we want to say something like "That said, we expect this selection to be stable for a long period of time. This allows users of a customized value to optimize cache usage"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I did that in cae2225.

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 to ensure consistent ordering of results
for the user:
For instance, use the user's session ID `xyzabc123` as follows:

[source,js]
------------------------------------------------
Expand All @@ -65,3 +85,22 @@ GET /_search?preference=xyzabc123
------------------------------------------------
// CONSOLE

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,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think _only_nodes has the same so you won't need to route your request to the node in question

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.

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