routing-field.asciidoc 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
  1. [[mapping-routing-field]]
  2. === `_routing` field
  3. A document is routed to a particular shard in an index using the following
  4. formulas:
  5. routing_factor = num_routing_shards / num_primary_shards
  6. shard_num = (hash(_routing) % num_routing_shards) / routing_factor
  7. `num_routing_shards` is the value of the
  8. <<index-number-of-routing-shards,`index.number_of_routing_shards`>> index
  9. setting. `num_primary_shards` is the value of the
  10. <<index-number-of-shards,`index.number_of_shards`>> index setting.
  11. The default `_routing` value is the document's <<mapping-id-field,`_id`>>.
  12. Custom routing patterns can be implemented by specifying a custom `routing`
  13. value per document. For instance:
  14. [source,console]
  15. ------------------------------
  16. PUT my-index-000001/_doc/1?routing=user1&refresh=true <1>
  17. {
  18. "title": "This is a document"
  19. }
  20. GET my-index-000001/_doc/1?routing=user1 <2>
  21. ------------------------------
  22. // TESTSETUP
  23. <1> This document uses `user1` as its routing value, instead of its ID.
  24. <2> The same `routing` value needs to be provided when
  25. <<docs-get,getting>>, <<docs-delete,deleting>>, or <<docs-update,updating>>
  26. the document.
  27. The value of the `_routing` field is accessible in queries:
  28. [source,console]
  29. --------------------------
  30. GET my-index-000001/_search
  31. {
  32. "query": {
  33. "terms": {
  34. "_routing": [ "user1" ] <1>
  35. }
  36. }
  37. }
  38. --------------------------
  39. <1> Querying on the `_routing` field (also see the <<query-dsl-ids-query,`ids` query>>)
  40. NOTE: Data streams do not support custom routing. Instead, target the
  41. appropriate backing index for the stream.
  42. ==== Searching with custom routing
  43. Custom routing can reduce the impact of searches. Instead of having to fan
  44. out a search request to all the shards in an index, the request can be sent to
  45. just the shard that matches the specific routing value (or values):
  46. [source,console]
  47. ------------------------------
  48. GET my-index-000001/_search?routing=user1,user2 <1>
  49. {
  50. "query": {
  51. "match": {
  52. "title": "document"
  53. }
  54. }
  55. }
  56. ------------------------------
  57. <1> This search request will only be executed on the shards associated with the `user1` and `user2` routing values.
  58. ==== Making a routing value required
  59. When using custom routing, it is important to provide the routing value
  60. whenever <<docs-index_,indexing>>, <<docs-get,getting>>,
  61. <<docs-delete,deleting>>, or <<docs-update,updating>> a document.
  62. Forgetting the routing value can lead to a document being indexed on more than
  63. one shard. As a safeguard, the `_routing` field can be configured to make a
  64. custom `routing` value required for all CRUD operations:
  65. [source,console]
  66. ------------------------------
  67. PUT my-index-000002
  68. {
  69. "mappings": {
  70. "_routing": {
  71. "required": true <1>
  72. }
  73. }
  74. }
  75. PUT my-index-000002/_doc/1 <2>
  76. {
  77. "text": "No routing value provided"
  78. }
  79. ------------------------------
  80. // TEST[catch:bad_request]
  81. <1> Routing is required for all documents.
  82. <2> This index request throws a `routing_missing_exception`.
  83. ==== Unique IDs with custom routing
  84. When indexing documents specifying a custom `_routing`, the uniqueness of the
  85. `_id` is not guaranteed across all of the shards in the index. In fact,
  86. documents with the same `_id` might end up on different shards if indexed with
  87. different `_routing` values.
  88. It is up to the user to ensure that IDs are unique across the index.
  89. [[routing-index-partition]]
  90. ==== Routing to an index partition
  91. An index can be configured such that custom routing values will go to a subset of the shards rather
  92. than a single shard. This helps mitigate the risk of ending up with an imbalanced cluster while still
  93. reducing the impact of searches.
  94. This is done by providing the index level setting <<routing-partition-size,`index.routing_partition_size`>> at index creation.
  95. As the partition size increases, the more evenly distributed the data will become at the
  96. expense of having to search more shards per request.
  97. When this setting is present, the formulas for calculating the shard become:
  98. routing_value = hash(_routing) + hash(_id) % routing_partition_size
  99. shard_num = (routing_value % num_routing_shards) / routing_factor
  100. That is, the `_routing` field is used to calculate a set of shards within the index and then the
  101. `_id` is used to pick a shard within that set.
  102. To enable this feature, the `index.routing_partition_size` should have a value greater than 1 and
  103. less than `index.number_of_shards`.
  104. Once enabled, the partitioned index will have the following limitations:
  105. * Mappings with <<parent-join,`join` field>> relationships cannot be created within it.
  106. * All mappings within the index must have the `_routing` field marked as required.