Children Aggregation

A special single bucket aggregation that selects child documents that have the specified type, as defined in a join field.

This aggregation has a single option:

  • type - The child type that should be selected.

For example, let’s say we have an index of questions and answers. The answer type has the following join field in the mapping:

  1. PUT child_example
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "join": {
  6.         "type": "join",
  7.         "relations": {
  8.           "question": "answer"
  9.         }
  10.       }
  11.     }
  12.   }
  13. }

The question document contain a tag field and the answer 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 document:

  1. PUT child_example/_doc/1
  2. {
  3.   "join": {
  4.     "name": "question"
  5.   },
  6.   "body": "<p>I have Windows 2003 server and i bought a new Windows 2008 server...",
  7.   "title": "Whats the best way to file transfer my site from server to a newer one?",
  8.   "tags": [
  9.     "windows-server-2003",
  10.     "windows-server-2008",
  11.     "file-transfer"
  12.   ]
  13. }

Examples of answer documents:

  1. PUT child_example/_doc/2?routing=1
  2. {
  3.   "join": {
  4.     "name": "answer",
  5.     "parent": "1"
  6.   },
  7.   "owner": {
  8.     "location": "Norfolk, United Kingdom",
  9.     "display_name": "Sam",
  10.     "id": 48
  11.   },
  12.   "body": "<p>Unfortunately you're pretty much limited to FTP...",
  13.   "creation_date": "2009-05-04T13:45:37.030"
  14. }
  16. PUT child_example/_doc/3?routing=1&refresh
  17. {
  18.   "join": {
  19.     "name": "answer",
  20.     "parent": "1"
  21.   },
  22.   "owner": {
  23.     "location": "Norfolk, United Kingdom",
  24.     "display_name": "Troll",
  25.     "id": 49
  26.   },
  27.   "body": "<p>Use Linux...",
  28.   "creation_date": "2009-05-05T13:45:37.030"
  29. }

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

  1. POST child_example/_search?size=0
  2. {
  3.   "aggs": {
  4.     "top-tags": {
  5.       "terms": {
  6.         "field": "tags.keyword",
  7.         "size": 10
  8.       },
  9.       "aggs": {
  10.         "to-answers": {
  11.           "children": {
  12.             "type" : "answer" 
  13.           },
  14.           "aggs": {
  15.             "top-names": {
  16.               "terms": {
  17.                 "field": "owner.display_name.keyword",
  18.                 "size": 10
  19.               }
  20.             }
  21.           }
  22.         }
  23.       }
  24.     }
  25.   }
  26. }

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:

  1. {
  2.   "took": 25,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped" : 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total" : {
  12.       "value": 3,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": null,
  16.     "hits": []
  17.   },
  18.   "aggregations": {
  19.     "top-tags": {
  20.       "doc_count_error_upper_bound": 0,
  21.       "sum_other_doc_count": 0,
  22.       "buckets": [
  23.         {
  24.           "key": "file-transfer",
  25.           "doc_count": 1, 
  26.           "to-answers": {
  27.             "doc_count": 2, 
  28.             "top-names": {
  29.               "doc_count_error_upper_bound": 0,
  30.               "sum_other_doc_count": 0,
  31.               "buckets": [
  32.                 {
  33.                   "key": "Sam",
  34.                   "doc_count": 1
  35.                 },
  36.                 {
  37.                   "key": "Troll",
  38.                   "doc_count": 1
  39.                 }
  40.               ]
  41.             }
  42.           }
  43.         },
  44.         {
  45.           "key": "windows-server-2003",
  46.           "doc_count": 1, 
  47.           "to-answers": {
  48.             "doc_count": 2, 
  49.             "top-names": {
  50.               "doc_count_error_upper_bound": 0,
  51.               "sum_other_doc_count": 0,
  52.               "buckets": [
  53.                 {
  54.                   "key": "Sam",
  55.                   "doc_count": 1
  56.                 },
  57.                 {
  58.                   "key": "Troll",
  59.                   "doc_count": 1
  60.                 }
  61.               ]
  62.             }
  63.           }
  64.         },
  65.         {
  66.           "key": "windows-server-2008",
  67.           "doc_count": 1, 
  68.           "to-answers": {
  69.             "doc_count": 2, 
  70.             "top-names": {
  71.               "doc_count_error_upper_bound": 0,
  72.               "sum_other_doc_count": 0,
  73.               "buckets": [
  74.                 {
  75.                   "key": "Sam",
  76.                   "doc_count": 1
  77.                 },
  78.                 {
  79.                   "key": "Troll",
  80.                   "doc_count": 1
  81.                 }
  82.               ]
  83.             }
  84.           }
  85.         }
  86.       ]
  87.     }
  88.   }
  89. }

The number of question documents with the tag file-transfer, windows-server-2003, etc.

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