[[mapping-routing-field]] === `_routing` field 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 <> or the document's <> ID, if present. Custom routing patterns can be implemented by specifying a custom `routing` value per document. For instance: [source,js] ------------------------------ PUT my_index/my_type/1?routing=user1 <1> { "title": "This is a document" } GET my_index/my_type/1?routing=user1 <2> ------------------------------ // CONSOLE // TESTSETUP <1> This document uses `user1` as its routing value, instead of its ID. <2> The same `routing` value needs to be provided when <>, <>, or <> the document. The value of the `_routing` field is accessible in queries and scripts: [source,js] -------------------------- GET my_index/_search { "query": { "terms": { "_routing": [ "user1" ] <1> } }, "script_fields": { "Routing value": { "script": "doc['_routing']" <2> } } } -------------------------- // CONSOLE <1> Querying on the `_routing` field (also see the <>) <2> Accessing the `_routing` field in scripts (inline scripts must be <> for this example to work) ==== Searching with custom routing 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): [source,js] ------------------------------ GET my_index/_search?routing=user1,user2 <1> { "query": { "match": { "title": "document" } } } ------------------------------ // CONSOLE <1> This search request will only be executed on the shards associated with the `user1` and `user2` routing values. ==== Making a routing value required When using custom routing, it is important to provide the routing value whenever <>, <>, <>, or <> 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 custom `routing` value required for all CRUD operations: [source,js] ------------------------------ PUT my_index2 { "mappings": { "my_type": { "_routing": { "required": true <1> } } } } PUT my_index2/my_type/1 <2> { "text": "No routing value provided" } ------------------------------ // CONSOLE // TEST[catch:request] <1> Routing is required for `my_type` documents. <2> This index request throws a `routing_missing_exception`. ==== Unique IDs with custom routing 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.