---
title: "默认允许部分结果配置"
date: 2026-01-27
lastmod: 2026-01-27
description: "控制默认允许部分结果的配置项说明"
tags: ["搜索配置", "容错机制", "查询行为"]
summary: "配置项作用 #  search.default_allow_partial_results 配置项控制在搜索请求中未指定 allow_partial_results 参数时的默认行为。当查询涉及多个分片时，如果某些分片失败，此配置决定是返回部分结果还是整个查询失败。
配置项类型 #  该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。
默认值 #  true（允许部分结果） 是否必需 #  可选配置项（有默认值）
取值范围 #  true - 允许返回部分结果 false - 不允许部分结果，有分片失败则整个查询失败 配置格式 #  # 默认配置（允许部分结果） search.default_allow_partial_results: true # 不允许部分结果 search.default_allow_partial_results: false 相关配置项 #     配置项 默认值 说明     search.default_allow_partial_results true 默认允许部分结果   search.default_search_timeout 60s 默认搜索超时    工作原理 #  部分结果处理机制：
┌─────────────────────────────────────────────────────────────────┐ │ 部分结果处理流程 │ └─────────────────────────────────────────────────────────────────┘ 搜索请求（涉及多个分片） │ ├── 分片 1 执行 ✓ ├── 分片 2 执行 ✓ ├── 分片 3 执行 ✗ (失败) └── 分片 4 执行 ✓ │ ▼ 检查 allow_partial_results │ ├── true（允许部分结果） │ │ │ └── 返回成功分片的结果 │ ├── 返回 3 个分片的数据 │ ├── 标记为部分结果 │ └── 警告: "shard failures" │ └── false（不允许部分结果） │ └── 返回失败 ├── 整个查询失败 ├── 抛出异常 └── 返回分片失败信息 部分结果示例 #  部分结果响应示例: { "took": 15, "timed_out": false, "_shards": { "total": 5, "successful": 4, "skipped": 0, "failed": 1 }, "hits": { "total": 100, "hits": [."
---


## 配置项作用

`search.default_allow_partial_results` 配置项控制在搜索请求中未指定 `allow_partial_results` 参数时的默认行为。当查询涉及多个分片时，如果某些分片失败，此配置决定是返回部分结果还是整个查询失败。

## 配置项类型

该配置项为**动态配置**，可以在运行时通过集群设置 API 进行修改。

## 默认值

```
true（允许部分结果）
```

## 是否必需

**可选配置项**（有默认值）

## 取值范围

```
true  - 允许返回部分结果
false - 不允许部分结果，有分片失败则整个查询失败
```

## 配置格式

```yaml
# 默认配置（允许部分结果）
search.default_allow_partial_results: true

# 不允许部分结果
search.default_allow_partial_results: false
```

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `search.default_allow_partial_results` | true | 默认允许部分结果 |
| `search.default_search_timeout` | 60s | 默认搜索超时 |

## 工作原理

部分结果处理机制：

```
┌─────────────────────────────────────────────────────────────────┐
│                    部分结果处理流程                               │
└─────────────────────────────────────────────────────────────────┘

搜索请求（涉及多个分片）
    │
    ├── 分片 1 执行 ✓
    ├── 分片 2 执行 ✓
    ├── 分片 3 执行 ✗ (失败)
    └── 分片 4 执行 ✓
        │
        ▼
检查 allow_partial_results
    │
    ├── true（允许部分结果）
    │   │
    │   └── 返回成功分片的结果
    │       ├── 返回 3 个分片的数据
    │       ├── 标记为部分结果
    │       └── 警告: "shard failures"
    │
    └── false（不允许部分结果）
        │
        └── 返回失败
            ├── 整个查询失败
            ├── 抛出异常
            └── 返回分片失败信息
```

## 部分结果示例

```
部分结果响应示例:

{
  "took": 15,
  "timed_out": false,
  "_shards": {
    "total": 5,
    "successful": 4,
    "skipped": 0,
    "failed": 1
  },
  "hits": {
    "total": 100,
    "hits": [...]
  },
  "failures": [
    {
      "shard": 2,
      "index": "test",
      "reason": {
        "type": "search_context_missing_exception",
        "reason": "No search context found"
      }
    }
  ]
}

说明:
- total: 5 个分片
- successful: 4 个成功
- failed: 1 个失败
- 返回部分数据: 4 个分片的结果
```

## 使用场景

### 1. 默认配置（推荐）

```yaml
search.default_allow_partial_results: true
```

**适用场景：**
- 大多数生产环境
- 需要高可用性
- 部分数据比无数据好
- 分布式环境

