docs: Use stackexchange based example to make documentation easier to understand

This commit is contained in:
Martijn van Groningen 2017-08-04 14:51:23 +02:00
parent 829f7cb658
commit b88cfe2008
No known key found for this signature in database
GPG Key ID: AB236F4FCF2AF12A
1 changed files with 49 additions and 50 deletions

View File

@ -17,7 +17,7 @@ PUT my_index
"my_join_field": { <1>
"type": "join",
"relations": {
"my_parent": "my_child" <2>
"question": "answer" <2>
}
}
}
@ -28,34 +28,34 @@ PUT my_index
// CONSOLE
<1> The name for the field
<2> Defines a single relation where `my_parent` is parent of `my_child`.
<2> Defines a single relation where `question` is parent of `answer`.
To index a document with a join, the name of the relation and the optional parent
of the document must be provided in the `source`.
For instance the following creates two parent documents in the `my_parent` context:
For instance the following creates two parent documents in the `question` context:
[source,js]
--------------------------------------------------
PUT my_index/doc/1?refresh
{
"text": "This is a parent document",
"text": "This is a question",
"my_join_field": {
"name": "my_parent" <1>
"name": "question" <1>
}
}
PUT my_index/doc/2?refresh
{
"text": "This is a another parent document",
"text": "This is a another question",
"my_join_field": {
"name": "my_parent"
"name": "question"
}
}
--------------------------------------------------
// CONSOLE
// TEST[continued]
<1> This document is a `my_parent` document.
<1> This document is a `question` document.
When indexing parent documents, you can choose to specify just the name of the relation
as a shortcut instead of encapsulating it in the normal object notation:
@ -64,14 +64,14 @@ as a shortcut instead of encapsulating it in the normal object notation:
--------------------------------------------------
PUT my_index/doc/1?refresh
{
"text": "This is a parent document",
"my_join_field": "my_parent" <1>
"text": "This is a question",
"my_join_field": "question" <1>
}
PUT my_index/doc/2?refresh
{
"text": "This is a another parent document",
"my_join_field": "my_parent"
"text": "This is another question",
"my_join_field": "question"
}
--------------------------------------------------
// CONSOLE
@ -85,7 +85,6 @@ must be added in the `_source`.
WARNING: It is required to index the lineage of a parent in the same shard so you must
always route child documents using their greater parent id.
For instance the following index two children documents pointing to the same parent `1`
with a `routing` value equals to the `id` of the parent:
@ -93,18 +92,18 @@ with a `routing` value equals to the `id` of the parent:
--------------------------------------------------
PUT my_index/doc/3?routing=1&refresh <1>
{
"text": "This is a child document",
"text": "This is an answer",
"my_join_field": {
"name": "my_child", <2>
"name": "answer", <2>
"parent": "1" <3>
}
}
PUT my_index/doc/4?routing=1&refresh
{
"text": "This is a another child document",
"text": "This is another answer",
"my_join_field": {
"name": "my_child",
"name": "answer",
"parent": "1"
}
}
@ -113,12 +112,12 @@ PUT my_index/doc/4?routing=1&refresh
// TEST[continued]
<1> This child document must be on the same shard than its parent
<2> `my_child` is the name of the join for this document
<2> `answer` is the name of the join for this document
<3> The parent id of this child document
==== Parent-join restrictions
* Only one `join` field is allowed per index mapping.
* Only one `join` field mapping is allowed per index.
* Parent and child documents must be indexed on the same shard.
This means that the same `routing` value needs to be provided when
<<docs-get,getting>>, <<docs-delete,deleting>>, or <<docs-update,updating>>
@ -175,8 +174,8 @@ Will return:
"_id": "1",
"_score": null,
"_source": {
"text": "This is a parent document",
"my_join_field": "my_parent" <1>
"text": "This is a question",
"my_join_field": "question" <1>
},
"sort": [
"1"
@ -188,8 +187,8 @@ Will return:
"_id": "2",
"_score": null,
"_source": {
"text": "This is a another parent document",
"my_join_field": "my_parent" <2>
"text": "This is another question",
"my_join_field": "question" <2>
},
"sort": [
"2"
@ -202,9 +201,9 @@ Will return:
"_score": null,
"_routing": "1",
"_source": {
"text": "This is a child document",
"text": "This is an answer",
"my_join_field": {
"name": "my_child", <3>
"name": "answer", <3>
"parent": "1" <4>
}
},
@ -219,9 +218,9 @@ Will return:
"_score": null,
"_routing": "1",
"_source": {
"text": "This is a another child document",
"text": "This is another answer",
"my_join_field": {
"name": "my_child",
"name": "answer",
"parent": "1"
}
},
@ -235,9 +234,9 @@ Will return:
--------------------------------------------------
// TESTRESPONSE[s/\.\.\./"timed_out": false, "took": $body.took, "_shards": $body._shards/]
<1> This document belongs to the `my_parent` join
<2> This document belongs to the `my_parent` join
<3> This document belongs to the `my_child` join
<1> This document belongs to the `question` join
<2> This document belongs to the `question` join
<3> This document belongs to the `answer` join
<4> The linked parent id for the child document
==== Parent-join queries and aggregations
@ -257,14 +256,14 @@ GET my_index/_search
{
"query": {
"parent_id": { <1>
"type": "my_child",
"type": "answer",
"id": "1"
}
},
"aggs": {
"parents": {
"terms": {
"field": "my_join_field#my_parent", <2>
"field": "my_join_field#question", <2>
"size": 10
}
}
@ -272,7 +271,7 @@ GET my_index/_search
"script_fields": {
"parent": {
"script": {
"source": "doc['my_join_field#my_parent']" <3>
"source": "doc['my_join_field#question']" <3>
}
}
}
@ -315,7 +314,7 @@ PUT my_index
"my_join_field": {
"type": "join",
"relations": {
"my_parent": "my_child"
"question": "answer"
},
"eager_global_ordinals": false
}
@ -332,10 +331,10 @@ as follows:
[source,sh]
--------------------------------------------------
# Per-index
GET _stats/fielddata?human&fields=my_join_field#my_parent
GET _stats/fielddata?human&fields=my_join_field#question
# Per-node per-index
GET _nodes/stats/indices/fielddata?human&fields=my_join_field#my_parent
GET _nodes/stats/indices/fielddata?human&fields=my_join_field#question
--------------------------------------------------
// CONSOLE
// TEST[continued]
@ -354,7 +353,7 @@ PUT my_index
"my_join_field": {
"type": "join",
"relations": {
"my_parent": ["my_child", "another_child"] <1>
"question": ["answer", "comment"] <1>
}
}
}
@ -364,7 +363,7 @@ PUT my_index
--------------------------------------------------
// CONSOLE
<1> `my_parent` is parent of `my_child`.
<1> `question` is parent of `answer` and `comment`.
And multiple levels of parent/child:
@ -378,8 +377,8 @@ PUT my_index
"my_join_field": {
"type": "join",
"relations": {
"my_parent": ["my_child", "another_child"], <1>
"another_child": "grand_child" <2>
"question": ["answer", "comment"], <1>
"answer": "vote" <2>
}
}
}
@ -389,18 +388,18 @@ PUT my_index
--------------------------------------------------
// CONSOLE
<1> `my_parent` is parent of `my_child` and `another_child`
<2> `another_child` is parent of `grand_child`
<1> `question` is parent of `answer` and `comment`
<2> `answer` is parent of `vote`
The mapping above represents the following tree:
my_parent
question
/ \
/ \
my_child another_child
comment answer
|
|
grand_child
vote
Indexing a grand child document requires a `routing` value equals
to the grand-parent (the greater parent of the lineage):
@ -410,9 +409,9 @@ to the grand-parent (the greater parent of the lineage):
--------------------------------------------------
PUT my_index/doc/3?routing=1&refresh <1>
{
"text": "This is a grand child document",
"text": "This is a vote",
"my_join_field": {
"name": "grand_child",
"name": "vote",
"parent": "2" <2>
}
}
@ -421,6 +420,6 @@ PUT my_index/doc/3?routing=1&refresh <1>
// TEST[continued]
<1> This child document must be on the same shard than its grandparent and parent
<2> The parent id of this document (must points to an `another_child` document)
<2> The parent id of this document (must points to an `answer` document)