# Nested queries don't work as documented

**URL:** <https://discuss.elastic.co/t/nested-queries-dont-work-as-documented/275737>\
**Category:** Elasticsearch\
**Created:** [June 12, 2021, 6:49pm UTC](https://discuss.elastic.co/t/nested-queries-dont-work-as-documented/275737 "2021-06-12T18:49:39Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![titani0us](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/titani0us/32/31492_2.png) [@titani0us](https://discuss.elastic.co/u/titani0us)\
**Post date:** [June 12, 2021, 6:49pm UTC](https://discuss.elastic.co/t/nested-queries-dont-work-as-documented/275737/1 "2021-06-12T18:49:39Z")

</div>

Hello,

As documented in your documentation [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-query.html), the documentation shows using dot-notation to traverse a nested field (user -\> id). However, when using the query dsl this way, no results are returned.

Instead, you must use the nested query DSL structure in order to perform terms queries on nested fields.

Examples  
**Does Not work as documented**

```auto
{
    "query": {
         "terms": {
               "foo.object_id": [
                    "obj.lvu3r6PlxWwiSWuU"
                ]
           }
      }
 }

```

\*\* Works using nested DSL \*\*

```auto
{
    "query": {
        "nested": {
            "path": "foo",
            "query": {
                "terms": {
                    "foo.object_id": [
                        "obj.lvu3r6PlxWwiSWuU"
                    ]
                }
            }
        }
   }
}

```

I have seen the other threads where Elastic folks have confirmed you have to used the nested DSL, but my question is ..... why do you have a documented example on the latest release that shows otherwise?

Is this a bug or is your documentation just wrong/confusing?

If its just confusing, then I would love to know the easiest way to submit documentation change requests that actually get processed in a timely manner.

I think it's easy for folks that live and breath Elasticsearch to just "know" this was a documentation issue, but for newcomers this wastes a ton of valuable time. Especially with dot-notation being so prolific in many/most top-5 popular programming languages.

Thanks for any feedback/help here.

---

<div class="post-metadata">

**Author:** ![kumarabhi](https://avatars.discourse-cdn.com/v4/letter/k/6a8cbe/32.png) [@kumarabhi](https://discuss.elastic.co/u/kumarabhi)\
**Post date:** [June 13, 2021, 6:21am UTC](https://discuss.elastic.co/t/nested-queries-dont-work-as-documented/275737/2 "2021-06-13T06:21:48Z")

</div>

Nested documents should be queried with nested query  
Please refer to  
[Nested query | Elasticsearch Guide [7.13] | Elastic](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html)  
[Nested field type | Elasticsearch Guide [7.13] | Elastic](https://www.elastic.co/guide/en/elasticsearch/reference/current/nested.html)

---

<div class="post-metadata">

**Author:** ![Mark\_Harwood](https://sea2.discourse-cdn.com/elastic/user_avatar/discuss.elastic.co/mark_harwood/32/10538_2.png) [@Mark\_Harwood](https://discuss.elastic.co/u/Mark_Harwood)\
**Post date:** [June 13, 2021, 4:45pm UTC](https://discuss.elastic.co/t/nested-queries-dont-work-as-documented/275737/3 "2021-06-13T16:45:55Z")

</div>

The documentation for the terms query with the dot notation happens to show querying a sub property of an object. Objects aren’t always mapped as ‘nested’ unless there’s a particular need to do so.

---

<div class="post-metadata">

**Author:** ![system](https://us1.discourse-cdn.com/elastic/original/3X/1/a/1ac57faf039f6b580b3f104ef42a2a89e41014de.png) [@system](https://discuss.elastic.co/u/system)\
**Post date:** [July 11, 2021, 4:46pm UTC](https://discuss.elastic.co/t/nested-queries-dont-work-as-documented/275737/4 "2021-07-11T16:46:34Z")

</div>

This topic was automatically closed 28 days after the last reply. New replies are no longer allowed.