OpenSearch/docs/reference/query-dsl/has-child-query.asciidoc

[[query-dsl-has-child-query]]
=== Has child query
++++
<titleabbrev>Has child</titleabbrev>
++++

Returns parent documents whose <<parent-join,joined>> child documents match a
provided query. You can create parent-child relationships between documents in
the same index using a <<parent-join,join>> field mapping.

[WARNING]
====
Because it performs a join, the `has_child` is slow compared to other queries.
Its performance degrades as the number of matching child documents pointing to
unique parent documents increases. Each `has_child` query in a search can
increase query time significantly.

If you care about query performance, do not use this query. If you need to use
the `has_child` query, use it as rarely as possible. 
====

[[has-child-query-ex-request]]
==== Example request

[[has-child-index-setup]]
===== Index setup
To use the `has_child` query, your index must include a <<parent-join,join>>
field mapping. For example:

[source,js]
----
PUT /my_index
{
    "mappings": {
        "properties" : {
            "my-join-field" : {
                "type" : "join",
                "relations": {
                    "parent": "child"
                }
            }
        }
    }
}

----
// CONSOLE
// TESTSETUP

[[has-child-query-ex-query]]
===== Example query

[source,js]
----
GET /_search
{
    "query": {
        "has_child" : {
            "type" : "child",
            "query" : {
                "match_all" : {}
            },
            "max_children": 10,
            "min_children": 2,
            "score_mode" : "min"
        }
    }
}
----
// CONSOLE

[[has-child-top-level-params]]
==== Top-level parameters for `has_child`

`type`::
(Required, string) Name of the child relationship mapped for the
<<parent-join,join>> field.

`query`::
(Required, query object) Query you wish to run on child documents of the `type`
field. If a child document matches the search, the query returns the parent
document.

`ignore_unmapped`::
+
--
(Optional, boolean) Indicates whether to ignore an unmapped `type` and not
return any documents instead of an error. Defaults to `false`.

If `false`, {es} returns an error if the `type` is unmapped.

You can use this parameter to query multiple indices that may not contain the
`type`.
--

`max_children`::
(Optional, integer) Maximum number of child documents that match the `query`
allowed for a returned parent document. If the parent document exceeds this
limit, it is excluded from the search results.

`min_children`::
(Optional, integer) Minimum number of child documents that match the `query`
required to match the query for a returned parent document. If the parent
document does not meet this limit, it is excluded from the search results.

`score_mode`::
+
--
(Optional, string) Indicates how scores for matching child documents affect the
root parent document's <<relevance-scores,relevance score>>. Valid values
are:

`none` (Default)::
Do not use the relevance scores of matching child documents. The query assigns
parent documents a score of `0`.

`avg`::
Use the mean relevance score of all matching child documents.

`max`::
Uses the highest relevance score of all matching child documents.

`min`::
Uses the lowest relevance score of all matching child documents.

`sum`::
Add together the relevance scores of all matching child documents.
--

[[has-child-query-notes]]
==== Notes

[[has-child-query-performance]]
===== Sorting
You cannot sort the results of a `has_child` query using standard
<<request-body-search-sort,sort options>>.

If you need to sort returned documents by a field in their child documents, use
a `function_score` query and sort by `_score`. For example, the following query
sorts returned documents by the `click_count` field of their child documents.

[source,js]
----
GET /_search
{
    "query": {
        "has_child" : {
            "type" : "child",
            "query" : {
                "function_score" : {
                    "script_score": {
                        "script": "_score * doc['click_count'].value"
                    }
                }
            },
            "score_mode" : "max"
        }
    }
}
----
// CONSOLE