OpenSearch/docs/reference/aggregations/bucket/children-aggregation.asciidoc

[[search-aggregations-bucket-children-aggregation]]
=== Children Aggregation

A special single bucket aggregation that enables aggregating from buckets on parent document types to buckets on child documents.

This aggregation relies on the <<mapping-parent-field,_parent field>> in the mapping. This aggregation has a single option:

* `type` - The child type that the buckets in the parent space should be mapped to.

For example, let's say we have an index of questions and answers. The answer type has the following `_parent` field in the mapping:
[source,js]
--------------------------------------------------
PUT child_example
{
    "mappings": {
        "answer" : {
            "_parent" : {
                "type" : "question"
            }
        }
    }
}
--------------------------------------------------
// CONSOLE

The question typed document contain a tag field and the answer typed documents contain an owner field. With the `children`
aggregation the tag buckets can be mapped to the owner buckets in a single request even though the two fields exist in
two different kinds of documents.

An example of a question typed document:
[source,js]
--------------------------------------------------
PUT child_example/question/1
{
    "body": "<p>I have Windows 2003 server and i bought a new Windows 2008 server...",
    "title": "Whats the best way to file transfer my site from server to a newer one?",
    "tags": [
        "windows-server-2003",
        "windows-server-2008",
        "file-transfer"
    ]
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

Examples of `answer` typed documents:
[source,js]
--------------------------------------------------
PUT child_example/answer/1?parent=1&refresh
{
    "owner": {
        "location": "Norfolk, United Kingdom",
        "display_name": "Sam",
        "id": 48
    },
    "body": "<p>Unfortunately you're pretty much limited to FTP...",
    "creation_date": "2009-05-04T13:45:37.030"
}
PUT child_example/answer/2?parent=1&refresh
{
    "owner": {
        "location": "Norfolk, United Kingdom",
        "display_name": "Troll",
        "id": 49
    },
    "body": "<p>Use Linux...",
    "creation_date": "2009-05-05T13:45:37.030"
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

The following request can be built that connects the two together:

[source,js]
--------------------------------------------------
POST child_example/_search?size=0
{
  "aggs": {
    "top-tags": {
      "terms": {
        "field": "tags.keyword",
        "size": 10
      },
      "aggs": {
        "to-answers": {
          "children": {
            "type" : "answer" <1>
          },
          "aggs": {
            "top-names": {
              "terms": {
                "field": "owner.display_name.keyword",
                "size": 10
              }
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

<1> The `type` points to type / mapping with the name `answer`.

The above example returns the top question tags and per tag the top answer owners.

Possible response:

[source,js]
--------------------------------------------------
{
  "timed_out": false,
  "took": 25,
  "_shards": { "total": 5, "successful": 5, "failed": 0 },
  "hits": { "total": 3, "max_score": 0.0, hits: [] },
  "aggregations": {
    "top-tags": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "file-transfer",
          "doc_count": 1, <1>
          "to-answers": {
            "doc_count": 2, <2>
            "top-names": {
              "doc_count_error_upper_bound": 0,
              "sum_other_doc_count": 0,
              "buckets": [
                {
                  "key": "Sam",
                  "doc_count": 1
                },
                {
                  "key": "Troll",
                  "doc_count": 1
                }
              ]
            }
          }
        },
        {
          "key": "windows-server-2003",
          "doc_count": 1, <1>
          "to-answers": {
            "doc_count": 2, <2>
            "top-names": {
              "doc_count_error_upper_bound": 0,
              "sum_other_doc_count": 0,
              "buckets": [
                {
                  "key": "Sam",
                  "doc_count": 1
                },
                {
                  "key": "Troll",
                  "doc_count": 1
                }
              ]
            }
          }
        },
        {
          "key": "windows-server-2008",
          "doc_count": 1, <1>
          "to-answers": {
            "doc_count": 2, <2>
            "top-names": {
              "doc_count_error_upper_bound": 0,
              "sum_other_doc_count": 0,
              "buckets": [
                {
                  "key": "Sam",
                  "doc_count": 1
                },
                {
                  "key": "Troll",
                  "doc_count": 1
                }
              ]
            }
          }
        }
      ]
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 25/"took": $body.took/]

<1> The number of question documents with the tag `file-transfer`, `windows-server-2003`, etc.
<2> The number of answer documents that are related to question documents with the tag `file-transfer`, `windows-server-2003`, etc.