112 lines
3.0 KiB
Plaintext
112 lines
3.0 KiB
Plaintext
[[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&refresh=true <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:
|
|
|
|
[source,js]
|
|
--------------------------
|
|
GET my_index/_search
|
|
{
|
|
"query": {
|
|
"terms": {
|
|
"_routing": [ "user1" ] <1>
|
|
}
|
|
}
|
|
}
|
|
--------------------------
|
|
// CONSOLE
|
|
|
|
<1> Querying on the `_routing` field (also see the <<query-dsl-ids-query,`ids` query>>)
|
|
|
|
==== 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.
|