计算查询与特定文档之间的评分，提供详细的评分计算过程。
API #
GET /{index}/_explain/{id}
POST /{index}/_explain/{id}
GET /{index}/{type}/{id}/_explain
POST /{index}/{type}/{id}/_explain
API 的作用 #
该 API 用于解释为什么特定文档匹配或不匹配查询，返回：
- 文档是否匹配查询
- 评分计算过程的详细解释
- 各个评分因子的权重
- 评分分解的详细信息
Explain 的用途 #
| 用途 | 描述 |
|---|---|
| 调试查询 | 理解查询为什么匹配或不匹配 |
| 优化评分 | 查看评分权重的影响 |
| 性能分析 | 分析查询执行计划 |
| 学习机制 | 理解评分计算原理 |
API 的参数 #
路由参数 #
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
{index} | 字符串 | 必需 | 索引名称 |
{id} | 字符串 | 必需 | 文档 ID |
{type} | 字符串 | 否 | 文档类型（已弃用） |
Query String 参数 #
查询参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
q | 字符串 | 否* | - | Lucene 查询字符串语法 |
analyzer | 字符串 | 否 | - | 查询字符串的分析器 |
analyze_wildcard | 布尔值 | 否 | false | 是否分析通配符和前缀查询 |
default_operator | 枚举值 | 否 | OR | 查询字符串的默认操作符：AND、OR |
df | 字符串 | 否 | _all | 查询字符串的默认字段 |
执行参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
preference | 字符串 | 否 | random | 执行节点/分片偏好：_local、_primary 等 |
routing | 字符串 | 否 | - | 路由值 |
lenient | 布尔值 | 否 | false | 是否忽略格式化查询失败 |
字段参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
stored_fields | 列表 | 否 | - | 返回的存储字段列表 |
_source | 布尔值/列表 | 否 | true | 是否返回源字段 |
_source_excludes | 列表 | 否 | - | 排除的源字段 |
_source_includes | 列表 | 否 | - | 包含的源字段 |
请求体参数（POST） #
{
"query": { ... }
}
示例 #
基本查询解释 #
GET /my_index/_explain/1
{
"query": {
"match": {
"message": "search engine"
}
}
}
响应示例：
{
"_index": "my_index",
"_id": "1",
"matched": true,
"explanation": {
"value": 0.5753642,
"description": "weight(message:search in 0) [PerFieldSimilarity], result of:",
"details": [
{
"value": 0.5753642,
"description": "score(freq=3.0), computed as boost * idf * tf from:",
"details": [
{ "value": 2.2, "description": "boost" },
{ "value": 1.0, "description": "idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:" },
{ "value": 0.262234, "description": "tf, computed as freq / len from:" }
]
}
]
}
}
使用查询字符串 #
GET /my_index/_explain/1?q=message:search
Bool 查询解释 #
POST /my_index/_explain/1
{
"query": {
"bool": {
"must": [
{ "match": { "title": "search" } }
],
"should": [
{ "match": { "tags": "popular" } }
]
}
}
}
Filter 查询解释 #
POST /my_index/_explain/1
{
"query": {
"bool": {
"filter": [
{ "term": { "status": "published" } }
]
}
}
}
使用路由 #
GET /my_index/_explain/1?routing=user1
{
"query": {
"match": { "message": "test" }
}
}
只返回特定字段 #
GET /my_index/_explain/1?_source_includes=title,message
排除大字段 #
GET /my_index/_explain/1?_source_excludes=content,attachments
使用偏好 #
GET /my_index/_explain/1?preference=_local
不匹配文档解释 #
{
"_index": "my_index",
"_id": "1",
"matched": false,
"explanation": {
"value": 0.0,
"description": "no matching term"
}
}
响应字段说明 #
| 字段 | 描述 |
|---|---|
_index | 文档所在索引 |
_id | 文档 ID |
matched | 是否匹配查询 |
explanation | 评分解释详情 |
explanation.value | 最终评分 |
explanation.description | 评分描述 |
explanation.details | 评分分解详情 |
评分因子 #
| 因子 | 描述 |
|---|---|
| boost | 查询或字段的权重提升 |
| idf | 逆文档频率 |
| tf | 词频 |
| fieldNorm | 字段归一化因子 |
| coord | 协调因子 |
使用场景 #
场景 1：调试查询 #
GET /articles/_explain/doc123
{
"query": {
"bool": {
"must": [
{ "match": { "title": "easysearch" } }
]
}
}
}
场景 2：理解评分 #
GET /products/_explain/1
{
"query": {
"match": {
"description": "laptop computer"
}
}
}
场景景 3：优化查询 #
GET /logs/_explain/1
{
"query": {
"query_string": {
"query": "error OR warning"
}
}
}
评分解释详解 #
词频 (TF) #
计算词在文档中的出现频率：
tf = freq / sqrt(freq^2 + sumOfSquares)
逆文档频率 (IDF) #
衡量词的稀有程度：
idf = log(1 + (N - n + 0.5) / (n + 0.5))
评分公式 #
score = boost * idf * tf * fieldNorm * coord
注意事项 #
- 单文档：一次只能解释一个文档
- 性能影响：Explain 操作会增加服务器负载
- 类型已弃用：有类型的 API 已被弃用
- 真实评分：返回的评分与实际搜索的评分相同
- 不执行查询：只计算评分，不返回实际结果
