Search template — Elastic Stack 实战手册

Search template — Elastic Stack 实战手册

· 更多精彩内容,请下载阅读全本《Elastic Stack实战手册》

· 加入创作人行列,一起交流碰撞,参与技术圈年度盛事吧

创作人:骆潇龙

Elasticsearch 允许使用模板语言 mustache 来预设搜索逻辑,在实际搜索时,通过参数中的键值,对来替换模板中的占位符,最终完成搜索。该方式将搜索逻辑封闭在 Elasticsearch 中,可以使下游服务,在不知道具体搜索逻辑的情况下完成数据检索。我们以 Kibana 自带的航班数据kibana_sample_data_flights为基础,以按航班号搜索为例,简单介绍搜索模板的使用。

第一步,创建 ID 为 testSearchTemplate 的搜索模板,语句如下

POST _scripts/testSearchTemplate
{ 
  "script": {
    "lang": "mustache",   #使用 mustache 模板语言
    "source": {   # 脚本内容
      "query": {    # 搜索逻辑
        "term": {
          "FlightNum": {
            "value": "{{FlightNum}}"  # 占位符 FlightNum
          }
        }
      }
    }
  }
}

第二步,传参搜索数据,语句如下

GET kibana_sample_data_flights/_search/template
{
  "id": "testSearchTemplate",     # 使用的模板ID
  "params": {
    "FlightNum": "9HY9SWR"    # 占位符替换的值
  }
}

以上两步就是使用模板搜索数据,该逻辑等同于下面这个搜索

GET kibana_sample_data_flights/_search
{
  "query": {
    "term": {
      "FlightNum": {
        "value": "9HY9SWR"
      }
    }
  }
}

API介绍

下面我们从搜索模板的生命周期:创建、查看、使用、删除来展开介绍模板搜索相关 API。

准备

在正式介绍之前,我们先来说一说关于模板搜索的几个预备知识。

首先,如果使用的 Elasticsearch 集群开启了安全功能,那么角色对操作的索引必须要有read权限。

其次,搜索模板使用的语法是Mustache

更多的关于该种脚本语言的介绍以及功能请查看其官方文档:https://mustache.github.io/mustache.5.html

最后,模板搜索属于 Elasticsearch 中 Script 功能的扩展, Script 的限定及用法基本都适用于模板搜索。比如,集群关于 Script 的配置也会影响模板搜索,配置项script.allowed_types可规范模板搜索接受的类型( inline / stored / both ),script.allowed_contexts也会限制模板搜索可进行的操作。

创建

搜索模板的创建与 Elasticsearch 其它脚本的创建一样,都是发送 1 个POST请求即可。

如下所示:

POST _scripts/<templateId>  # 1
{
  "script": {
    "lang": "mustache", # 2
    "source": {   # 3
      "query": {
          "term": {
            "FlightNum": {
              "value": "{{FlightNum}}"  # 可变参数 FlightNum
            }
          }
        }
    }
  }
}
  1. _scripts/<templateId>发送 POST 请求来创建搜索模板,其中<templateId>是你为该模板设置的 ID,搜索时会用到该 ID
  2. lang 参数配置的是搜索模板使用的脚本语言为mustache
  3. source 参数配置的是搜索模板的具体内容,该部分的格式参照 Elasticsearch 搜索的请求 body,需要搜索时填充的值使用mustache语法,配置占位符即可,比如本例中的占位符就是{{FlightNum}}

查看

当我们想查看之前创建的模板内容,或者验证某个 ID 的模板是否存在时,可以向_scripts/<templateId>发送 GET 请求来获取模板的具体内容。

示例如下:

GET _scripts/<templateId>  # 1
{
  "_id" : "testSearchTemplate",  # 2
  "found" : true,  # 3
  "script" : {   # 4
    "lang" : "mustache", 
    "source" : """{"query":{"term":{"FlightNum":{"value":"{{FlightNum}}"}}}}""", 
    "options" : {  # 5
      "content_type" : "application/json; charset=UTF-8"
    }
  }
}
  1. 请求的 path 为_scripts/<templateId>,其中<templateId>为你要查询的模板 Id,请求类型为 GET
  2. 返回的 body 中,_id 属性再次表明此次查询的模板 ID,本示例查询的是之前创建的testSearchTemplate模板
  3. found 属性表明此次查询是否查到结果,如果模板 ID 存在则此值为 true,反之为 false
  4. script 就是该搜索模板的具体内容与保存时相同。核心有 lang 属性表示脚本语法,source 属性存放脚本具体内容
  5. script 属性中的 Options 属性是非必要其它脚本属性,默认会有 content_type 属性,该属性保存查询时 http 请求的content-type ,默认为application/json; charset=UTF-8

