---
title: "搜索默认保持时间配置"
date: 2026-03-03
lastmod: 2026-03-03
description: "控制搜索上下文默认保持时间的配置项说明"
tags: ["搜索配置", "滚动查询", "超时配置"]
summary: "配置项作用 #  search.default_keep_alive 配置项指定搜索上下文（Scroll Context）的默认保持时间。当执行滚动查询时，此配置决定搜索结果在服务器上保持有效的时长。
配置项类型 #  该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。
默认值 #  5m（5分钟） 是否必需 #  可选配置项（有默认值）
取值范围 #  1m ~ search.max_keep_alive 配置格式 #  # 默认配置 search.default_keep_alive: 5m # 较短时间 search.default_keep_alive: 1m # 较长时间 search.default_keep_alive: 10m # 禁用滚动查询 search.default_keep_alive: 0s 工作原理 #  滚动查询保持时间控制搜索上下文的有效期：
┌─────────────────────────────────────────────────────────┐ │ 初始化滚动查询 │ │ GET /my_index/_search?scroll=5m │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌───────┴────────┐ │ │ 指定 scroll 参数 未指定 scroll │ │ ▼ ▼ 使用指定的时间 使用 default_keep_alive (scroll=5m) (默认 5m) │ │ ▼ ▼ ┌───────┴────────┐ │ 创建滚动上下文 │ │ 设置过期时间 │ └───────┬────────┘ │ ▼ 持续检查是否过期 │ ┌───────┴────────┐ │ │ 未过期（续期） 过期（清理） │ │ ▼ ▼ 继续使用上下文 上下文被清理 使用示例 #  基本滚动查询："
---


## 配置项作用

`search.default_keep_alive` 配置项指定搜索上下文（Scroll Context）的默认保持时间。当执行滚动查询时，此配置决定搜索结果在服务器上保持有效的时长。

## 配置项类型

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

## 默认值

```
5m（5分钟）
```

## 是否必需

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

## 取值范围

```
1m ~ search.max_keep_alive
```

## 配置格式

```yaml
# 默认配置
search.default_keep_alive: 5m

# 较短时间
search.default_keep_alive: 1m

# 较长时间
search.default_keep_alive: 10m

# 禁用滚动查询
search.default_keep_alive: 0s
```

## 工作原理

滚动查询保持时间控制搜索上下文的有效期：

```
┌─────────────────────────────────────────────────────────┐
│              初始化滚动查询                                │
│      GET /my_index/_search?scroll=5m                      │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
                ┌───────┴────────┐
                │                 │
            指定 scroll 参数      未指定 scroll
                │                 │
                ▼                 ▼
        使用指定的时间        使用 default_keep_alive
        (scroll=5m)           (默认 5m)
                │                 │
                ▼                 ▼
        ┌───────┴────────┐
        │  创建滚动上下文  │
        │  设置过期时间   │
        └───────┬────────┘
                │
                ▼
        持续检查是否过期
                │
        ┌───────┴────────┐
        │                 │
    未过期（续期）      过期（清理）
        │                 │
        ▼                 ▼
    继续使用上下文     上下文被清理
```

## 使用示例

**基本滚动查询：**

```bash
# 使用默认保持时间
GET /my_index/_search?scroll
{
  "size": 1000,
  "query": {
    "match_all": {}
  }
}

# 使用自定义保持时间
GET /my_index/_search?scroll=10m
{
  "size": 1000,
  "query": {
    "match_all": {}
  }
}
```

**动态修改默认值：**

```bash
# 修改默认保持时间为 10 分钟
PUT /_cluster/settings
{
  "transient": {
    "search.default_keep_alive": "10m"
  }
}
```

## 推荐设置建议

**生产环境建议**：根据数据量和处理速度设置

| 场景 | 推荐配置 | 说明 |
|-----|---------|------|
| 默认 | 5m | 通用场景 |
| 快速处理 | 1-2m | 减少资源占用 |
| 大数据导出 | 10-30m | 给予充足处理时间 |
| 实时搜索 | 1m | 快速释放资源 |

