Routing
OpenSearch uses a hashing algorithm to route documents to specific shards in an index. By default, the document’s _id
field is used as the routing value, but you can also specify a custom routing value for each document.
Default routing
The following is the default OpenSearch routing formula. The _routing
value is the document’s _id
.
shard_num = hash(_routing) % num_primary_shards
Custom routing
You can specify a custom routing value when indexing a document, as shown in the following example request:
PUT sample-index1/_doc/1?routing=JohnDoe1
{
"title": "This is a document"
}
In this example, the document is routed using the value JohnDoe1
instead of the default _id
.
You must provide the same routing value when retrieving, deleting, or updating the document, as shown in the following example request:
GET sample-index1/_doc/1?routing=JohnDoe1
Querying by routing
You can query documents based on their routing value by using the _routing
field, as shown in the following example. This query only searches the shard(s) associated with the JohnDoe1
routing value:
GET sample-index1/_search
{
"query": {
"terms": {
"_routing": [ "JohnDoe1" ]
}
}
}
Required routing
You can make custom routing required for all CRUD operations on an index, as shown in the following example request. If you try to index a document without providing a routing value, OpenSearch will throw an exception.
PUT sample-index2
{
"mappings": {
"_routing": {
"required": true
}
}
}
Routing to specific shards
You can configure an index to route custom values to a subset of shards rather than a single shard. This is done by setting index.routing_partition_size
at the time of index creation. The formula for calculating the shard is shard_num = (hash(_routing) + hash(_id)) % routing_partition_size) % num_primary_shards
.
The following example request routes documents to one of four shards in the index:
PUT sample-index3
{
"settings": {
"index.routing_partition_size": 4
},
"mappings": {
"_routing": {
"required": true
}
}
}