删除

在一个搜索模板完成了它的使命后,我们需要及时删除它,因为 Elasticsearch 默认缓存脚本的数据量是有上限的,删除的方式很简单,发送一个DELETE请求即可。

示例如下:

DELETE _scripts/<templateId>   #1

<templateId>为要删除的搜索模板的 ID,比如_scripts/testSearchTemplate 表示的就是删除 ID 为testSearchTemplate的搜索模板。

使用

搜索模板的使用就是在搜索时,直接发送占位符的值,即可执行预设搜索语句。由于还是在搜索的范畴,所以发送请求的 path 是_search/template

下面是关于使用搜索模板进行查询的示例:

GET <index>/_search/template?<query_parameters> #1
{
  "source": """{"query": {"term": {"FlightNum": {"value": "{{FlightNum}}"}}}}""",  #2
  "id": "testSearchTemplate", # 3
  "params": {  # 4
    "FlightNum": "9HY9SWR"
  },
  "profile": true, # 5
  "explain": true  # 6
}

模板搜索发送的地址为<index>/_search/template,与搜索一样<index>处为选填参数,你可以指定搜索的索引,不指定则表示搜索全部索引。

因为本质上还是属于搜索的范畴,所以一些搜索参数在模板搜索是也可以使用,比如:

  • scroll(可选,时长):表示本搜索需要支持游标搜索,游标过期时间为配置值
  • ccs_minimize_roundtrips(可选,布尔值):如果为 true 则在跨集群搜索时最小化集群间交互。默认为 true
  • expand_wildcards(可选,字符串):表示索引通配符作用的范围,可配置为全部(all)、打开索引(open)、关闭索引(closed)、隐藏索引(hidden,需要与open或closed结合使用)、不允许通配符(none)
  • explain(可选,布尔值):表示返回结果是否带计算得分的详细信息,默认是false
  • ignore_throttled(可选,布尔值):如果为 true 则表示查询忽略被限制的索引,被限制的索引一般指被冻结(freeze)的索引,该值默认是 true
  • ignore_unavailable(可选,布尔值):如果为 true 则表示关闭的索引不在搜索范围内,默认值为 true
  • preference(可选,字符串):指定执行该操作的节点或分片,默认是随机的
  • rest_total_hits_as_int(可选,布尔值):如果为 true 则 hits.total 将会是个数值而非一个对象,默认为 false
  • routing(可选, 字符串):配置搜索执行的路由
  • search_type(可选,字符串):这是搜索的类型,可选值有:query_then_fetch、dfs_query_then_fetch
  • source 字段:用于配置搜索模板,该字段与 ID 字段冲突只能二选一,使用 source 表示不使用保存的模板而使用本模板
  • id 字段:表示本次查询使用的搜索模板 ID,该字段与 source 字 段冲突只能二选一
  • params 字段:配置的 key-value 值将替换模板中的占位符执行搜索
  • profile 字段:是可选字段,表示返回结果中是否有 Elasticsearch 执行搜索的一些元信息
  • explain 字段:是可选字段,与 http 中搜索参数配置的 explain 含义一样,表示结果是否带计算得分的详细信息

上述搜索返回结果如下:

{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 9.071844,
    "hits" : [
      {
        "_shard" : "[kibana_sample_data_flights][0]",
        "_node" : "ydZx8i8HQBe69T4vbYm30g",
        "_index" : "kibana_sample_data_flights",
        "_type" : "_doc",
        "_id" : "KPRFDHkB9LctWlE3WLqj",
        "_score" : 9.071844,
        "_source" : {
          "FlightNum" : "9HY9SWR",
          "DestCountry" : "AU",
          "OriginWeather" : "Sunny"
        },
        "_explanation" : {}  # 计算得分的逻辑
      }
    ]
  },
  "profile" : {} # 搜索细节信息
}

