Skip to content

Commit a088fcf

Browse files
jimczijimczi
committed
explain the single parent/child relation first and moves the multiple levels relations to the end of the docs. Add links in the main types page
1 parent 2bce296 commit a088fcf

File tree

2 files changed

+131
-93
lines changed

2 files changed

+131
-93
lines changed

‎docs/reference/mapping/types.asciidoc‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ string:: <<text,`text`>> and <<keyword,`keyword`>>
3838

3939
<<percolator>>:: Accepts queries from the query-dsl
4040

41+
<<parent-join>>:: Defines parent/child relation for documents within the same index
42+
4143
[float]
4244
=== Multi-fields
4345

@@ -84,7 +86,7 @@ include::types/token-count.asciidoc[]
8486

8587
include::types/percolator.asciidoc[]
8688

87-
89+
include::types/parent-join.asciidoc[]
8890

8991

9092

‎docs/reference/mapping/types/parent-join.asciidoc‎

Lines changed: 128 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ The `join` datatype is a special field that creates
55
parent/child relation within documents of the same index.
66
This field defines a set of possible relations within the documents,
77
each relation being a parent name and a child name.
8-
A single parent/child relation can be defined as follow:
8+
A parent/child relation can be defined as follow:
99

1010
[source,js]
1111
--------------------------------------------------
@@ -26,56 +26,11 @@ PUT my_index
2626
// CONSOLE
2727

2828
<1> The name for the field
29-
<2> `my_parent` is parent of `my_child`.
29+
<2> Defines a single relation where `my_parent` is parent of `my_child`.
3030

