Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Routing mapping description rewritten #55

Open
wants to merge 4 commits into from

2 participants

@derrickburns

Please review to make sure I got this right. I did not understand the original description.

guide/reference/mapping/routing-field.textile
@@ -5,26 +5,26 @@ cat: guide
sidebar: reference_mapping
---
-p. The routing field allows to control the @_routing@ aspect when indexing data and explicit routing control is required.
+p. When an index is sharded, a shard must be selected to index an incoming document. The shard chosen is a function of the @routing value@. The @_routing@ field mapping specifies how the routing value is determined.
@kimchy Owner
kimchy added a note

By default, the routing value is based on the document id, so its not really that the routing value is required. Maybe it makes sense to add it?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
guide/reference/mapping/routing-field.textile
((6 lines not shown))
h1. store / index
-p. The first thing the @_routing@ mapping does is to store the routing value provided (@store@ set to @yes@) and index it (@index@ set to @not_analyzed@). The reason why the routing is stored by default is so reindexing data will be possible if the routing value is completely external and not part of the docs.
+p. By default, the routing value is stored (@store@ set to @yes@) as the value of the @_routing@ field of the document and indexed (@index@ set to @not_analyzed@). Storing the routing value as a field in the document enables easy re-indexing, should that be necessary.
@kimchy Owner
kimchy added a note

I would add that by default, if the routing value is used, then its stored.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@derrickburns

Ok, I tried again. Let me know if this is right.

@derrickburns

Do you want this? If not, please close the issue. Thanks.

@derrickburns derrickburns reopened this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 17 additions and 9 deletions.
  1. +17 −9 guide/reference/mapping/routing-field.textile
View
26 guide/reference/mapping/routing-field.textile
@@ -5,26 +5,26 @@ cat: guide
sidebar: reference_mapping
---
-p. The routing field allows to control the @_routing@ aspect when indexing data and explicit routing control is required.
+p. When an index is sharded, a shard must be selected to index an incoming document. The shard chosen is a function of the @_routing value@. There are three methods for specifying the @routing value@. The method chosen is determined by the mapping of the @_routing@ value and the presence of the @_routing@ field in document as follows.
-h1. store / index
+h1. Implicit Routing
-p. The first thing the @_routing@ mapping does is to store the routing value provided (@store@ set to @yes@) and index it (@index@ set to @not_analyzed@). The reason why the routing is stored by default is so reindexing data will be possible if the routing value is completely external and not part of the docs.
+Typically, the id of a document is used as its routing value. This is the default case. No @_routing@ mapping need be provided in order to select implicit routing.
-h1. required
+h1. Explicit Routing
-p. Another aspect of the @_routing@ mapping is the ability define it as required by setting @required@ to @true@. This is very important to set when using routing features, as it allows different APIs to make use of it. For example, and index operation will be rejected if no routing value has been provided (or derived from the doc). A delete operation will be broadcasted to all shards with no routing value is provided and @_routing@ is required.
+A document may provide its routing value explicitly by providing a field called @_routing@ whose value is used as the routing value. In this case, not @_routing@ mapping is necessary, but the document must provide the routing value in the @_routing@ field.
-h1. path
+h1. Indirect Routing
-p. The routing value can be provided as an external value when indexing (and still stored as part of the document, in much the same way @_source@ is stored). But, it can also be automatically extracted from the index doc based on a @path@. For example, having the following mapping:
+A document may provide its routing value in a field other than @_routing@. To do so, a mapping must be provided for the @_routing@ field that identifies the document field that contains the mapping value. This indirection is specified in the mapping by defining a @path@ property in the mapping. For example, having the following mapping:
<pre class="prettyprint lang-js">
{
"comment" : {
"_routing" : {
"required" : true,
- "path" : "blog.post_id"
+ "path" : "blog.id"
}
}
}
@@ -41,4 +41,12 @@ p. Will cause the following doc to be routed based on the @111222@ value:
}
</pre>
-p. Note, using @path@ without explicit routing value provided required an additional (though quite fast) parsing phase.
+
+h1. store / index
+
+p. By default, the routing value is stored (@store@ set to @yes@) as the value of the @_routing@ field of the document and indexed (@index@ set to @not_analyzed@). Storing the routing value as a field in the document enables easy re-indexing, should that be necessary.
+
+h1. required
+
+p. By setting the mapping property @required@ of the @_routing@ mapping to @true@, one may require that a routing value be provided in a document for the document to be indexed. If no such routing value can be determined and @required@ is set to @true@, then the document will not be indexed.
+
Something went wrong with that request. Please try again.