其它

本部分将介绍关于模板搜索的一些小技巧。通常情况下我们写的搜索模板,往往是很难一次就配置正确的,因此需要频繁的测试我们写的模板,与参数结合后是否是我们预期的搜索语句,这时我们就可以使用以下这个请求,来校验模板使用是否正确。

GET _render/template # 1
{
  "source": """{"query": {"term": {"FlightNum": {"value": "{{FlightNum}}"}}}}""" ,# 2
  "params": { # 3
    "FlightNum": "9HY9SWR"
  }
}

{  # 4
  "template_output" : {
    "query" : {
      "term" : {
        "FlightNum" : {
          "value" : "9HY9SWR"
        }
      }
    }
  }
}
  1. _render/template发送 GET 请求来验证模板是否正确
  2. source 字段为要验证的搜索模板,该字段可以省略,如果省略需要在 path 处指定模板iID,比如_render/template/testSearchTemplate
  3. params 字段为模板使用的参数
  4. 此 JSON 就是该请求的返回,template_output字段就是在使用此params下搜索模板生成的查询语句

模板语言 mustache 有许多功能,这里再介绍几个比较常见的。

比如我们使用占位符替换的不是一个字符串,而是一个对象或数组对象,那么我们可以用{{#toJson}}{{/toJson}}来实现,

具体如下:

GET _render/template
{
  "source": """{"query": {"term": {"FlightNum": {{#toJson}}FlightNum{{/toJson}}  }}}""", # 1
  "params": { # 2
    "FlightNum": {
      "value":"9HY9SWR"
    }
  }
}

{ # 3
  "template_output" : {
    "query" : {
      "term" : {
        "FlightNum" : {
          "value" : "9HY9SWR"
        }
      }
    }
  }
}

在配置模板时,我们将FlightNum的 value 配置为{{#toJson}}FlightNum{{/toJson}},即表示占位符FlightNum是一个对象

在配置 params 时,我们将 FlightNum 的值设置为一个 JSON 对象{ "value":"9HY9SWR"}

通过校验请求的返回,可以看到{{#toJson}}FlightNum{{/toJson}}被替换为对象{ "value":"9HY9SWR"}

Mustache 还能在将变量套入模板时做一些处理,比如将数组变量组合成字符串放入模板、设置占位符的默认值,以及对 URL 转码。

示例如下

GET _render/template
{
  "source": {
    "query": {
      "term": {
        "FlightNum": "{{#join delimiter='||'}}FlightNums{{/join delimiter='||'}}", #1
        "DestCountry":"{{DestCountry}}{{^DestCountry}}AU{{/DestCountry}}",#2
        "Dest": "{{#url}}{{Dest}}{{/url}}"#3
      }
    }
  },
  "params": {
    "FlightNums": [
      "9HY9SWR",
      "adf2c1"
    ],
    "Dest":"http://www.baidu.com"
  }
}

{
  "template_output" : {
    "query" : {
      "term" : {
        "FlightNum" : "9HY9SWR||adf2c1", # 4
        "DestCountry" : "AU", #5
        "Dest" : "http%3A%2F%2Fwww.baidu.com" # 6
      }
    }
  }
}

第一个模板使用{{#join delimiter='||'}}{{/join delimiter='||'}}设置了数组合并的分割字符为 "||",传参时FlightNums配置的为["9HY9SWR","adf2c1"],而生成的则是 #4 处的9HY9SWR||adf2c1

第二个模板使用{{^DestCountry}}AU{{/DestCountry}}设置了占位符 DestCountry 的默认值为 AU,这样我们在params中并未配置 DestCountry 的值,但生成的 #5 处自动用 AU 替换了占位符

第三个模板我们用{{#url}}{{/url}}声明了此处是一个 URL,需要进行转义,则在 #6 处配置的http://www.baidu.com变为了http%3A%2F%2Fwww.baidu.com

上一篇:Rollover API— Elastic Stack 实战手册


下一篇:Ingest pipelines—Elastic Stack 实战手册