04.search_template

1. Search Template简介

/_search/template api 允许使用mustache(小胡子)语言在执行搜索请求之前预渲染它们，并使用模板参数填充现有模板。

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

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

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

2. 样例Examples

1. 存储一个template 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}}"
                }
            }
        }
    }
}

This template can be retrieved by

获取template

GET _scripts/<templateid>

 
返回

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

删除template

DELETE _scripts/<templateid>

使用存储的template来进行搜索

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

id是stored template的script name

校验一个search template
Validate a search template

A template can be rendered in a response with given parameters using

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

This call will return the rendered template:
返回渲染后的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 using

也可以使用store的template进行渲染

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

Explain
使用explain参数来看渲染的详情

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

Profiling
You can use profile parameter when running a template:
使用profile参数来进行性能分析

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

Filling in a query string with a single value

使用单个value来填充query string

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

将参数转成json
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
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
条件子句不能使用模板的JSON形式表示。而是必须将模板作为字符串传递。例如，假设我们要在行字段上运行匹配查询，并希望按行号进行过滤，其中开始和结束是可选的。

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.

We could write the query as:

{
  "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. 填充param text, Fill in the value of param text
2. 检测到line_no参数则包含range filter, Include the range filter only if line_no is specified
3. 检测到line_no.start 则包含gte 条件， Include the gte clause only if line_no.start is specified
4. 填充line_no.start 的value, Fill in the value of param line_no.start
5. 在检测到line_no.start AND line_no.end的时候填充一个逗号",", Add a comma after the gte clause only if line_no.start AND line_no.end are specified
6. 检测到line_no.end 的时候包含lte条件，Include the lte clause only if line_no.end is specified
7. 填充line_no.end的value, Fill in the value of param line_no.end

As written above, this template is not valid JSON because it includes the section markers like {{#line_no}}. For this reason, the template should either be stored in a file (see Store a search template) or, when used via the REST API, should be written as a string:

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

使用url编码
Encoding URLs
{{#url}}value{{/url}} 功能可以用来将参数进行url编码
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"
            }
        }
    }
}