Elasticsearch Search API之搜索模板(search Template)
微信公众号：[中间件兴趣圈]
作者新书速递：
《RocketMQ技术内幕》新书上市，7折优惠，7折优惠啦！！！目前可在主流购物平台（京东、天猫等）购买，本书从源码角度深度分析了RocketMQ NameServer、消息发送、消息存储、消息消费、消息过滤、主从同步HA、事务消息；在实战篇重点介绍了RocketMQ运维管理界面与当前支持的39个运维命令；并在附录部分罗列了RocketMQ几乎所有的配置参数。本书得到了RocketMQ创始人、阿里巴巴Messaging开源技术负责人、Linux OpenMessaging 主席的高度认可并作序推荐。目前是国内第一本成体系剖析RocketMQ的书籍。
本节将详细介绍Elasticsearch Search API的搜索模板。
mustache模板语法
首先在学习Search Template之前，我们需要先掌握mustache模板语法，因为在ES中默认使用mustache语言来定义模板。
以下内容转载自：“https://www.cnblogs.com/DF-fzh/p/5979093.html”
Mustache 的模板语法比较简单，主要定义如下几个模板：
{{data}}
{{#data}} {{/data}}
{{^data}} {{/data}}
{{.}}
{{<partials}}
{{{data}}}
{{!comments}}
后续讲解基于如下数据展开：
1var souce = {
2 "name": " xiaohua ",
3 "msg": {
4 "sex": " female ",
5 "age": " 22 ",
6 "hobit": " reading "
7 },
8 "subject": ["Ch","En","Math","physics"]
9}
{{data}}
{{}}两对花括号是Mustache中的标识符。花括号里的data表示键名，这句的作用是直接输出与键名匹配的键值。
例如：
1var tpl = '{{name}}';
2var html = Mustache.render(tpl, souce);
3//输出：
4xiaohua ，为souce对象中属性名为name的值。
{{#data}} {{/data}}
以#开始、以/结束表示区块，它会根据当前上下文中的键值来对区块进行一次或多次渲染，例如改写下 Demo 中的 tpl：
1var tpl = '{{#msg}} <p>{{sex}},{{age}},{{hobit}}</p> {{/msg}}';
2var html = Mustache.render(tpl, data);
3//输出：
4<p> female, 22, reading</p>
通过#msg /msg定义一个块，在这个块中的属于msg属性的作用域。
{{^data}} {{/data}}
该语法与{{#data}}{{/data}}类似，不同在于它是当data值为null或undefined或false时才渲染输出该区块内容。
1var tpl = {{^nothing}}没找到 nothing 键名就会渲染这段{{/nothing}};
2var html = Mustache.render(tpl, data);
3//输出：
4没找到 nothing 键名就会渲染这段
{{.}}
{{.}}表示枚举，可以循环输出整个数组，例如：
1var tpl = '{{#subject}} <p>{{.}}</p> {{/subject}}';
2var html = Mustache.render(tpl, data);
3//输出：
4p>Ch</p> <p>En</p> <p>Math</p> <p>physics</p>
{{>partials}}
以>开始表示子模块，如{{> msg}}；当结构比较复杂时，我们可以使用该语法将复杂的结构拆分成几个小的子模块，例如：
1var tpl = "<h1>{{namme}}</h1> <ul>{{>msg}}</ul>"
2var partials = {msg: "{{#msg}}<li>{{sex}}</li><li>{{age}}</li><li>{{hobit}}</li>{{/msg}
3var html = Mustache.render(tpl, data, partials);
4//输出：
5<h1>xiaohua</h1>
6<ul>
7 <li>female</li>
8 <li>22</li>
9 <li>reading</li>
10</ul>
{{!comments}}
注释语句。
掌握了mustache语法后，我们进入ES Search Template的讲解。
所谓的搜索模板，其实有点类似于SQL语句中的预处理，就是对查询表达式中包含占位符来，在查询时指定相应的参数，这类模板，也可以预先存储在ES服务器中。
ES搜索模板详解
下面从示例开始着手介绍：
1GET _search/template
2{
3 "source" : {
4 "query": { "match" : { "{{my_field}}" : "{{my_value}}" } },
5 "size" : "{{my_size}}"
6 }, // @1
7 "params" : { // @2
8 "my_field" : "message",
9 "my_value" : "some message",
10 "my_size" : 5
11 }
12}
代码@1：通过souce字段定义查询字符串，其中使用mustache语法来定义占位符的意义。
代码@2：通过params参数设置参数，此时请注意参数中key需要与模板中的 {{key}}相等，否则无法完成替换。
上述对应的JAVA Demo代码如下：
1public static void searchBySearchTemplate() {
2 RestHighLevelClient client = EsClient.getClient();
3 try {
4 SearchRequest searchRequest = new SearchRequest();
5 searchRequest.indices("mapping_search_after");
6
7 SearchTemplateRequest templateRequest = new SearchTemplateRequest(searchRequest); // @1
8
9 Map<String, Object> scriptParams = new HashMap<>();
10 scriptParams.put("termQuery_field", "user");
11 scriptParams.put("termQuery_field_value", "user1");
12 scriptParams.put("my_size", 5);
13 templateRequest.setScriptParams(scriptParams); // @2
14 templateRequest.setScriptType(ScriptType.INLINE); // @3 start
15 templateRequest.setScript("{\r\n" +
16 " \"query\": { \"match\" : { \"{{termQuery_field}}\" : \"{{termQuery_field_value}}\" } },\r\n" +
17 " \"size\" : \"{{my_size}}\"\r\n" +
18 " }"); // @3 end
19
20 SearchTemplateResponse result = client.searchTemplate(templateRequest, RequestOptions.DEFAULT);
21 System.out.println(result);
22 } catch (Throwable e) {
23 e.printStackTrace();
24 } finally {
25 EsClient.close(client);
26 }
27 }
代码@1：构建SearchTemplateRequest对象时通常会传入一个SearchRequest对象，由SearchRequest对象指定查询的索引。
代码@2：使用scriptParams接受Map类型的参数，本次查询的参数。
代码@3：使用scriptType参数，指定脚步的位置，其中ScriptType.INLINE，则脚步的内容由script属性指定；如果类型为ScriptType.STORE，表示存储在es服务器中，其script表示脚本的内容，如果要使用ScriptType.STORE，首先需要使用增加脚本API添加模板，将在下文介绍如何调用API添加脚本。
converting parameters to JSON
将参数转换为JSON。可以通过 {{#toJson}}parameter{{/toJson}} 语法指示parameter要被替换为json对象，而不是普通的字符串，示例如下：
1GET _search/template
2{
3 "source": "{ \"query\": { \"terms\": {{#toJson}}statuses{{/toJson}} }}",
4 "params": {
5 "statuses" : {
6 "status": [ "pending", "published" ]
7 }
8 }
9}
其需要传入的值为：
1{
2 "statuses" : {
3 "status": [ "pending", "published" ]
4 }
5}
其表示的含义如下：
1{
2 "query": {
3 "terms": {
4 "status": ["pending","published"]
5 }
6 }
7}
对应的JAVA示例如下：
1public static void searchBySearchTemplate_toJson() {
2 RestHighLevelClient client = EsClient.getClient();
3 try {
4 SearchRequest searchRequest = new SearchRequest();
5 searchRequest.indices("mapping_search_after");
6 SearchTemplateRequest templateRequest = new SearchTemplateRequest(searchRequest);
7 templateRequest.setScript("{ \"query\": { \"terms\": {{#toJson}}ids{{/toJson}} }}");
8 Map<String, Object> scriptParams = new HashMap<>();
9 Map<String, Object> idMap = new HashMap<>();
10 idMap.put("id", Arrays.asList(1,2));
11 scriptParams.put("ids", idMap);
12 templateRequest.setScriptParams(scriptParams);
13 templateRequest.setScriptType(ScriptType.INLINE);
14 SearchTemplateResponse result = client.searchTemplate(templateRequest, RequestOptions.DEFAULT);
15 System.out.println(result);
16 } catch (Throwable e) {
17 e.printStackTrace();
18 } finally {
19 EsClient.close(client);
20 }
21 }
concatenating array of values
{{#join}数组{{/join}}函数可用于将数组的值连接为逗号分隔的字符串：
1GET _search/template
2{
3 "source": {
4 "query": {
5 "match": {
6 "emails": "{{#join}}emails{{/join}}"
7 }
8 }
9 },
10 "params": {
11 "emails": [ "username@email.com", "lastname@email.com" ]
12 }
13}
其转换后的ES查询语法如下：
1{
2 "query" : {
3 "match" : {
4 "emails" : "username@email.com,lastname@email.com"
5 }
6 }
7}
默认是用逗号连接，可以通过delimiter属性自定义分隔符号，例如：
1GET _search/template
2{
3 "source": {
4 "query": {
5 "range": {
6 "born": {
7 "gte" : "{{date.min}}",
8 "lte" : "{{date.max}}",
9 "format": "{{#join delimiter='||'}}date.formats{{/join delimiter='||'}}"
10 }
11 }
12 }
13 },
14 "params": {
15 "date": {
16 "min": "2016",
17 "max": "31/12/2017",
18 "formats": ["dd/MM/yyyy", "yyyy"]
19 }
20 }
21}
其代表的ES查询语法如下：
1{
2 "query" : {
3 "range" : {
4 "born" : {
5 "gte" : "2016",
6 "lte" : "31/12/2017",
7 "format" : "dd/MM/yyyy||yyyy"
8 }
9 }
10 }
11}
Java的使用方式不变，就不再重复给出。
Default values
可以通过{{var}}{{^var}}default{{/var}}来设定默认值。
1{
2 "source": {
3 "query": {
4 "range": {
5 "line_no": {
6 "gte": "{{start}}",
7 "lte": "{{end}}{{^end}}20{{/end}}"
8 }
9 }
10 }
11 },
12 "params": { ... }
13}
表示如果params中如果存在end参数，就使用end参数的值，如果没有，则使用默认值20。
Encoding URLS
可以使用{{#url}}value{{/url}} 来编码URL。
1GET _render/template
2{
3 "source" : {
4 "query" : {
5 "term": {
6 "http_access_log": "{{#url}}{{host}}/{{page}}{{/url}}"
7 }
8 }
9 },
10 "params": {
11 "host": "https://www.elastic.co/",
12 "page": "learn"
13 }
14}
其对应的ES查询语法为：
1{
2 "template_output" : {
3 "query" : {
4 "term" : {
5 "http_access_log" : "https%3A%2F%2Fwww.elastic.co%2F%2Flearn"
6 }
7 }
8 }
9}
Pre-registred template
预注册搜索模板。
使用如下方式添加搜索模板，此时会存储在es服务器中，举例如下：
1POST _scripts/<templatename>
2{
3 "script": { // @1
4 "lang": "mustache", // @2
5 "source": { // @3
6 "query": {
7 "match": {
8 "title": "{{query_string}}"
9 }
10 }
11 }
12 }
13}
代码@1：使用script属性来定义整个模板的各个属性。
代码@2：lang，指定使用的模板脚本描述语言，这里选择的模板语言为：mustache。
代码@3：通过souce字段指定用户定义的模板。
目前作者使用的es版本为6.4.0,其高级Rest客户端并未封装增加脚步的API，故
如下示例给出基于RestClient API 添加搜索模板。
1public void addScript(String templateName, String script) { // @1
2 if (StringUtils.isEmpty(templateName) || StringUtils.isEmpty(script)) {
3 throw new RuntimeException("参数非法");
4 }
5
6 StringBuilder scriptBody = new StringBuilder();
7 scriptBody.append("{\"script\": {").append("\"lang\":\"mustache\",").append("\"source\":")
8 .append(script).append("}").append("}");
9
10 RestClient lowRestClient = restHighLevelClient.getLowLevelClient();
11 Request request = new Request("POST", "/_scripts/" + templateName);
12 request.setJsonEntity(scriptBody.toString());
13 try {
14 Response response = lowRestClient.performRequest(request);
15 int statusCode = response.getStatusLine().getStatusCode();// 响应状态行，可以从中获取状态码
16 if (statusCode == 200) {
17 // 获取指定名称的响应头，这里可以根据返回类型，进行结果集解码，默认为json
18 String responseBody = EntityUtils.toString(response.getEntity());// 响应体包含在
19 // {"acknowledged":true}
20 JSONObject result = JSON.parseObject(responseBody);
21 if(!result.getBoolean("acknowledged")) {
22 throw new RuntimeException("添加模板失败:" + responseBody);
23 }
24 } else {
25 throw new RuntimeException("添加模板失败");
26 }
27 } catch (IOException e) {
28 throw new RuntimeException("添加模板失败", e);
29 }
30 }
对参数做个简单的说明：
1）String templateName：模板名称。
2）String script：脚本内容。
例如要先存储如下搜索模板：
1{
2 "query": {
3 "match" : {
4 "{{termQuery_field}}" : "{{termQuery_field_value}}"
5 }
6 },
7 "size" : "{{my_size}}"
8}
Java示例代码：
1public static void testCreateSearchTemplate() {
2 ElasticsearchTemplate template = new ElasticsearchTemplate();
3 try {
4 template.addScript("testTemplate02",
5 "{\"query\": { \"match\" : { \"{{termQuery_field}}\" : \"{{termQuery_field_value}}\" } },\"size\" : \"{{my_size}}\"}");
6 } finally {
7 template.close();
8 }
9}
模板存储后，就可以直接根据名称(id)来使用了。
1templateRequest.setScriptParams(scriptParams);
2templateRequest.setScriptType(ScriptType.STORED);
3templateRequest.setScript("testTemplate02");
搜索模板就介绍到这里。
Multi Search Template
多模板搜索API可以在一次请求中执行多个搜索模板，其请求格式与Bulk、Multi-Search请求格式与工作机制类似。在这里就不在过细讲解，就是在请求的时候将多个请求放入一个集合中，然后返回结果也按照该顺序进行返回。对应的API接口为：RestHighLevelClient#msearchTemplate。
本节详细介绍了ElasticSearch 搜索模板的相关知识。
更多文章请关注微信公众号：