Skip to content

Latest commit

 

History

History
724 lines (589 loc) · 16.8 KB

search-template.asciidoc

File metadata and controls

724 lines (589 loc) · 16.8 KB
Raw

Search template API

Search template

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
  }
}

{api-request-title}

GET _search/template

{api-prereq-title}

{api-description-title}

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.

Note
 The mustache language is implemented in {es} 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.

{api-query-parms-title}

+ Defaults to true.

ccs_minimize_roundtrips

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

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.

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.

typed_keys

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

{api-request-body-title}

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

{api-response-codes-title}

Store a search template

You can store a search template using the stored scripts API.

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

The template can be retrieved by calling

GET _scripts/<templateid>

The API returns the following result:

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

This template can be deleted by calling

DELETE _scripts/<templateid>
Using a stored search template

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

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

  1. Name of the stored template script.

Validating a search template

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": [ (1)
          "pending",
          "published"
        ]
      }
    }
  }
}

  1. 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

You can use the explain parameter when running a template:

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

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
GET _search/template
{
  "source": {
    "query": {
      "term": {
        "message": "{{query_string}}"
      }
    }
  },
  "params": {
    "query_string": "search for these words"
  }
}
Converting parameters to JSON

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

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

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

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": {                      (1)
      "start": 10,
      "end": 20
    }
  }
}

  1. 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}}" (1)
        }
      },
      "filter": {
        {{#line_no}} (2)
          "range": {
            "line_no": {
              {{#start}} (3)
                "gte": "{{start}}" (4)
                {{#end}},{{/end}} (5)
              {{/start}}
              {{#end}} (6)
                "lte": "{{end}}" (7)
              {{/end}}
            }
          }
        {{/line_no}}
      }
    }
  }
}

  1. Fill in the value of param text

  2. Include the range filter only if line_no is specified

  3. Include the gte clause only if line_no.start is specified

  4. Fill in the value of param line_no.start

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

  6. Include the lte clause only if line_no.end is specified

  7. 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

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"
      }
    }
  }
}

Multi search template API

Multi search template

Allows to execute several search template requests.

{api-request-title}

GET _msearch/template

{api-prereq-title}

{api-description-title}

Allows to execute several search template requests within the same API using the _msearch/template endpoint.

The format of the request is similar to the Multi Search API format:

header\n
body\n
header\n
body\n

The header part supports the same index, search_type, preference, and routing options as the Multi Search API.

The body includes a search template body request and supports inline, stored and file templates.

{api-examples-title}

$ cat requests
{"index": "test"}
{"source": {"query": {"match":  {"user" : "{{username}}" }}}, "params": {"username": "john"}} (1)
{"source": {"query": {"{{query_type}}": {"name": "{{name}}" }}}, "params": {"query_type": "match_phrase_prefix", "name": "Smith"}}
{"index": "_all"}
{"id": "template_1", "params": {"query_string": "search for these words" }} (2)

$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo

  1. Inline search template request

  2. Search template request based on a stored template

The response returns a responses array, which includes the search template response for each search template request matching its order in the original multi search template request. If there was a complete failure for that specific search template request, an object with error message will be returned in place of the actual search response.