elasticsearch/docs/reference/query-dsl/queries/template-query.asciidoc

[[query-dsl-template-query]]
=== Template Query

added[1.1.0]

A query that accepts a query template and a map of key/value pairs to fill in
template parameters.

[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "query": {"match_{{template}}": {}},
            "params" : {
                "template" : "all"
            }
        }
    }
}

------------------------------------------


Alternatively passing the template as an escaped string works as well:

[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "query": "{\"match_{{template}}\": {}}\"", <1>
            "params" : {
                "template" : "all"
            }
        }
    }
}
------------------------------------------
<1> New line characters (`\n`) should be escaped as `\\n` or removed,
    and quotes (`"`) should be escaped as `\\"`.

You can register a template by storing it in the `config/scripts` directory, in a file using the `.mustache` extension.
In order to execute the stored template, reference it by name in the `query`
parameter:


[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "query": "storedTemplate", <1>
            "params" : {
                "template" : "all"
            }
        }
    }
}

------------------------------------------
<1> Name of the the query template in `config/scripts/`, i.e., `storedTemplate.mustache`.

Templating is based on Mustache. For simple token substitution all you provide
is a query containing some variable that you want to substitute and the actual
values:


[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "query": {"match_{{template}}": {}},
            "params" : {
                "template" : "all"
            }
        }
    }
}
------------------------------------------

which is then turned into:

[source,js]
------------------------------------------
{
    "query": {
        "match_all": {}
    }
}
------------------------------------------

added[1.3.0]

You can register a template by storing it in the elasticsearch index `.scripts` or by using the REST API. (See <<search-template>> for more details)
In order to execute the stored template, reference it by name in the `query`
parameter:


[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "query": "templateName", <1>
            "params" : {
                "template" : "all"
            }
        }
    }
}
------------------------------------------
<1> Name of the the query template stored in the index.

[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "query": "storedTemplate", <1>
            "params" : {
                "template" : "all"
            }
        }
    }
}

------------------------------------------


There is also a dedicated `template` endpoint, allows you to template an entire search request.
Please see <<search-template>> for more details.