### 2. 不允许部分结果

```yaml
search.default_allow_partial_results: false
```

**适用场景：**
- 需要完整数据
- 数据准确性要求高
- 可以接受查询失败
- 监控分片健康

### 3. 请求级别覆盖

```bash
# 默认允许部分结果
GET /_search
{
  "query": { "match_all": {} }
}

# 明确不允许部分结果
GET /_search?allow_partial_results=false
{
  "query": { "match_all": {} }
}
```

## 推荐设置建议

| 场景 | 推荐值 | 说明 |
|-----|-------|------|
| 生产环境 | true | 高可用性优先 |
| 日志分析 | true | 部分数据可接受 |
| 财务数据 | false | 完整性优先 |
| 实时搜索 | true | 快速响应 |
| 数据统计 | false | 需要准确数据 |

## 容错策略对比

```
两种容错策略:

允许部分结果 (true):
    优点:
        ✓ 高可用性
        ✓ 部分数据可用
        ✓ 不会因个别分片失败而全部失败

    缺点:
        ✗ 数据不完整
        ✗ 可能影响统计准确性
        ✗ 需要处理失败信息

不允许部分结果 (false):
    优点:
        ✓ 数据完整性
        ✓ 统计准确性
        ✓ 明确的失败信息

    缺点:
        ✗ 可用性降低
        ✗ 单个分片失败导致全部失败
        ✗ 用户体验较差
```

## 请求级别控制

```
查询请求中的参数控制:

1. 不指定参数（使用默认）
   GET /_search
   {
     "query": { "match_all": {} }
   }
   → 使用 default_allow_partial_results 值

2. 明确指定允许
   GET /_search?allow_partial_results=true
   {
     "query": { "match_all": {} }
   }
   → 允许部分结果

3. 明确指定不允许
   GET /_search?allow_partial_results=false
   {
     "query": { "match_all": {} }
   }
   → 不允许部分结果
```

## 动态配置示例

```bash
# 更改全局默认值
PUT /_cluster/settings
{
  "transient": {
    "search.default_allow_partial_results": false
  }
}

# 恢复默认值
PUT /_cluster/settings
{
  "transient": {
    "search.default_allow_partial_results": null
  }
}

# 查看当前配置
GET /_cluster/settings?filter_path=*.search.default_allow_partial_results
```

## 监控建议

```bash
# 查看当前配置
GET /_cluster/settings?filter_path=*.search.default_allow_partial_results

# 查看分片失败情况
GET /_search
{
  "query": { "match_all": {} }
}
# 检查响应中的 _shards.failed 和 failures 字段

# 查看集群健康
GET /_cluster/health

# 查看未分配分片
GET /_cat/shards?v | grep UNASSIGNED
```

## 错误处理

```
处理分片失败的最佳实践:

1. 监控失败响应
   - 检查 _shards.failed
   - 查阅 failures 数组
   - 记录失败原因

2. 重试策略
   - 对于临时性错误，重试查询
   - 指数退避重试
   - 限制重试次数

3. 降级策略
   - 返回部分数据并警告
   - 使用缓存数据
   - 返回上次成功的结果

4. 告警机制
   - 分片失败率过高时告警
   - 自动触发分片修复
   - 通知运维人员
```

## 配置示例

```yaml
# 场景 1: 高可用性优先
cluster.name: high-availability-cluster
search.default_allow_partial_results: true

# 场景 2: 数据完整性优先
cluster.name: accuracy-cluster
search.default_allow_partial_results: false

# 场景 3: 混合策略
cluster.name: mixed-cluster
search.default_allow_partial_results: true
# 在需要完整性的查询中明确指定:
# GET /_search?allow_partial_results=false
```

## 常见分片失败原因

```
导致分片失败的常见原因:

1. 分片未分配
    - 节点故障
    - 分片正在迁移
    - 磁盘空间不足

2. 分片正在恢复
    - 节点重启后
    - 新副本创建中

3. 查询超时
    - 查询太复杂
    - 资源不足

4. 脚本错误
    - 脚本语法错误
    - 运行时错误

5. 内存不足
    - 字段数据缓存溢出
    - JVM 堆内存不足

应对措施:
    - 修复未分配分片
    - 优化查询性能
    - 增加节点资源
    - 修复脚本错误
```

## 注意事项

1. **动态更新**：此配置为动态配置，可在线修改
2. **请求覆盖**：可以在查询请求中覆盖此设置
3. **数据完整性**：需要根据业务需求选择
4. **监控失败**：应监控分片失败情况
5. **用户体验**：允许部分结果可提高可用性
6. **与重试配合**：配合重试机制使用