---
title: "查询解释"
date: 2026-03-11
lastmod: 2026-03-11
description: "计算查询与特定文档之间的评分，提供详细的评分解释"
tags: ["搜索", "查询调试", "评分解释"]
summary: "计算查询与特定文档之间的评分，提供详细的评分计算过程。
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": { ."
---


计算查询与特定文档之间的评分，提供详细的评分计算过程。

## 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）

```json
{
  "query": { ... }
}
```

## 示例

### 基本查询解释

```bash
GET /my_index/_explain/1
{
  "query": {
    "match": {
      "message": "search engine"
    }
  }
}
```

**响应示例：**

```json
{
  "_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:" }
        ]
      }
    ]
  }
}
```

### 使用查询字符串

```bash
GET /my_index/_explain/1?q=message:search
```

### Bool 查询解释

```bash
POST /my_index/_explain/1
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "search" } }
      ],
      "should": [
        { "match": { "tags": "popular" } }
      ]
    }
  }
}
```

### Filter 查询解释

```bash
POST /my_index/_explain/1
{
  "query": {
    "bool": {
      "filter": [
        { "term": { "status": "published" } }
      ]
    }
  }
}
```

### 使用路由

```bash
GET /my_index/_explain/1?routing=user1
{
  "query": {
    "match": { "message": "test" }
  }
}
```

### 只返回特定字段

```bash
GET /my_index/_explain/1?_source_includes=title,message
```

### 排除大字段

```bash
GET /my_index/_explain/1?_source_excludes=content,attachments
```

### 使用偏好

```bash
GET /my_index/_explain/1?preference=_local
```

### 不匹配文档解释

```json
{
  "_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：调试查询

```bash
GET /articles/_explain/doc123
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "easysearch" } }
      ]
    }
  }
}
```

### 场景 2：理解评分

```bash
GET /products/_explain/1
{
  "query": {
    "match": {
      "description": "laptop computer"
    }
  }
}
```

### 场景景 3：优化查询

```bash
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
```

## 注意事项

1. **单文档**：一次只能解释一个文档
2. **性能影响**：Explain 操作会增加服务器负载
3. **类型已弃用**：有类型的 API 已被弃用
4. **真实评分**：返回的评分与实际搜索的评分相同
5. **不执行查询**：只计算评分，不返回实际结果