31-
It is also possible to define multiple children for a single parent:
32-
33-
[source,js]
34-
--------------------------------------------------
35-
PUT my_index
36-
{
37-
"mappings": {
38-
"doc": {
39-
"properties": {
40-
"my_join_field": {
41-
"type": "join",
42-
"my_parent": ["my_child", "another_child"] <1>
43-
}
44-
}
45-
}
46-
}
47-
}
48-
--------------------------------------------------
49-
// CONSOLE
50-
51-
<1> `my_parent` is parent of `my_child`.
52-
53-
... and multiple levels of parent/child:
54-
55-
[source,js]
56-
--------------------------------------------------
57-
PUT my_index
58-
{
59-
"mappings": {
60-
"doc": {
61-
"properties": {
62-
"my_join_field": {
63-
"type": "join",
64-
"my_parent": ["my_child", "another_child"], <1>
65-
"another_child": "grand_child" <2>
66-
}
67-
}
68-
}
69-
}
70-
}
71-
--------------------------------------------------
72-
// CONSOLE
73-
74-
<1> `my_parent` is parent of `my_child` and `another_child`
75-
<2> `another_child` is parent of `grand_child
76-
77-
To index a parent `my_parent` document the name of the relation
78-
must be added to the `_source`:
31+
To index a document with a join, the name of the relation and the optional parent
32+
of the document must be provided in the `source`.
33+
For instance the following creates a parent document in the `my_parent` context:
7934

8035
[source,js]
8136
--------------------------------------------------
@@ -84,6 +39,12 @@ PUT my_index/doc/1?refresh
8439
"text": "This is a parent document",
8540
"my_join_field": "my_parent" <1>
8641
}
42+
43+
PUT my_index/doc/2?refresh
44+
{
45+
"text": "This is a another parent document",
46+
"my_join_field": "my_parent"
47+
}
8748
--------------------------------------------------
8849
// CONSOLE
8950
// TEST[continued]
@@ -92,52 +53,39 @@ PUT my_index/doc/1?refresh
9253

9354
When indexing a child, the name of the relation as well as the parent id of the document
9455
must be added in the `_source`.
95-
96-
9756
It is required to index the lineage of a parent in the same shard so you must
9857
always route child documents using their greater parent id.
99-
For instance the following index a child document with a `routing` value
100-
equals to the `id` of the parent:
58+
For instance the following index two children documents pointing to the same parent
59+
with a `routing` value equals to the `id` of the parent:
10160

10261
[source,js]
10362
--------------------------------------------------
104-
PUT my_index/doc/2?routing=1&refresh <1>
63+
PUT my_index/doc/3?routing=1&refresh <1>
10564
{
10665
"text": "This is a child document",
10766
"my_join_field": {
10867
"name": "my_child", <2>
10968
"parent": "1" <3>
11069
}
11170
}
112-
--------------------------------------------------
113-
// CONSOLE
114-
// TEST[continued]
115-
116-
<1> This child document must be on the same shard than its parent
117-
<2> This is `my_child` document
118-
<3> The parent id of this child document
11971
120-
Similarly indexing a great child document requires a `routing` value equals
121-
to the grand-parent (the greater parent of the lineage):
122-
123-
[source,js]
124-
--------------------------------------------------
125-
PUT my_index/doc/3?routing=1&refresh <1>
72+
PUT my_index/doc/4?routing=1&refresh <1>
12673
{
127-
"text": "This is a grand child document",
74+
"text": "This is a another child document",
12875
"my_join_field": {
129-
"name": "grand_child",
130-
"parent": "2" <2>
76+
"name": "my_child",
77+
"parent": "1"
13178
}
13279
}
13380
--------------------------------------------------
13481
// CONSOLE
13582
// TEST[continued]
13683

137-
<1> This child document must be on the same shard than its grandparent and parent
138-
<2> The parent id of this document (must points to an `another_child` document)
84+
<1> This child document must be on the same shard than its parent
85+
<2> `my_child` is the name of the join for this document
86+
<3> The parent id of this child document
13987

140-
==== Parent-child restrictions
88+
==== Parent-join restrictions
14189

14290
* Only one `join` field is allowed per index mapping.
14391
* An element can have multiple children but only one parent.
@@ -181,7 +129,7 @@ GET my_index/_search
181129
{
182130
...,
183131
"hits": {
184-
"total": 3,
132+
"total": 4,
185133
"max_score": null,
186134
"hits": [
187135
{
@@ -195,7 +143,7 @@ GET my_index/_search
195143
},
196144
"fields": {
197145
"my_join_field": [
198-
"my_parent" <1>
146+
"my_parent"
199147
]
200148
},
201149
"sort": [
@@ -207,6 +155,24 @@ GET my_index/_search
207155
"_type": "doc",
208156
"_id": "2",
209157
"_score": null,
158+
"_source": {
159+
"text": "This is a another parent document",
160+
"my_join_field": "my_parent"
161+
},
162+
"fields": {
163+
"my_join_field": [
164+
"my_parent"
165+
]
166+
},
167+
"sort": [
168+
"2"
169+
]
170+
},
171+
{
172+
"_index": "my_index",
173+
"_type": "doc",
174+
"_id": "3",
175+
"_score": null,
210176
"_routing": "1",
211177
"_source": {
212178
"text": "This is a child document",
@@ -217,39 +183,39 @@ GET my_index/_search
217183
},
218184
"fields": {
219185
"my_join_field": [
220-
"my_child" <2>
186+
"my_child"
221187
],
222188
"my_join_field#my_parent": [
223-
"1" <3>
189+
"1"
224190
]
225191
},
226192
"sort": [
227-
"2"
193+
"3"
228194
]
229195
},
230196
{
231197
"_index": "my_index",
232198
"_type": "doc",
233-
"_id": "3",
199+
"_id": "4",
234200
"_score": null,
235201
"_routing": "1",
236202
"_source": {
237-
"text": "This is a grand child document",
203+
"text": "This is a another child document",
238204
"my_join_field": {
239-
"name": "grand_child",
240-
"parent": "2"
205+
"name": "my_child",
206+
"parent": "1"
241207
}
242208
},
243209
"fields": {
244210
"my_join_field": [
245-
"grand_child" <4>
211+
"my_child"
246212
],
247-
"my_join_field#another_child": [
248-
"2" <5>
213+
"my_join_field#my_parent": [
214+
"1"
249215
]
250216
},
251217
"sort": [
252-
"3"
218+
"4"
253219
]
254220
}
255221
]
@@ -258,11 +224,10 @@ GET my_index/_search
258224
--------------------------------------------------
259225
// TESTRESPONSE[s/\.\.\./"timed_out": false, "took": $body.took, "_shards": $body._shards/]
260226

261-
<1> This is a parent document in the `my_parent` context
262-
<2> This is child document in the `my_child` context
263-
<3> The linked parent id for the child document
264-
<4> This is child document in the `grand_child` context
265-
<5> The linked parent id for the child document
227+
<1> This document belongs to the `my_parent` join
228+
<2> This document belongs to the `my_parent` join
229+
<3> This document belongs to the `my_child` join
230+
<4> The linked parent id for the child document
266231

267232
==== Parent-join queries and aggregations
268233

@@ -361,3 +326,74 @@ GET _nodes/stats/indices/fielddata?human&fields=my_join_field#my_parent
361326
--------------------------------------------------
362327
// CONSOLE
363328
// TEST[continued]
329+
330+
==== Multiple levels of parent join
331+
332+
It is also possible to define multiple children for a single parent:
333+
334+
[source,js]
335+
--------------------------------------------------
336+
PUT my_index
337+
{
338+
"mappings": {
339+
"doc": {
340+
"properties": {
341+
"my_join_field": {
342+
"type": "join",
343+
"my_parent": ["my_child", "another_child"] <1>
344+
}
345+
}
346+
}
347+
}
348+
}
349+
--------------------------------------------------
350+
// CONSOLE
351+
352+
<1> `my_parent` is parent of `my_child`.
353+
354+
... and multiple levels of parent/child:
355+
356+
[source,js]
357+
--------------------------------------------------
358+
PUT my_index
359+
{
360+
"mappings": {
361+
"doc": {
362+
"properties": {
363+
"my_join_field": {
364+
"type": "join",
365+
"my_parent": ["my_child", "another_child"], <1>
366+
"another_child": "grand_child" <2>
367+
}
368+
}
369+
}
370+
}
371+
}
372+
--------------------------------------------------
373+
// CONSOLE
374+
375+
<1> `my_parent` is parent of `my_child` and `another_child`
376+
<2> `another_child` is parent of `grand_child
377+
378+
Indexing a great child document requires a `routing` value equals
379+
to the grand-parent (the greater parent of the lineage):
380+
381+
382+
[source,js]
383+
--------------------------------------------------
384+
PUT my_index/doc/3?routing=1&refresh <1>
385+
{
386+
"text": "This is a grand child document",
387+
"my_join_field": {
388+
"name": "grand_child",
389+
"parent": "2" <2>
390+
}
391+
}
392+
--------------------------------------------------
393+
// CONSOLE
394+
// TEST[continued]
395+
396+
<1> This child document must be on the same shard than its grandparent and parent
397+
<2> The parent id of this document (must points to an `another_child` document)
398+
399+

0 commit comments

Comments
 (0)