1. 什么是 Search Template？能解决什么问题？

搜索模板是存储在 ES 集群里的 Mustache 模板（lang: mustache）。你把一份标准 _search 请求体写成模板，变量交给 params，每次调用只需传参即可：

搜索前端：把输入框内容作为 params 传进来，屏蔽 DSL 细节与危险语法。
业务后端：把“检索策略”与“业务代码”解耦——需要改查询逻辑时，只改模板，不用发版。
多团队协作：数据/搜索工程师直接维护模板，应用侧只负责传参和渲染结果。

模板以脚本的形式存在集群状态中（Stored Script），受脚本开关与限制影响（如禁用脚本、限制大小等）。

2. 快速上手（5 分钟）

2.1 创建/更新模板

PUT _scripts/my-search-template
{"script": {"lang": "mustache","source": {"query": { "match": { "message": "{{query_string}}" } },"from": "{{from}}","size": "{{size}}"}}
}

2.2 本地渲染与调试（不真正搜索）

POST _render/template
{"id": "my-search-template","params": { "query_string": "hello world", "from": 20, "size": 10 }
}

2.3 运行模板化搜索

GET my-index/_search/template
{"id": "my-search-template","params": { "query_string": "hello world", "from": 0, "size": 10 }
}

2.4 批量运行（多查询一起发）

GET my-index/_msearch/template
{ }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 } }
{ }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" } }

2.5 管理模板

获取某个模板：GET _scripts/my-search-template
列出全部：GET _cluster/state/metadata?filter_path=metadata.stored_scripts
删除：DELETE _scripts/my-search-template

3. Mustache 语法要点（结合搜索的“刚需功能”）

Mustache 是逻辑少的模板语言，靠变量替换 + 区块控制完成拼装。

3.1 变量与默认值

POST _render/template
{"source": {"query": { "match": { "message": "{{query_string}}" } },"from": "{{from}}{{^from}}0{{/from}}","size": "{{size}}{{^size}}10{{/size}}"},"params": { "query_string": "hello world" }
}

{{var}}：变量
{{^var}}default{{/var}}：当 var 不存在/为空时用默认值

3.2 条件与 if-else

"filter": [{{#year_scope}}{ "range": { "@timestamp": { "gte": "now-1y/d", "lt": "now/d" } }},{{/year_scope}}{ "term": { "user.id": "{{user_id}}" } }
]

{{#cond}}...{{/cond}}：cond 为真则渲染
{{^cond}}...{{/cond}}：cond 为假则渲染
两者可组合做 if-else

3.3 工具函数（Lambda）

URL 编码：{{#url}}{{host}}/{{page}}{{/url}}
拼接数组：{{#join delimiter='||'}}date.formats{{/join}}
转 JSON：{{#toJson}}tags{{/toJson}}（数组/对象都能转）

⚠️ 强烈建议：凡是数组、对象、子查询块，一律用 toJson 输出，避免引号/逗号导致的无效 JSON。

3.4 列表循环与“尾逗号”陷阱

"fields": [{{#text_fields}}{{user_name}}{{^last}},{{/last}}{{/text_fields}}]

用一个布尔字段 last 控制是否加逗号，避免 [a,b,] 这种无效 JSON。

3.5 更换变量分隔符（小众）

{{=( )=}}
"message": "(query_string)"
(={{ }}=)

在模板内部临时把 {{ }} 改为 ()，适用于与其他模板语言冲突的场景。

不支持：Mustache 的 partials 特性在 ES 搜索模板里不可用。

4. 进阶：把“复杂检索策略”模板化

Search Template 的 source 支持 _search 的全部请求体，你可以模板化任何结构：Query DSL、Retrievers、kNN、RRF、LTR 重排、Async Search 参数等。

4.1 混合检索（RRF）模板

PUT _scripts/rrf-template
{"script": {"lang": "mustache","source": {"retriever": {"rrf": {"rank_window_size": "{{rank_window}}{{^rank_window}}100{{/rank_window}}","retrievers": [{ "standard": { "query": { "match": { "text": "{{q}}" } } } },{ "standard": { "query": { "sparse_vector": {"field": "vector.tokens", "inference_id": "{{elser_id}}", "query": "{{q}}"}}}}]}},"size": "{{size}}{{^size}}10{{/size}}"}}
}

使用：

GET my-index/_search/template
{"id": "rrf-template","params": { "q": "blue shoes sale", "elser_id": "my-elser-endpoint", "size": 20 }
}

4.2 LTR（学习排序）重排模板

PUT _scripts/ltr-rescore
{"script": {"lang": "mustache","source": {"retriever": {"rescorer": {"retriever": { "standard": { "query": { "multi_match": {"query": "{{q}}", "fields": ["title^2","content"]}}}},"window_size": "{{win}}{{^win}}100{{/win}}","learning_to_rank": {"model_id": "{{model_id}}","params": { "query_text": "{{q}}" }}}},"from": "{{from}}{{^from}}0{{/from}}","size": "{{size}}{{^size}}10{{/size}}"}}
}

生产要点：window_size ≥ from + size，否则可能出现未重排的文档排在前面。

4.3 可选项与权限控制

把“是否限定时间范围”“是否加高权重字段”等开关做成布尔参数，套 {{#cond}}...{{/cond}}。
把“敏感过滤”写入模板，前端只能传白名单参数，降低注入风险。

5. 工程化落地清单

命名与版本

模板 id 采用 search.<domain>.<scenario>.v1，修改不兼容时递增版本，便于回滚。

参数白名单

应用层只接受你定义好的 params 字段；对字符串做长度限制、对数组做最大项数限制。

渲染前自检

先 _render/template；若 JSON 解析失败立即中断，返回明确错误给上游。

监控与审计

记录模板 id、参数快照（脱敏）、渲染耗时、命中率、took、超时率，为回归与 A/B 提供数据。

性能开关

大范围查询配 timeout；只要命中数就 size:0 + terminate_after;
不追求精确总数就别 track_total_hits:true（或给个阈值），保性能可控。

安全与脚本限制

了解脚本相关设置（如禁用脚本会影响模板）；控制模板大小与数量，避免集群状态膨胀。

6. 常见坑与排雷

尾逗号/引号错位：数组/对象拼装一律用 toJson；列表循环用 last 变量收尾。
空变量导致非法查询：对可空字段加默认值或用条件包裹。
把用户输入直塞进 DSL：一定做白名单与长度校验（模板只是替换，不会自动防注入）。
脚本被禁用：排查集群脚本设置（模板属于 stored script）。
多团队改动互相影响：对模板加 代码评审/发布流程，并约定 id 与版本策略。

7. 一键迁移套路（给你一套模版骨架）

PUT _scripts/search.web.v1
{"script": {"lang": "mustache","source": {"query": {"bool": {"filter": [{{#time_range}}{ "range": { "@timestamp": { "gte": "{{gte}}", "lte": "{{lte}}" } } },{{/time_range}}{{#env}}{ "term": { "service.env": "{{env}}" } },{{/env}}{{#category}}{ "term": { "category.keyword": "{{category}}" } }{{/category}}],"must": [{{#q}}{ "simple_query_string": { "query": "{{q}}", "fields": ["title^2","content"] } }{{/q}}]}},"_source": ["@timestamp","title","url","snippet"],"from": "{{from}}{{^from}}0{{/from}}","size": "{{size}}{{^size}}10{{/size}}","timeout": "{{timeout}}{{^timeout}}2s{{/timeout}}"}}
}