_explain 是干什么的
_explain 返回指定文档对某个查询的得分推导过程：哪一层查询、哪个词条、哪个字段各贡献了多少分。它有两个典型用途，一是确认某篇文档为什么没被搜到（看 matched），二是排查排序异常（看哪一步把分数拉开了）。search 请求里加 "explain": true 可以对每条命中附带同样的解释。
基本信息
| 接口 | GET /<index>/_explain/<id>，请求体写 query |
|---|---|
| 返回 | matched 是否命中、explanation.value 得分、description 逐层解释 |
| 便捷用法 | search 里加 "explain": true |
| 适用版本 | Elasticsearch 5.x 起默认为 BM25 打分，解释层级随打分模型变化 |
示例
示例
# 单文档解释：为什么命不中 / 得分怎么来的
GET /my-index/_explain/1
{
"query": { "match": { "message": "search" } }
}
# 检索时附带解释：注意响应体积会明显变大
GET /my-index/_search
{
"explain": true,
"size": 3,
"query": { "match": { "message": "search" } }
}典型使用场景
- 命不中排查：确认是查询条件问题还是文档缺少匹配词条
- 排序异常：同分文档过多，或某个字段权重压过其他命中
- 权重验证：调整 boost 后确认加权是否按预期生效
- 分析器核对：解释里出现的词条与预期分词结果不符时回查分析器
- 得分教学：理解 tf、idf、norm 各因子对最终分数的贡献
返回结构读法
| 返回项 | 含义 | 关注点 |
|---|---|---|
| matched | 是否命中该查询 | false 说明条件不满足，此时得分无意义 |
| explanation.value | 最终得分 | 与检索结果里的 _score 对应 |
| explanation.description | 当前层打分公式 | 从这里先判断是哪一类子查询 |
| explanation.details | 子层分解 | 逐层往下读可定位加权来源 |
文档不存在时返回 found: false 而不是报错，调试前先核对索引名与 ID；查询跨多个索引时要在 URI 里带上对应索引。
explain: true 会显著增大响应体并让查询多算一遍解释，只适合小批量排查，不要留在生产查询或压测脚本里。
得分解释的基本原理
检索打分是对每个候选文档逐一完成的，最终分数由各级子查询按权重合成：叶子查询贡献词条级分数，布尔查询把子查询分数相加或取最大，加权查询再乘上 boost。解释文本正是这棵打分树的展开，从最外层 description 往下逐层读，就能看出是哪一步把分数抬高或压低。如果 matched 为 false，说明在条件层面就没有命中，不必再分析分数。
解释文本里的字段名与查询结构一一对应，读到 tf、idf、norm、boost 这些层级就能定位是哪一步把分数拉开，理解各因子的含义比记住公式更有用。