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

119 lines
3.2 KiB
Plaintext
Raw Normal View History

[[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>
------------------------------
// AUTOSENSE
// TESTSETUP
<1> This document uses `user1` as its routing value, instead of its ID.
2016-02-09 05:07:32 -05:00
<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": {
2016-05-06 03:25:58 -04:00
"script": "doc['_routing']" <2>
}
}
}
--------------------------
// AUTOSENSE
<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"
}
}
}
------------------------------
// AUTOSENSE
<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"
}
------------------------------
// AUTOSENSE
// 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.