IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Clear scroll API Multi search template API »
Elastic Docs ›Elasticsearch Guide [7.12] ›REST APIs ›Search APIs

Search template API

edit

Search template API

edit

Allows you to use the mustache language to pre render search requests.

GET _search/template
{
  "source" : {
    "query": { "match" : { "{{my_field}}" : "{{my_value}}" } },
    "size" : "{{my_size}}"
  },
  "params" : {
    "my_field" : "message",
    "my_value" : "foo",
    "my_size" : 5
  }
}

Request

edit

GET _search/template

Prerequisites

edit

Description

edit

The /_search/template endpoint allows you to use the mustache language to pre- render search requests, before they are executed and fill existing templates with template parameters.

For more information on how Mustache templating and what kind of templating you can do with it check out the online documentation of the mustache project.

The mustache language is implemented in Elasticsearch as a sandboxed scripting language, hence it obeys settings that may be used to enable or disable scripts per type and context as described in the scripting docs.

Path parameters

edit
<index>
(Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.

Query parameters

edit
allow_no_indices

(Optional, Boolean) If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.

Defaults to true.

ccs_minimize_roundtrips
(Optional, Boolean) If true, network round-trips are minimized for cross-cluster search requests. Defaults to true.
expand_wildcards

(Optional, string) Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are:

all
Match any data stream or index, including hidden ones.
open
Match open, non-hidden indices. Also matches any non-hidden data stream.
closed
Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
hidden
Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
none
Wildcard expressions are not accepted.
explain
(Optional, Boolean) If true, the response includes additional details about score computation as part of a hit. Defaults to false.
ignore_throttled
(Optional, Boolean) If true, specified concrete, expanded or aliased indices are not included in the response when throttled. Defaults to true.
ignore_unavailable
(Optional, Boolean) If false, the request returns an error if it targets a missing or closed index. Defaults to false.
preference
(Optional, string) Specifies the node or shard the operation should be performed on. Random by default.
profile
(Optional, Boolean) If true, the query execution is profiled. Defaults to false.
rest_total_hits_as_int
(Optional, Boolean) If true, hits.total are rendered as an integer in the response. Defaults to false.
routing
(Optional, string) Custom value used to route operations to a specific shard.
scroll
(Optional, time units) Specifies how long a consistent view of the index should be maintained for scrolled search.
search_type

(Optional, string) The type of the search operation. Available options:

  • query_then_fetch
  • dfs_query_then_fetch
typed_keys
(Optional, Boolean) If true, aggregation and suggester names are prefixed by their respective types in the response. Defaults to false.

Request body

edit

The API request body must contain the search definition template and its parameters.

Examples

edit

Store a search template

edit

To store a search template, use the create stored script API. Specify mustache as the lang.

POST _scripts/<templateid>
{
  "script": {
    "lang": "mustache",
    "source": {
      "query": {
        "match": {
          "title": "{{query_string}}"
        }
      }
    }
  }
}

To retrieve the template, use the get stored script API.

GET _scripts/<templateid>

The API returns:

{
  "script" : {
    "lang" : "mustache",
    "source" : """{"query":{"match":{"title":"{{query_string}}"}}}""",
    "options": {
      "content_type" : "application/json; charset=UTF-8"
    }
  },
  "_id": "<templateid>",
  "found": true
}

To delete the template, use the delete stored script API.

DELETE _scripts/<templateid>

Using a stored search template

edit

To use a stored template at search time send the following request:

GET _search/template
{
  "id": "<templateid>", 
  "params": {
    "query_string": "search for these words"
  }
}

Name of the stored template script.

Validating a search template

edit

A template can be rendered in a response with given parameters by using the following request:

GET _render/template
{
  "source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
  "params": {
    "statuses" : {
        "status": [ "pending", "published" ]
    }
  }
}

The API returns the rendered template:

{
  "template_output": {
    "query": {
      "terms": {
        "status": [ 
          "pending",
          "published"
        ]
      }
    }
  }
}

status array has been populated with values from the params object.

Stored templates can also be rendered by calling the following request:

GET _render/template/<template_name>
{
  "params": {
    "..."
  }
}

Using the explain parameter

edit

You can use the explain parameter when running a template:

GET _search/template
{
  "id": "my_template",
  "params": {
    "status": [ "pending", "published" ]
  },
  "explain": true
}

Profiling

edit

You can use the profile parameter when running a template:

GET _search/template
{
  "id": "my_template",
  "params": {
    "status": [ "pending", "published" ]
  },
  "profile": true
}

Filling in a query string with a single value

edit
GET _search/template
{
  "source": {
    "query": {
      "term": {
        "message": "{{query_string}}"
      }
    }
  },
  "params": {
    "query_string": "search for these words"
  }
}

Converting parameters to JSON

edit

The {{#toJson}}parameter{{/toJson}} function can be used to convert parameters like maps and array to their JSON representation:

GET _search/template
{
  "source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
  "params": {
    "statuses" : {
        "status": [ "pending", "published" ]
    }
  }
}

which is rendered as:

{
  "query": {
    "terms": {
      "status": [
        "pending",
        "published"
      ]
    }
  }
}

A more complex example substitutes an array of JSON objects:

GET _search/template
{
  "source": "{\"query\":{\"bool\":{\"must\": {{#toJson}}clauses{{/toJson}} }}}",
  "params": {
    "clauses": [
      { "term": { "user" : "foo" } },
      { "term": { "user" : "bar" } }
    ]
  }
}

which is rendered as:

{
  "query": {
    "bool": {
      "must": [
        {
          "term": {
            "user": "foo"
          }
        },
        {
          "term": {
            "user": "bar"
          }
        }
      ]
    }
  }
}

Concatenating array of values

edit

The {{#join}}array{{/join}} function can be used to concatenate the values of an array as a comma delimited string:

GET _search/template
{
  "source": {
    "query": {
      "match": {
        "emails": "{{#join}}emails{{/join}}"
      }
    }
  },
  "params": {
    "emails": [ "username@email.com", "lastname@email.com" ]
  }
}

which is rendered as:

{
  "query" : {
    "match" : {
      "emails" : "username@email.com,lastname@email.com"
    }
  }
}

The function also accepts a custom delimiter:

GET _search/template
{
  "source": {
    "query": {
      "range": {
        "born": {
            "gte"   : "{{date.min}}",
            "lte"   : "{{date.max}}",
            "format": "{{#join delimiter='||'}}date.formats{{/join delimiter='||'}}"
	    }
      }
    }
  },
  "params": {
    "date": {
        "min": "2016",
        "max": "31/12/2017",
        "formats": ["dd/MM/yyyy", "yyyy"]
    }
  }
}

which is rendered as:

{
  "query": {
    "range": {
      "born": {
        "gte": "2016",
        "lte": "31/12/2017",
        "format": "dd/MM/yyyy||yyyy"
      }
    }
  }
}

Default values

edit

A default value is written as {{var}}{{^var}}default{{/var}} for instance:

{
  "source": {
    "query": {
      "range": {
        "line_no": {
          "gte": "{{start}}",
          "lte": "{{end}}{{^end}}20{{/end}}"
        }
      }
    }
  },
  "params": { ... }
}

When params is { "start": 10, "end": 15 } this query would be rendered as:

{
  "range": {
    "line_no": {
      "gte": "10",
      "lte": "15"
    }
  }
}

But when params is { "start": 10 } this query would use the default value for end:

{
  "range": {
    "line_no": {
      "gte": "10",
      "lte": "20"
    }
  }
}

Conditional clauses

edit

Conditional clauses cannot be expressed using the JSON form of the template. Instead, the template must be passed as a string. For instance, let’s say we wanted to run a match query on the line field, and optionally wanted to filter by line numbers, where start and end are optional.

The params would look like:

{
  "params": {
    "text": "words to search for",
    "line_no": {                      
      "start": 10,
      "end": 20
    }
  }
}

The line_no, start, and end parameters are optional.

When written as a query, the template would include invalid JSON, such as section markers like {{#line_no}}:

{
  "query": {
    "bool": {
      "must": {
        "match": {
          "line": "{{text}}" 
        }
      },
      "filter": {
        {{#line_no}} 
          "range": {
            "line_no": {
              {{#start}} 
                "gte": "{{start}}" 
                {{#end}},{{/end}} 
              {{/start}}
              {{#end}} 
                "lte": "{{end}}" 
              {{/end}}
            }
          }
        {{/line_no}}
      }
    }
  }
}

Fill in the value of param text

Include the range filter only if line_no is specified

Include the gte clause only if line_no.start is specified

Fill in the value of param line_no.start

Add a comma after the gte clause only if line_no.start AND line_no.end are specified

Include the lte clause only if line_no.end is specified

Fill in the value of param line_no.end

Because search templates cannot include invalid JSON, you can pass the same query as a string instead:

"source": "{\"query\":{\"bool\":{\"must\":{\"match\":{\"line\":\"{{text}}\"}},\"filter\":{{{#line_no}}\"range\":{\"line_no\":{{{#start}}\"gte\":\"{{start}}\"{{#end}},{{/end}}{{/start}}{{#end}}\"lte\":\"{{end}}\"{{/end}}}}{{/line_no}}}}}}"

Encoding URLs

edit

The {{#url}}value{{/url}} function can be used to encode a string value in a HTML encoding form as defined in by the HTML specification.

As an example, it is useful to encode a URL:

GET _render/template
{
  "source": {
    "query": {
      "term": {
        "http_access_log": "{{#url}}{{host}}/{{page}}{{/url}}"
      }
    }
  },
  "params": {
    "host": "https://www.elastic.co/",
    "page": "learn"
  }
}

The previous query will be rendered as:

{
  "template_output": {
    "query": {
      "term": {
        "http_access_log": "https%3A%2F%2Fwww.elastic.co%2F%2Flearn"
      }
    }
  }
}
« Clear scroll API Multi search template API »