Has child query

The has_child query returns parent documents whose child documents match a specific query. You can establish parent/child relationships between documents in the same index by using a join field type.

The has_child query is slower than other queries because of the join operation it performs. Performance decreases as the number of matching child documents pointing to different parent documents increases. Each has_child query in your search may significantly impact query performance. If you prioritize speed, avoid using this query or limit its usage as much as possible.

Example

Before you can run a has_child query, your index must contain a join field in order to establish parent/child relationships. The index mapping request uses the following format:

  1. PUT /example_index
  2. {
  3. "mappings": {
  4. "properties": {
  5. "relationship_field": {
  6. "type": "join",
  7. "relations": {
  8. "parent_doc": "child_doc"
  9. }
  10. }
  11. }
  12. }
  13. }

copy

In this example, you’ll configure an index that contains documents representing products and their brands.

First, create the index and establish the parent/child relationship between brand and product:

  1. PUT testindex1
  2. {
  3. "mappings": {
  4. "properties": {
  5. "product_to_brand": {
  6. "type": "join",
  7. "relations": {
  8. "brand": "product"
  9. }
  10. }
  11. }
  12. }
  13. }

copy

Index two parent (brand) documents:

  1. PUT testindex1/_doc/1
  2. {
  3. "name": "Luxury brand",
  4. "product_to_brand" : "brand"
  5. }

copy

  1. PUT testindex1/_doc/2
  2. {
  3. "name": "Economy brand",
  4. "product_to_brand" : "brand"
  5. }

copy

Index three child (product) documents:

  1. PUT testindex1/_doc/3?routing=1
  2. {
  3. "name": "Mechanical watch",
  4. "sales_count": 150,
  5. "product_to_brand": {
  6. "name": "product",
  7. "parent": "1"
  8. }
  9. }

copy

  1. PUT testindex1/_doc/4?routing=2
  2. {
  3. "name": "Electronic watch",
  4. "sales_count": 300,
  5. "product_to_brand": {
  6. "name": "product",
  7. "parent": "2"
  8. }
  9. }

copy

  1. PUT testindex1/_doc/5?routing=2
  2. {
  3. "name": "Digital watch",
  4. "sales_count": 100,
  5. "product_to_brand": {
  6. "name": "product",
  7. "parent": "2"
  8. }
  9. }

copy

To search for the parent of a child, use a has_child query. The following query returns parent documents (brands) that make watches:

  1. GET testindex1/_search
  2. {
  3. "query" : {
  4. "has_child": {
  5. "type":"product",
  6. "query": {
  7. "match" : {
  8. "name": "watch"
  9. }
  10. }
  11. }
  12. }
  13. }

copy

The response returns both brands:

  1. {
  2. "took": 15,
  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": 2,
  13. "relation": "eq"
  14. },
  15. "max_score": 1,
  16. "hits": [
  17. {
  18. "_index": "testindex1",
  19. "_id": "1",
  20. "_score": 1,
  21. "_source": {
  22. "name": "Luxury brand",
  23. "product_to_brand": "brand"
  24. }
  25. },
  26. {
  27. "_index": "testindex1",
  28. "_id": "2",
  29. "_score": 1,
  30. "_source": {
  31. "name": "Economy brand",
  32. "product_to_brand": "brand"
  33. }
  34. }
  35. ]
  36. }
  37. }

Retrieving inner hits

To return child documents that matched the query, provide the inner_hits parameter:

  1. GET testindex1/_search
  2. {
  3. "query" : {
  4. "has_child": {
  5. "type":"product",
  6. "query": {
  7. "match" : {
  8. "name": "watch"
  9. }
  10. },
  11. "inner_hits": {}
  12. }
  13. }
  14. }

copy

