Elasticsearch Search Template 搜索模板

Elasticsearch Search Template

所谓 search template 搜索模板其实就是：

1. 预先定义好查询语句 DSL 的结构并预留参数
2. 搜索的时再传入参数值
3. 渲染出完整的 DSL ，最后进行搜索

使用搜索模板可以将 DSL 从应用程序中解耦出来，并且可以更加灵活的更改查询语句。

例如：

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

构造出来的 DSL 就是：

{"query": {"match": {"message": "foo"}}
}

在模板中通过 {{ }} 的方式预留参数，然后查询时再指定对应的参数值，最后填充成具体的查询语句进行搜索。

---

搜索模板 API

为了实现搜索模板和查询分离，我们首先需要单独保存和管理搜索模板。

保存搜索模板

使用 scripts API 保存搜索模板（不存在则创建，存在则覆盖）。示例：

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

查询搜索模板

GET _scripts/<templateid>

删除搜索模板

DELETE _scripts/<templateid>

使用搜索模板

示例：

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

params 中的参数与搜索模板中定义的一致，上文保存搜索模板的示例是 {{query_string}}，所以这里进行搜索时对应的参数就是 query_string 。

检验搜索模板

有时候我们想看看搜索模板输入了参数之后渲染成的 DSL 到底长啥样。

示例：

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

返回的结果就是：

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

{{#toJson}} {{/toJson}} 就是转换成 json 格式。

已经保存的搜索模板可以通过以下方式查看渲染结果：

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

使用 explain 和 profile 参数

示例：

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

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

模板渲染

填充简单值

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

渲染出来的 DSL 就是：

{"query": {"term": {"message": "search words"}}
}

将参数转换为 JSON

使用 {{#toJson}}parameter{{/toJson}} 会将参数转换为 JSON。

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

渲染出来的 DSL 就是：

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

对象数组的渲染示例：

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

渲染结果就是：

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

将数组 join 成字符串

使用 {{#join}}array{{/join}} 可以将数组 join 成字符串。

示例：

GET _search/template
{"source": {"query": {"match": {"emails": "{{#join}}emails{{/join}}"}}},"params": {"emails": [ "aaa", "bbb" ]}
}

渲染结果：

{"query" : {"match" : {"emails" : "aaa,bbb"}}
}

除了默认以 , 分隔外，还可以自定义分隔符，示例：

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

例子中的 {{#join delimiter='||'}} {{/join delimiter='||'}} 意思就是进行 join 操作，分隔符设置为 || ，渲染结果就是：

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

默认值

使用 {{var}}{{^var}}default{{/var}} 的方式设置默认值。

示例：

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

{{end}}{{^end}}20{{/end}} 就是给 end 设置了默认值为 20 。

当 params 是 { "start": 10, "end": 15 } 时，渲染结果是：

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

当 params 是 { "start": 10 } 时，end 就会使用默认值，渲染结果就是：

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

条件子句

有时候我们的参数是可选的，这时候就可以使用 {{#key}} {{/key}}的语法。

示例，假设参数 line_no, start, end 都是可选的，使用 {{#key}} {{/key}} 形如：

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

1、 当参数为：

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

渲染结果是：

{"query": {"bool": {"must": {"match": {"line": "words to search for"}},"filter": {"range": {"line_no": {"gte": "10","lte": "20"}}}}}
}

2、 当参数为：

{"params": {"text": "words to search for"}
}

渲染结果为：

{"query": {"bool": {"must": {"match": {"line": "words to search for"}},"filter": {}}}
}

3、当参数为：

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

渲染结果为：

{"query": {"bool": {"must": {"match": {"line": "words to search for"}},"filter": {"range": {"line_no": {"gte": 10}}}}}
}

4、当参数为：

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

渲染结果为：

{"query": {"bool": {"must": {"match": {"line": "words to search for"}},"filter": {"range": {"line_no": {"lte": 20}}}}}
}

需要注意的是在 JSON 对象中，

{"filter": {{{#line_no}}...{{/line_no}}}
}

这样直接写 {{#line_no}} 肯定是非法的JSON格式，你必须转换为 JSON 字符串。

URLs 编码

使用 {{#url}}value{{/url}} 的方式可以进行 HTML 编码转义。

示例：

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

渲染结果：

{"template_output": {"query": {"term": {"http_access_log": "https%3A%2F%2Fwww.elastic.co%2F%2Flearn"}}}
}

---

Mustache 基本语法

上文中的 {{ }} 语法其实就是 mustache language ，补充介绍下基本的语法规则。

使用 {{key}}

模板：Hello {{name}}

输入：

{"name": "Chris"
}

输出：Hello Chris

使用 {{{key}}} 避免转义

所有变量都会默认进行 HTML 转义。

模板：{{company}}

输入：

{"company": "<b>GitHub</b>"
}

输出：<b>GitHub</b>

使用 {{{ }}} 避免转义。

模板：{{{company}}}

输入：

{"company": "<b>GitHub</b>"
}

输出：<b>GitHub</b>

使用 {{#key}} {{/key}} 构造区块

1、 当 key 是 false 或者空列表将会忽略
模板：

    Shown.{{#person}}Never shown!{{/person}}

输入：

{"person": false
}

输出：

    Shown.

2、 当 key 非空值则渲染填充
模板：

    {{#repo}}<b>{{name}}</b>{{/repo}}

输入：

{"repo": [{ "name": "resque" },{ "name": "hub" },{ "name": "rip" }]
}

输出：

    <b>resque</b><b>hub</b><b>rip</b>

3、当 key 是函数则调用后渲染
模板：

    {{#wrapped}}{{name}} is awesome.{{/wrapped}}

输入：

{"name": "Willy","wrapped": function() {return function(text, render) {return "<b>" + render(text) + "</b>"}}
}

输出：

    <b>Willy is awesome.</b>

4、当 key 是非 false 且非列表
模板：

    {{#person?}}Hi {{name}}!{{/person?}}

输入：

{"person?": { "name": "Jon" }
}

输出：

    Hi Jon!

使用 {{^key}} {{/key}} 构造反区块

{{^key}} {{/key}} 的语法与 {{#key}} {{/key}} 类似，不同的是，当 key 不存在，或者是 false ，又或者是空列表时才渲染输出区块内容。

模板：

    {{#repo}}<b>{{name}}</b>{{/repo}}{{^repo}}No repos :({{/repo}}

输入：

{"repo": []
}

输出：

    No repos :(

使用 {{! }} 添加注释

{{! }} 注释内容将会被忽略。

模板：

<h1>Today{{! ignore me }}.</h1>

输出：

<h1>Today.</h1>

使用 {{> }} 子模块

模板：

base.mustache:
<h2>Names</h2>
{{#names}}{{> user}}
{{/names}}user.mustache:
<strong>{{name}}</strong>

其实也就等价于：

<h2>Names</h2>
{{#names}}<strong>{{name}}</strong>
{{/names}}

使用 {{= =}} 自定义定界符

有时候我们需要改变默认的定界符 {{ }} ，那么就可以使用 {{= =}} 的方式自定义定界符。

例如：

{{=<% %>=}}

定界符被定义为了 <% %>，这样原先 {{key}} 的使用方式就变成了 <%key%>。
再使用：

<%={{ }}=%>

就重新把定界符改回了 {{ }}。

更多语法详情请查阅官方文档 mustache language 。

结语

使用 search template 可以对搜索进行有效的解耦，即应用程序只需要关注搜索参数与返回结果，而不用关注具体使用的 DSL 查询语句，到底使用哪种 DSL 则由搜索模板进行单独管理。