文章二十七：ElasticSearch ES查询模板（Search Template）高效复用实战

在Elasticsearch（ES）开发中，同步查询和异步查询是两种核心场景，而查询模板（Search Template）作为通用复用工具，可无缝适配两种查询方式，无需重复编写相似查询逻辑，大幅提升开发效率、降低语法错误概率。本文将以通用模板 general_page_study_template 为例，完整讲解模板的创建、测试（含关键的模拟执行流程）、同步/异步调用及基础管理，全程贴合生产环境实战，所有命令可直接复制执行。

一、核心认知：查询模板的通用性

重点说明：ES查询模板并非专属某一种查询方式，而是同步查询、异步查询均可通用。其核心价值在于将固定查询逻辑（如查询结构、排序框架、聚合规则）封装为模板，动态参数（如查询字段、查询值、返回条数）可灵活传入，实现"一份模板，多场景复用"，同时便于后续统一维护和逻辑调整。

二、第一步：创建通用查询模板 general_page_study_template

我们创建一个适配常规业务场景的通用模板，支持动态传入查询字段、查询值、返回条数、排序字段及排序方向，可直接用于同步和异步查询（后续同步查询示例使用index_test 索引，与请求格式对应）。

1. 创建命令（可直接执行）

复制代码

PUT _scripts/general_page_study_template { "script": { "lang": "mustache", // ES查询模板默认语言，无需修改 "source": { // 固定逻辑：开启总命中数统计（同步、异步查询均常用） "track_total_hits": true, // 动态查询逻辑：查询字段和查询值由参数传入 "query": { "match": { "{``{query_field}}": "{``{query_param}}" // 动态变量：查询字段、查询值 } }, // 动态参数：返回条数，由参数传入 "size": "{``{return_size}}", // 动态排序：排序字段和排序方向由参数传入 "sort": [ { "{``{sort_field}}": { "order": "{``{sort_order}}" // 动态变量：排序字段、排序方向（asc/desc） } } ] } } }

2. 创建说明

模板名称 general_page_study_template 为自定义，包含"general"标识，明确其适配同步、异步两种场景；
动态变量用 {``{变量名}} 标识，后续调用时需通过 params 参数传入具体值，变量与参数需一一对应；
固定逻辑（如 track_total_hits: true）可根据业务需求调整，封装后所有调用该模板的查询都会沿用该逻辑，无需单独修改。

三、第二步：模板测试（关键步骤）------ 验证模板是否生效

模板创建后，不能直接用于业务查询，需先完成测试，确保模板可正常解析、参数可正确填充。测试分为3个步骤，从基础验证到模拟执行，再到真实调用，层层递进，避免后续业务报错。

1. 基础验证：查询模板是否创建成功

这是最基础的测试步骤，用于确认模板已成功保存到ES集群中。

查询命令

复制代码

GET _scripts/general_page_study_template

结果说明

若返回完整的模板内容（与创建时的JSON结构一致），则说明模板创建成功；
若返回 index_not_found_exception 或 missing 相关提示，则说明模板创建失败，需重新执行创建命令，检查语法是否正确（如JSON格式、括号匹配）。

2. 核心测试：模拟执行（Dry Run）------ 验证模板渲染是否正确

模拟执行（也叫模板渲染）是最关键的测试步骤，核心作用是：不真正查询索引数据，仅将模板中的动态变量替换为传入的参数，生成最终的查询DSL，用于验证模板语法、参数填充是否符合预期，避免真实查询时出现语法错误。

模拟执行命令（render渲染）

复制代码

POST _render/template { "id": "general_page_study_template", // 指定要测试的模板名称 "params": { "query_field": "title", // 传入动态参数：查询字段 "query_param": "Elasticsearch", // 传入动态参数：查询值 "return_size": 10, // 传入动态参数：返回条数 "sort_field": "create_time", // 传入动态参数：排序字段 "sort_order": "desc" // 传入动态参数：排序方向 } }

模拟执行结果（正确示例）

复制代码

{ "template_output": { "track_total_hits": true, "query": { "match": { "title": "Elasticsearch" // 动态变量已正确替换为传入参数 } }, "size": 10, "sort": [ { "create_time": { "order": "desc" } } ] } }

结果验证要点

所有 {``{变量名}} 均已替换为传入的 params 参数，无残留变量；
生成的查询DSL语法正确（如括号匹配、字段格式正确）；
查询结构、排序规则与模板设计一致，无异常缺失或多余内容。

若模拟执行失败（如返回语法错误、变量未替换），需检查模板语法（如 {``{变量名}} 书写是否正确）、传入的 params 参数是否完整（无遗漏变量）。

3. 最终验证：真实查询调用测试（同步+异步）

模拟执行通过后，需通过真实查询（同步、异步各一次），验证模板可正常适配两种场景，能成功查询到数据。

（1）同步查询调用测试（正确格式：GET index_test/_search/template）

同步查询调用模板的标准格式为 GET 索引名/_search/template，传入模板ID和参数，验证能否正常返回数据，以下使用 index_test 索引对应标准请求格式。

复制代码

GET index_test/_search/template { "id": "general_page_study_template", // 指定要调用的模板名称 "params": { "query_field": "title", "query_param": "Elasticsearch", "return_size": 10, "sort_field": "create_time", "sort_order": "desc" } }

成功标志：返回正常的查询结果（包含 hits 数据、总命中数），无语法错误、无参数解析错误。

（2）异步查询调用测试

在异步查询中调用同一模板，只需添加异步专属参数（_async_search、wait_for_completion_timeout、keep_alive），参数传入逻辑与同步查询一致，索引可根据业务实际调整（此处沿用常规 page_study_index 示例）。

复制代码

POST page_study_index/_async_search?wait_for_completion_timeout=1ms&keep_alive=10m { "id": "general_page_study_template", "params": { "query_field": "title", "query_param": "Elasticsearch", "return_size": 100, "sort_field": "create_time", "sort_order": "desc" } }

成功标志：返回异步查询唯一ID（如下所示），标识模板调用成功，查询任务已提交到后台执行。

复制代码

{ "id": "FklMSnZpWFYzUUU2RmlZUlk4dDZOOVEdbmZWM1YwaEJSUVNSenVIeUxyazBGUToxNTQ1MTA", "is_running": true, "progress": 0, "expiration_time_in_millis": 1715740800000 }

（3）基于模板的批量查询测试

ES批量查询（msearch）可结合查询模板使用，核心优势是：复用同一模板逻辑，一次性传入多组参数，执行多个查询任务，无需重复编写模板调用代码，大幅提升批量查询效率。批量查询支持同步执行，以下结合 index_test 索引，演示基于模板的批量查询实战。

批量查询核心逻辑：通过 /_msearch/template 接口，每组查询需指定索引（可统一指定或单独指定），并传入模板ID和对应参数，多组查询用换行分隔。

批量查询命令（同步执行）

复制代码

POST index_test/_msearch/template
{}
{
  "id": "general_page_study_template",
  "params": {
    "query_field": "title",
    "query_param": "Elasticsearch",
    "return_size": 5,
    "sort_field": "create_time",
    "sort_order": "desc"
  }
}
{}
{
  "id": "general_page_study_template",
  "params": {
    "query_field": "content",
    "query_param": "查询模板",
    "return_size": 8,
    "sort_field": "update_time",
    "sort_order": "asc"
  }
}
{}
{
  "id": "general_page_study_template",
  "params": {
    "query_field": "author",
    "query_param": "admin",
    "return_size": 10,
    "sort_field": "create_time",
    "sort_order": "desc"
  }
}

批量查询说明

请求格式：POST 索引名/_msearch/template，若多组查询对应不同索引，可在每组查询前单独指定索引（如 {"index": "other_index"}）；
每组查询需以空JSON对象 {} 开头，后续跟上模板调用的JSON（包含 id 和 params），多组查询用换行分隔；
每组查询可传入不同参数（如不同查询字段、查询值、排序规则），但均复用 general_page_study_template 模板的固定逻辑，无需重复编写查询结构。

成功标志

返回数组形式的查询结果，每组结果对应一组参数的查询，包含各自的 hits 数据、总命中数，无语法错误、无参数解析错误，示例如下（简化版）：

复制代码

{ "responses": [ { "took": 12, "timed_out": false, "hits": { "total": {"value": 20, "relation": "eq"}, "hits": [/* 第一条查询结果数据 */] } }, { "took": 8, "timed_out": false, "hits": { "total": {"value": 15, "relation": "eq"}, "hits": [/* 第二条查询结果数据 */] } }, { "took": 10, "timed_out": false, "hits": { "total": {"value": 8, "relation": "eq"}, "hits": [/* 第三条查询结果数据 */] } } ] }

四、第三步：模板的基础管理（查询、修改、删除）

模板创建并测试通过后，日常运维中需根据业务需求进行管理，以下是常用操作，均围绕 general_page_study_template 模板展开。

1. 查询模板（重复基础验证）

复制代码

GET _scripts/general_page_study_template

2. 修改模板（调整通用逻辑）

当查询逻辑需要调整（如新增聚合字段），直接覆盖原模板即可，修改后所有后续调用（同步/异步）都会同步生效，无需逐一修改调用代码。

复制代码

PUT _scripts/general_page_study_template { "script": { "lang": "mustache", "source": { "track_total_hits": true, "query": { "match": { "{``{query_field}}": "{``{query_param}}" } }, "size": "{``{return_size}}", "sort": [ { "{``{sort_field}}": { "order": "{``{sort_order}}" } } ], // 新增聚合逻辑（同步、异步查询均会生效） "aggs": { "group_by_{``{sort_field}}": { "terms": { "field": "{``{sort_field}}" } } } } } }

修改后建议重新执行"模拟执行"和"真实调用测试"，确保修改后的模板无语法错误。

3. 删除模板（无需使用时清理）

当模板不再使用时，可执行删除命令，释放集群资源。

复制代码

DELETE _scripts/general_page_study_template

五、模板使用注意事项（同步、异步通用）

模板逻辑需通用化：创建模板时，避免添加同步或异步专属参数（如异步的 keep_alive、同步的实时响应参数），确保模板可无缝适配两种查询场景；
参数校验不可少：调用模板时，需确保 params 中的参数完整、格式正确（如 return_size 需为数字、sort_order 需为 asc 或desc），否则会导致查询失败；
模拟执行必做：每次创建或修改模板后，务必先执行模拟执行（Dry Run），验证模板渲染是否正确，避免真实查询时出现语法错误；
命名规范：建议模板名称包含"general"标识和索引相关信息，便于区分通用模板与专属模板，避免混淆（如 general_user_index_template）；
同步调用格式规范：同步查询调用模板需使用标准格式 GET 索引名/_search/template，避免使用错误的请求方式或路径，确保调用成功。

六、完整流程总结

围绕 general_page_study_template 模板，ES查询模板的完整实战流程如下，可直接用于生产环境落地：

创建模板：执行 PUT _scripts/general_page_study_template，封装通用查询逻辑；
基础验证：执行 GET _scripts/general_page_study_template，确认模板创建成功；
模拟执行：执行 POST _render/template，验证模板渲染和参数填充是否正确；
真实调用：同步查询使用 GET index_test/_search/template 调用，异步查询使用 POST 索引名/_async_search 调用，验证功能正常；
日常管理：根据业务需求，执行查询、修改、删除模板操作。

七、总结

ES查询模板 general_page_study_template 作为同步、异步查询的通用工具，其核心价值在于实现查询逻辑的复用与统一维护，尤其适合多个查询（无论同步还是异步）逻辑相似、仅参数不同的业务场景。通过"创建-测试-调用-管理"的完整流程，可确保模板稳定生效，大幅提升开发效率、降低运维成本，同时避免重复编写查询语句带来的语法错误，尤其是注意同步查询调用模板的标准格式，让ES查询开发更规范、更高效。