_validate/query 是什么
_validate/query 在不读取数据的前提下校验查询结构是否合法，带 explain 参数时还会返回重写后的执行计划，用来在查询生成器、查询模板上线前先自检，避免语法错误留到线上才暴露。它的开销远低于真正执行一次检索，适合放在生成逻辑的测试环节或在排障时确认查询写法是否被正确理解。要注意它只校验结构：字段名写错仍可能返回合法，只是查不到数据。
基本信息
| 接口 | GET /<index>/_validate/query 或 /_validate/query?explain=true |
|---|---|
| 返回 | valid 布尔值；带 explain 时返回分片与重写后的查询 |
| 开销 | 不读取数据，明显低于真实检索 |
| 局限 | 不校验字段是否存在与类型是否匹配 |
| 适用 | 查询生成器、查询模板与版本升级前的自检 |
典型使用场景
- 查询生成器自检：拼接出的 DSL 在发送前先校验一次结构
- 模板回归：改动查询模板后跑一遍校验，避免语法回退
- 确认查询理解：对比 explain 返回的重写结果与预期是否一致
- 升级前检查：提前发现新旧版本对某类语法的支持差异
- 排障辅助：报错时用校验接口区分是语法问题还是数据问题
两种用法
两种用法
GET /my-index/_validate/query?explain=true
{
"query": { "match": { "title": "test" } }
}
# 只看合法性，不返回执行计划
GET /my-index/_validate/query
{
"query": { "bool": { "must": [ { "term": { "status": "open" } } ] } }
}返回内容读法
| 字段 | 含义 | 读法 |
|---|---|---|
| valid | 结构是否合法 | false 时结合报错定位语法问题 |
| _shards | 分片执行情况 | 带 explain 时返回 |
| explanations | 各分片的计划 | 看 rewritten 是否符合预期 |
| rewritten | 重写后的查询 | 判断查询是否被正确理解 |
| error | 报错信息 | 定位非法字段或类型 |
校验通过只代表结构合法。字段名写错或类型不匹配时仍可能返回 valid 为 true 却查不到数据，字段层面的核对要用 mapping 或 field_caps 接口。
带 explain 的输出会执行查询重写，空索引与有数据索引的计划可能不同，评估计划时请用有代表性的索引。