A document is routed to a particular shard in an index using the following formulas:

routing_factor = num_routing_shards / num_primary_shardsshard_num = (hash(_routing) % num_routing_shards) / routing_factor

num_routing_shards is the value of theindex.number_of_routing_shards index setting.num_primary_shards is the value of theindex.number_of_shards index setting.

The default_routing value is the document’s_id. Custom routing patterns can be implemented by specifying a customrouting value per document. For instance:

PUT my-index-000001/_doc/1?routing=user1&refresh=true{  "title": "This is a document"}GET my-index-000001/_doc/1?routing=user1

1. This document usesuser1 as its routing value, instead of its ID.
2. The samerouting value needs to be provided whengetting,deleting, orupdating the document.

The value of the_routing field is accessible in queries:

GET my-index-000001/_search{  "query": {    "terms": {      "_routing": [ "user1" ]    }  }}

1. Querying on the_routing field (also see theids query)

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):

GET my-index-000001/_search?routing=user1,user2{  "query": {    "match": {      "title": "document"    }  }}

1. This search request will only be executed on the shards associated with theuser1 anduser2 routing values.

When using custom routing, it is important to provide the routing value wheneverindexing,getting,deleting, orupdating a document.

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 customrouting value required for all CRUD operations:

PUT my-index-000002{  "mappings": {    "_routing": {      "required": true    }  }}PUT my-index-000002/_doc/1{  "text": "No routing value provided"}

1. Routing is required for all documents.
2. This index request throws arouting_missing_exception.

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 different_routing values.

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 settingindex.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 formulas for calculating the shard become:

routing_value = hash(_routing) + hash(_id) % routing_partition_sizeshard_num = (routing_value % num_routing_shards) / routing_factor

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, theindex.routing_partition_size should have a value greater than 1 and less thanindex.number_of_shards.

Once enabled, the partitioned index will have the following limitations:

• Mappings withjoin field relationships cannot be created within it.
• All mappings within the index must have the_routing field marked as required.