Named queries confusion

[liamwhite1 (Liam White)]

After reading the documentation for named queries, and attempting to perform some myself, I am thoroughly confused on how to name queries.

This doesn't work:

{
    "term": {
        "tag_id": 1,
        "_name": "test"
    }
}

{"reason": "[term] query doesn't support multiple fields, found [_name] and [tag_id]"}

Neither does this:

{
    "bool": {
        "must": [{"match_all": {}}],
    },
    "_name": "test"
}

{"reason": "[_name] query malformed, no start_object after query name"}

But this does:

{
    "terms": {
        "tag_id": [1],
        "_name": "test"
    }
}

The documentation says "Each filter and query can accept a _name in its top level definition." But based on what I observe, this doesn't seem to be the case. What are the rules for how named queries actually need to work?

[liamwhite1 (Liam White)]

After reading the Elasticsearch source code, I found that this is the correct syntax for using the named queries for the two examples I gave:

    "term": {
        "tag_id": {
            "value": 1,
            "_name": "test"
        }
    }

{
    "bool": {
        "must": [{"match_all": {}}],
        "_name": "test"
    }
}

The documentation is confusing and should be updated to show how to name all of the leaf queries to save me the time of having to read the source code of Elasticsearch to figure out how to do it.