honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
docs/reference/mapping/types/parent-join.asciidoc
View File

@ -17,7 +17,7 @@ PUT my_index
"my_join_field": { <1> "my_join_field": { <1>
"type": "join", "type": "join",
"relations": { "relations": {
"my_parent": "my_child" <2> "question": "answer" <2>
} }
} }
} }
@ -28,34 +28,34 @@ PUT my_index
// CONSOLE // CONSOLE
<1> The name for the field <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 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`. 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] [source,js]
-------------------------------------------------- --------------------------------------------------
PUT my_index/doc/1?refresh PUT my_index/doc/1?refresh
{ {
"text": "This is a parent document", "text": "This is a question",
"my_join_field": { "my_join_field": {
"name": "my_parent" <1> "name": "question" <1>
} }
} }
PUT my_index/doc/2?refresh PUT my_index/doc/2?refresh
{ {
"text": "This is a another parent document", "text": "This is a another question",
"my_join_field": { "my_join_field": {
"name": "my_parent" "name": "question"
} }
} }
-------------------------------------------------- --------------------------------------------------
// CONSOLE // CONSOLE
// TEST[continued] // 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 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: 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 PUT my_index/doc/1?refresh
{ {
"text": "This is a parent document", "text": "This is a question",
"my_join_field": "my_parent" <1> "my_join_field": "question" <1>
} }
PUT my_index/doc/2?refresh PUT my_index/doc/2?refresh
{ {
"text": "This is a another parent document", "text": "This is another question",
"my_join_field": "my_parent" "my_join_field": "question"
} }
-------------------------------------------------- --------------------------------------------------
// CONSOLE // 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 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. always route child documents using their greater parent id.
For instance the following index two children documents pointing to the same parent `1` 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: 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> PUT my_index/doc/3?routing=1&refresh <1>
{ {
"text": "This is a child document", "text": "This is an answer",
"my_join_field": { "my_join_field": {
"name": "my_child", <2> "name": "answer", <2>
"parent": "1" <3> "parent": "1" <3>
} }
} }
PUT my_index/doc/4?routing=1&refresh PUT my_index/doc/4?routing=1&refresh
{ {
"text": "This is a another child document", "text": "This is another answer",
"my_join_field": { "my_join_field": {
"name": "my_child", "name": "answer",
"parent": "1" "parent": "1"
} }
} }
@ -113,12 +112,12 @@ PUT my_index/doc/4?routing=1&refresh
// TEST[continued] // TEST[continued]
<1> This child document must be on the same shard than its parent <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 <3> The parent id of this child document
==== Parent-join restrictions ==== 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. * Parent and child documents must be indexed on the same shard.
This means that the same `routing` value needs to be provided when This means that the same `routing` value needs to be provided when
<<docs-get,getting>>, <<docs-delete,deleting>>, or <<docs-update,updating>> <<docs-get,getting>>, <<docs-delete,deleting>>, or <<docs-update,updating>>
@ -175,8 +174,8 @@ Will return:
"_id": "1", "_id": "1",
"_score": null, "_score": null,
"_source": { "_source": {
"text": "This is a parent document", "text": "This is a question",
"my_join_field": "my_parent" <1> "my_join_field": "question" <1>
}, },
"sort": [ "sort": [
"1" "1"
@ -188,8 +187,8 @@ Will return:
"_id": "2", "_id": "2",
"_score": null, "_score": null,
"_source": { "_source": {
"text": "This is a another parent document", "text": "This is another question",
"my_join_field": "my_parent" <2> "my_join_field": "question" <2>
}, },
"sort": [ "sort": [
"2" "2"
@ -202,9 +201,9 @@ Will return:
"_score": null, "_score": null,
"_routing": "1", "_routing": "1",
"_source": { "_source": {
"text": "This is a child document", "text": "This is an answer",
"my_join_field": { "my_join_field": {
"name": "my_child", <3> "name": "answer", <3>
"parent": "1" <4> "parent": "1" <4>
} }
}, },
@ -219,9 +218,9 @@ Will return:
"_score": null, "_score": null,
"_routing": "1", "_routing": "1",
"_source": { "_source": {
"text": "This is a another child document", "text": "This is another answer",
"my_join_field": { "my_join_field": {
"name": "my_child", "name": "answer",
"parent": "1" "parent": "1"
} }
}, },
@ -235,9 +234,9 @@ Will return:
-------------------------------------------------- --------------------------------------------------
// TESTRESPONSE[s/\.\.\./"timed_out": false, "took": $body.took, "_shards": $body._shards/] // TESTRESPONSE[s/\.\.\./"timed_out": false, "took": $body.took, "_shards": $body._shards/]
<1> This document belongs to the `my_parent` join <1> This document belongs to the `question` join
<2> This document belongs to the `my_parent` join <2> This document belongs to the `question` join
<3> This document belongs to the `my_child` join <3> This document belongs to the `answer` join
<4> The linked parent id for the child document <4> The linked parent id for the child document
==== Parent-join queries and aggregations ==== Parent-join queries and aggregations
@ -257,14 +256,14 @@ GET my_index/_search
{ {
"query": { "query": {
"parent_id": { <1> "parent_id": { <1>
"type": "my_child", "type": "answer",
"id": "1" "id": "1"
} }
}, },
"aggs": { "aggs": {
"parents": { "parents": {
"terms": { "terms": {
"field": "my_join_field#my_parent", <2> "field": "my_join_field#question", <2>
"size": 10 "size": 10
} }
} }
@ -272,7 +271,7 @@ GET my_index/_search
"script_fields": { "script_fields": {
"parent": { "parent": {
"script": { "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": { "my_join_field": {
"type": "join", "type": "join",
"relations": { "relations": {
"my_parent": "my_child" "question": "answer"
}, },
"eager_global_ordinals": false "eager_global_ordinals": false
} }
@ -332,10 +331,10 @@ as follows:
[source,sh] [source,sh]
-------------------------------------------------- --------------------------------------------------
# Per-index # 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 # 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 // CONSOLE
// TEST[continued] // TEST[continued]
@ -354,7 +353,7 @@ PUT my_index
"my_join_field": { "my_join_field": {
"type": "join", "type": "join",
"relations": { "relations": {
"my_parent": ["my_child", "another_child"] <1> "question": ["answer", "comment"] <1>
} }
} }
} }
@ -364,7 +363,7 @@ PUT my_index
-------------------------------------------------- --------------------------------------------------
// CONSOLE // CONSOLE
<1> `my_parent` is parent of `my_child`. <1> `question` is parent of `answer` and `comment`.
And multiple levels of parent/child: And multiple levels of parent/child:
@ -378,8 +377,8 @@ PUT my_index
"my_join_field": { "my_join_field": {
"type": "join", "type": "join",
"relations": { "relations": {
"my_parent": ["my_child", "another_child"], <1> "question": ["answer", "comment"], <1>
"another_child": "grand_child" <2> "answer": "vote" <2>
} }
} }
} }
@ -389,18 +388,18 @@ PUT my_index
-------------------------------------------------- --------------------------------------------------
// CONSOLE // CONSOLE
<1> `my_parent` is parent of `my_child` and `another_child` <1> `question` is parent of `answer` and `comment`
<2> `another_child` is parent of `grand_child` <2> `answer` is parent of `vote`
The mapping above represents the following tree: 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 Indexing a grand child document requires a `routing` value equals
to the grand-parent (the greater parent of the lineage): 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> PUT my_index/doc/3?routing=1&refresh <1>
{ {
"text": "This is a grand child document", "text": "This is a vote",
"my_join_field": { "my_join_field": {
"name": "grand_child", "name": "vote",
"parent": "2" <2> "parent": "2" <2>
} }
} }
@ -421,6 +420,6 @@ PUT my_index/doc/3?routing=1&refresh <1>
// TEST[continued] // TEST[continued]
<1> This child document must be on the same shard than its grandparent and parent <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)