## 与 max_keep_alive 的关系

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `search.default_keep_alive` | 5m | 默认保持时间 |
| `search.max_keep_alive` | 24h | 最大保持时间 |

**限制关系：**

```
default_keep_alive ≤ max_keep_alive
```

## 常见问题

**问题 1：滚动上下文过期**

```
search_context_missing_exception: No search context found for id
```

**可能原因：**
1. 处理时间超过保持时间
2. `default_keep_alive` 设置过短

**解决方案：**

1. **增加保持时间**
```bash
PUT /_cluster/settings
{
  "transient": {
    "search.default_keep_alive": "10m"
  }
}
```

2. **请求时指定更长的时间**
```bash
GET /my_index/_search?scroll=10m
```

3. **优化处理速度**
```javascript
// 减少每批数据处理时间
// 及时续期滚动上下文
```

**问题 2：资源占用过高**

**可能原因：**
- `default_keep_alive` 设置过长
- 未及时清理滚动上下文

**解决方案：**

1. **减少默认保持时间**
```bash
PUT /_cluster/settings
{
  "transient": {
    "search.default_keep_alive": "2m"
  }
}
```

2. **及时清理上下文**
```bash
# 完成后清理
DELETE /_search/scroll/_all

# 或清理特定的上下文
DELETE /_search/scroll/scroll_id
```

3. **使用 search_after 替代**
```json
GET /my_index/_search
{
  "size": 100,
  "query": {"match_all": {}},
  "sort": [{"_id": "asc"}],
  "search_after": ["last_id"]
}
```

## 动态修改

```bash
# 临时修改
PUT /_cluster/settings
{
  "transient": {
    "search.default_keep_alive": "10m"
  }
}

# 持久修改
PUT /_cluster/settings
{
  "persistent": {
    "search.default_keep_alive": "10m"
  }
}

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

## 查看当前配置

```bash
# 查看当前设置
GET /_cluster/settings?flat_settings=true

# 查看特定配置
GET /_cluster/settings?filter_path=*.search.default_keep_alive
```

## 监控建议

```bash
# 查看活跃的滚动上下文
GET /_nodes/stats/indices/search?filter_path=**.open_contexts

# 查看滚动查询统计
GET /_cat/nodes?v&h=name,scroll_current,scroll_total
```

**健康阈值：**

| 指标 | 健康 | 警告 | 严重 |
|-----|------|------|------|
| open_contexts | < 100 | 100-400 | > 400 |
| scroll_current | < 50 | 50-200 | > 200 |

## 性能优化建议

**1. 合理设置保持时间**

```yaml
# 根据数据处理速度设置
# 如果每批处理需要 30 秒，设置 2-3 分钟的缓冲
search.default_keep_alive: 2m
```

**2. 及时清理上下文**

```javascript
// 应用层示例
try {
  do {
    result = client.scroll({
      scroll: '5m',
      scroll_id: scrollId
    });

    // 处理数据...

    if (result.hits.hits.length === 0) {
      break;
    }

  } while (true);

} finally {
  // 务必清理
  client.clearScroll({ scroll_id: scrollId });
}
```

**3. 使用替代方案**

```json
// 使用 search_after 进行深分页
GET /my_index/_search
{
  "size": 100,
  "query": {"match_all": {}},
  "sort": [{"timestamp": "asc"}],
  "search_after": [1609459200000]
}
```

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `search.max_keep_alive` | 24h | 最大保持时间 |
| `search.max_open_scroll_context` | 500 | 最大打开滚动上下文数 |
| `search.keep_alive_interval` | 1m | 清理检查间隔 |

## 注意事项

1. **动态更新**：此配置为动态配置，可在线修改
2. **资源占用**：每个滚动上下文占用内存
3. **及时清理**：使用完毕后务必清理上下文
4. **合理设置**：根据处理速度设置合适的时间
5. **替代方案**：考虑使用 search_after 替代滚动查询