OpenSearch/docs/reference/query-dsl/nested-query.asciidoc

[[query-dsl-nested-query]]
=== Nested query
++++
<titleabbrev>Nested</titleabbrev>
++++

Wraps another query to search <<nested,nested>> fields.

The `nested` query searches nested field objects as if they were indexed as
separate documents. If an object matches the search, the `nested` query returns
the root parent document.

[[nested-query-ex-request]]
==== Example request

[[nested-query-index-setup]]
===== Index setup

To use the `nested` query, your index must include a <<nested,nested>> field
mapping. For example:

[source,js]
----
PUT /my_index
{
    "mappings": {
        "properties" : {
            "obj1" : {
                "type" : "nested"
            }
        }
    }
}

----
// CONSOLE
// TESTSETUP

[[nested-query-ex-query]]
===== Example query

[source,js]
----
GET /my_index/_search
{
    "query": {
        "nested" : {
            "path" : "obj1",
            "query" : {
                "bool" : {
                    "must" : [
                    { "match" : {"obj1.name" : "blue"} },
                    { "range" : {"obj1.count" : {"gt" : 5}} }
                    ]
                }
            },
            "score_mode" : "avg"
        }
    }
}
----
// CONSOLE

[[nested-top-level-params]]
==== Top-level parameters for `nested`

`path`::
(Required, string) Path to the nested object you wish to search.

`query`::
+
--
(Required, query object) Query you wish to run on nested objects in the `path`.
If an object matches the search, the `nested` query returns the root parent
document.

You can search nested fields using dot notation that includes the complete path,
such as `obj1.name`.

Multi-level nesting is automatically supported, and detected, resulting in an
inner nested query to automatically match the relevant nesting level, rather
than root, if it exists within another nested query.
--

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

`avg` (Default)::
Use the mean relevance score of all matching child objects.

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

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

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

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

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

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

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