search template 是什么
查询模板把带参数的查询存成脚本（mustache 语法），调用方只传参数不传查询结构，便于统一查询口径、限制可变范围，也能避免复杂 DSL 散落在多个应用里各写一套。存储用 PUT /_scripts/<id>，脚本语言写 mustache；调用用 GET /<index>/_search/template，传 id 与 params 两个字段。模板里用 {{变量}} 取值，{{#cond}}...{{/cond}} 写条件块。
基本信息
| 存储 | PUT /_scripts/<id>，script.lang = mustache |
|---|---|
| 调用 | GET /<index>/_search/template，传 id 与 params |
| 变量语法 | {{变量名}} 取值，未传时渲染为空串 |
| 条件语法 | {{#cond}}...{{/cond}} 控制可选子句 |
| 生效方式 | 注册后立即生效 |
典型使用场景
- 统一查询口径：多个服务共用同一份查询逻辑，避免各写一套 DSL
- 限制可变范围：只开放参数、查询结构由模板固定，降低写错的风险
- 简化调用：客户端只发参数，请求体更小也更稳定
- 版本管理：模板先测试再更新，便于对比新旧查询效果
- 灰度切换：新老模板并存，按流量比例逐步切换
注册与调用
注册与调用
PUT /_scripts/my_template
{
"script": {
"lang": "mustache",
"source": {
"query": { "match": { "title": "{{query_string}}" } },
"size": "{{size}}"
}
}
}
GET /my-index/_search/template
{
"id": "my_template",
"params": { "query_string": "elastic", "size": 5 }
}结构与参数读法
| 项 | 含义 | 注意 |
|---|---|---|
| _scripts/<id> | 模板存储位置 | id 全局唯一，更新立即生效 |
| lang | 脚本语言 | 目前主要使用 mustache |
| params | 调用时传入的参数 | 变量名要与模板一一对应 |
| {{var}} | 变量取值 | 未传参时渲染为空串 |
| {{#cond}} | 条件块 | 用于拼装可选子句 |
模板参数的字符串会按查询语法解释，把用户输入直接塞进 match 之外的位置可能引入注入风险；尽量让模板内部固定使用 match 一类查询接收外部输入。
注册脚本后立即生效，依赖它的多个应用会同时受影响；改动前先在测试索引上验证渲染结果，再决定是否替换线上模板。
多条件的模板建议给可选子句配默认值：把常用条件写成条件块，调用方按需传参，避免每次调用都要构造一整套参数。
模板也支持随请求体内联（inline）提交，适合只做参数化、不需要跨服务共享的场景；需要统一口径的共用查询才值得注册到 _scripts。