The response contains child documents in the inner_hits field:

  1. {
  2. "took": 52,
  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": 2,
  13. "relation": "eq"
  14. },
  15. "max_score": 1,
  16. "hits": [
  17. {
  18. "_index": "testindex1",
  19. "_id": "1",
  20. "_score": 1,
  21. "_source": {
  22. "name": "Luxury brand",
  23. "product_to_brand": "brand"
  24. },
  25. "inner_hits": {
  26. "product": {
  27. "hits": {
  28. "total": {
  29. "value": 1,
  30. "relation": "eq"
  31. },
  32. "max_score": 0.53899646,
  33. "hits": [
  34. {
  35. "_index": "testindex1",
  36. "_id": "3",
  37. "_score": 0.53899646,
  38. "_routing": "1",
  39. "_source": {
  40. "name": "Mechanical watch",
  41. "sales_count": 150,
  42. "product_to_brand": {
  43. "name": "product",
  44. "parent": "1"
  45. }
  46. }
  47. }
  48. ]
  49. }
  50. }
  51. }
  52. },
  53. {
  54. "_index": "testindex1",
  55. "_id": "2",
  56. "_score": 1,
  57. "_source": {
  58. "name": "Economy brand",
  59. "product_to_brand": "brand"
  60. },
  61. "inner_hits": {
  62. "product": {
  63. "hits": {
  64. "total": {
  65. "value": 2,
  66. "relation": "eq"
  67. },
  68. "max_score": 0.53899646,
  69. "hits": [
  70. {
  71. "_index": "testindex1",
  72. "_id": "4",
  73. "_score": 0.53899646,
  74. "_routing": "2",
  75. "_source": {
  76. "name": "Electronic watch",
  77. "sales_count": 300,
  78. "product_to_brand": {
  79. "name": "product",
  80. "parent": "2"
  81. }
  82. }
  83. },
  84. {
  85. "_index": "testindex1",
  86. "_id": "5",
  87. "_score": 0.53899646,
  88. "_routing": "2",
  89. "_source": {
  90. "name": "Digital watch",
  91. "sales_count": 100,
  92. "product_to_brand": {
  93. "name": "product",
  94. "parent": "2"
  95. }
  96. }
  97. }
  98. ]
  99. }
  100. }
  101. }
  102. }
  103. ]
  104. }
  105. }

For more information about retrieving inner hits, see Inner hits.

Parameters

The following table lists all top-level parameters supported by has_child queries.

ParameterRequired/OptionalDescription
typeRequiredSpecifies the name of the child relationship as defined in the join field mapping.
queryRequiredThe query to run on child documents. If a child document matches the query, the parent document is returned.
ignore_unmappedOptionalIndicates whether to ignore unmapped type fields and not return documents instead of throwing an error. You can provide this parameter when querying multiple indexes, some of which may not contain the type field. Default is false.
max_childrenOptionalThe maximum number of matching child documents for a parent document. If exceeded, the parent document is excluded from the search results.
min_childrenOptionalThe minimum number of matching child documents required for a parent document to be included in the results. If not met, the parent is excluded. Default is 1.
score_modeOptionalDefines how scores of matching child documents influence the parent document’s score. Valid values are:
- none: Ignores the relevance scores of child documents and assigns a score of 0 to the parent document.
- avg: Uses the average relevance score of all matching child documents.
- max: Assigns the highest relevance score from the matching child documents to the parent.
- min: Assigns the lowest relevance score from the matching child documents to the parent.
- sum: Sums the relevance scores of all matching child documents.
Default is none.
inner_hitsOptionalIf provided, returns the underlying hits (child documents) that matched the query.

Sorting limitations

The has_child query does not support sorting results using standard sorting options. If you need to sort parent documents by fields in their child documents, you can use a function_score query and sort by the parent document’s score.

In the preceding example, you can sort parent documents (brands) based on the sales_count of their child products. This query multiplies the score by the sales_count field of the child documents and assigns the highest relevance score from the matching child documents to the parent:

  1. GET testindex1/_search
  2. {
  3. "query": {
  4. "has_child": {
  5. "type": "product",
  6. "query": {
  7. "function_score": {
  8. "script_score": {
  9. "script": "_score * doc['sales_count'].value"
  10. }
  11. }
  12. },
  13. "score_mode": "max"
  14. }
  15. }
  16. }

copy

The response contains the brands sorted by the highest child sales_count:

  1. {
  2. "took": 6,
  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": 2,
  13. "relation": "eq"
  14. },
  15. "max_score": 300,
  16. "hits": [
  17. {
  18. "_index": "testindex1",
  19. "_id": "2",
  20. "_score": 300,
  21. "_source": {
  22. "name": "Economy brand",
  23. "product_to_brand": "brand"
  24. }
  25. },
  26. {
  27. "_index": "testindex1",
  28. "_id": "1",
  29. "_score": 150,
  30. "_source": {
  31. "name": "Luxury brand",
  32. "product_to_brand": "brand"
  33. }
  34. }
  35. ]
  36. }
  37. }

Next steps