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

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

A query that accepts a query template and a map of key/value pairs to fill in
template parameters. 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": {
            "inline": { "match": { "text": "{{query_string}}" }},
            "params" : {
                "query_string" : "all about search"
            }
        }
    }
}

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

The above request is translated into:

[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "match": {
            "text": "all about search"
        }
    }
}

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

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

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

==== Stored templates

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 `file`
parameter:


[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "file": "my_template", <1>
            "params" : {
                "query_string" : "all about search"
            }
        }
    }
}
------------------------------------------
<1> Name of the query template in `config/scripts/`, i.e., `my_template.mustache`.

Alternatively, you can register a query template in the cluster state with:

[source,js]
------------------------------------------
PUT /_search/template/my_template
{
    "template": { "match": { "text": "{{query_string}}" }},
}
------------------------------------------

and refer to it in the `template` query with the `id` parameter:


[source,js]
------------------------------------------
GET /_search
{
    "query": {
        "template": {
            "id": "my_template", <1>
            "params" : {
                "query_string" : "all about search"
            }
        }
    }
}
------------------------------------------
<1> Name of the query template in `config/scripts/`, i.e., `my_template.mustache`.


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