WARNING: Version 2.3 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« _parent field _source field »
Elastic Docs ›Elasticsearch Guide [2.3] ›Mapping ›Meta-Fields

_routing field

edit

_routing field

edit

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 _id or the document’s _parent ID, if present.

Custom routing patterns can be implemented by specifying a custom routing value per document. For instance:

PUT my_index/my_type/1?routing=user1 
{
  "title": "This is a document"
}

GET my_index/my_type/1?routing=user1

This document uses user1 as its routing value, instead of its ID.

The same routing value needs to be provided when getting, deleting, or updating the document.

The value of the _routing field is accessible in queries, aggregations, scripts, and when sorting:

GET my_index/_search
{
  "query": {
    "terms": {
      "_routing": [ "user1" ] 
    }
  },
  "aggs": {
    "Routing values": {
      "terms": {
        "field": "_routing", 
        "size": 10
      }
    }
  },
  "sort": [
    {
      "_routing": { 
        "order": "desc"
      }
    }
  ],
  "script_fields": {
    "Routing value": {
      "script": "doc['_routing']" 
    }
  }
}

Querying on the _routing field (also see the ids query)

Aggregating on the _routing field

Sorting on the _routing field

Accessing the _routing field in scripts (inline scripts must be enabled for this example to work)

Searching with custom routing

edit

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):

GET my_index/_search?routing=user1,user2 
{
  "query": {
    "match": {
      "title": "document"
    }
  }
}

This search request will only be executed on the shards associated with the user1 and user2 routing values.

Making a routing value required

edit

When using custom routing, it is important to provide the routing value whenever indexing, getting, deleting, or 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:

PUT my_index
{
  "mappings": {
    "my_type": {
      "_routing": {
        "required": true 
      }
    }
  }
}

PUT my_index/my_type/1 
{
  "text": "No routing value provided"
}

Routing is required for my_type documents.

This index request throws a routing_missing_exception.

Unique IDs with custom routing

edit

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.

« _parent field _source field »