IMPORTANT: Version 6.6 of Elasticsearch has passed its maintenance date.
This documentation is no longer being updated. For the latest information, see the current release documentation.
A document is routed to a particular shard in an index using the following formula:
shard_num = hash(_routing) % num_primary_shards
The default value used for
_routing is the document’s
Custom routing patterns can be implemented by specifying a custom
value per document. For instance:
This document uses
The value of the
_routing field is accessible in queries:
Querying on the
Custom routing can reduce the impact of searches. Instead of having to fan out a search request to all the shards in an index, the request can be sent to just the shard that matches the specific routing value (or values):
Forgetting the routing value can lead to a document being indexed on more than
one shard. As a safeguard, the
_routing field can be configured to make a
routing value required for all CRUD operations:
When indexing documents specifying a custom
_routing, the uniqueness of the
_id is not guaranteed across all of the shards in the index. In fact,
documents with the same
_id might end up on different shards if indexed with
It is up to the user to ensure that IDs are unique across the index.
An index can be configured such that custom routing values will go to a subset of the shards rather than a single shard. This helps mitigate the risk of ending up with an imbalanced cluster while still reducing the impact of searches.
This is done by providing the index level setting
index.routing_partition_size at index creation.
As the partition size increases, the more evenly distributed the data will become at the
expense of having to search more shards per request.
When this setting is present, the formula for calculating the shard becomes:
shard_num = (hash(_routing) + hash(_id) % routing_partition_size) % num_primary_shards
That is, the
_routing field is used to calculate a set of shards within the index and then the
_id is used to pick a shard within that set.
To enable this feature, the
index.routing_partition_size should have a value greater than 1 and
Once enabled, the partitioned index will have the following limitations:
- Mappings with
joinfield relationships cannot be created within it.
- All mappings within the index must have the
_routingfield marked as required.