OpenSearch/docs/reference/mapping/fields/routing-field.asciidoc

[[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 <<mapping-id-field,`_id`>>
or the document's <<mapping-parent-field,`_parent`>> 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
    <<docs-get,getting>>, <<docs-delete,deleting>>, or <<docs-update,updating>>
    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 <<query-dsl-ids-query,`ids` query>>)
<2> Accessing the `_routing` field in scripts (inline scripts must be <<enable-dynamic-scripting,enabled>> 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 <<docs-index_,indexing>>, <<docs-get,getting>>,
<<docs-delete,deleting>>, or <<docs-update,updating>> 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.