<commit_before>[[parent-join]]
=== `join` datatype

The `join` datatype is a special field that creates
parent/child relation within documents of the same index.
The `relations` section defines a set of possible relations within the documents,
each relation being a parent name and a child name.
A parent/child relation can be defined as follows:

[source,js]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "doc": {
      "properties": {
        "my_join_field": { <1>
          "type": "join",
          "relations": {
            "question": "answer" <2>
          }
        }
      }
    }
  }
}
--------------------------------------------------
// CONSOLE

<1> The name for the field
<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 `question` context:

[source,js]
--------------------------------------------------
PUT my_index/doc/1?refresh
{
  "text": "This is a question",
  "my_join_field": {
    "name": "question" <1>
  }
}

PUT my_index/doc/2?refresh
{
  "text": "This is a another question",
  "my_join_field": {
    "name": "question"
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<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:

[source,js]
--------------------------------------------------
PUT my_index/doc/1?refresh
{
  "text": "This is a question",
  "my_join_field": "question" <1>
}

PUT my_index/doc/2?refresh
{
  "text": "This is another question",
  "my_join_field": "question"
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<1> Simpler notation for a parent document just uses the relation name.

When indexing a child, the name of the relation as well as the parent id of the document
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:

[source,js]
--------------------------------------------------
PUT my_index/doc/3?routing=1&refresh <1>
{
  "text": "This is an answer",
  "my_join_field": {
    "name": "answer", <2>
    "parent": "1" <3>
  }
}

PUT my_index/doc/4?routing=1&refresh
{
  "text": "This is another answer",
  "my_join_field": {
    "name": "answer",
    "parent": "1"
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<1> This child document must be on the same shard than its parent
<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 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>>
  a child document.
* An element can have multiple children but only one parent.
* It is possible to add a new relation to an existing `join` field.
* It is also possible to add a child to an existing element
  but only if the element is already a parent.

==== Searching with parent-join

The parent-join creates one field to index the name of the relation
within the document (`my_parent`, `my_child`, ...).

It also creates one field per parent/child relation.<commit_msg>Fix incomplete sentences in parent-join docs (#26623)<commit_after>[[parent-join]]
=== `join` datatype

The `join` datatype is a special field that creates
parent/child relation within documents of the same index.
The `relations` section defines a set of possible relations within the documents,
each relation being a parent name and a child name.
A parent/child relation can be defined as follows:

[source,js]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "doc": {
      "properties": {
        "my_join_field": { <1>
          "type": "join",
          "relations": {
            "question": "answer" <2>
          }
        }
      }
    }
  }
}
--------------------------------------------------
// CONSOLE

<1> The name for the field
<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 example creates two `parent` documents in the `question` context:

[source,js]
--------------------------------------------------
PUT my_index/doc/1?refresh
{
  "text": "This is a question",
  "my_join_field": {
    "name": "question" <1>
  }
}

PUT my_index/doc/2?refresh
{
  "text": "This is a another question",
  "my_join_field": {
    "name": "question"
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<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:

[source,js]
--------------------------------------------------
PUT my_index/doc/1?refresh
{
  "text": "This is a question",
  "my_join_field": "question" <1>
}

PUT my_index/doc/2?refresh
{
  "text": "This is another question",
  "my_join_field": "question"
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<1> Simpler notation for a parent document just uses the relation name.

When indexing a child, the name of the relation as well as the parent id of the document
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 example shows how to index two `child` documents:

[source,js]
--------------------------------------------------
PUT my_index/doc/3?routing=1&refresh <1>
{
  "text": "This is an answer",
  "my_join_field": {
    "name": "answer", <2>
    "parent": "1" <3>
  }
}

PUT my_index/doc/4?routing=1&refresh
{
  "text": "This is another answer",
  "my_join_field": {
    "name": "answer",
    "parent": "1"
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<1> The routing value is mandatory because parent and child documents must be indexed on the same shard
<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 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>>
  a child document.
* An element can have multiple children but only one parent.
* It is possible to add a new relation to an existing `join` field.
* It is also possible to add a child to an existing element
  but only if the element is already a parent.

==== Searching with parent-join

The parent-join creates one field to index the name of the relation
within the document (`my_parent`, `my_child`, ...).

It also creates one field per parent/child relation.
{'fraction_non_alphanumeric': 0.19638175144205558, 'fraction_numerical': 0.007079181961195595, 'mean_word_length': 2.3416557161629434, 'pattern_counts': {'":': 50, '<': 43, '<?xml version=': 0, '>': 43, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '669184', 'n_tokens_mistral': 2117, 'n_tokens_neox': 2086, 'n_words': 924}