---
title: "异步搜索等待完成超时上限"
date: 2026-03-30
lastmod: 2026-03-30
description: "控制异步搜索请求中 wait_for_completion_timeout 参数最大值的配置项说明"
tags: ["异步搜索", "超时控制", "API安全"]
summary: "配置项作用 #  async_search.max_wait_for_completion_timeout 配置项限制异步搜索请求中 wait_for_completion_timeout 参数的最大值。该配置项作为安全机制，防止客户端设置过长的等待时间导致资源占用。
配置项类型 #  该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。
默认值 #  1m（1分钟） 是否必需 #  可选配置项
取值范围 #  正数时间值（如 10s、1m、5m 等） 工作原理 #  异步搜索 API 支持两种执行模式：
1. 异步模式（默认）
POST /my-index/_async_search { "query": { "match_all": {} } } # 立即返回异步搜索ID，用户稍后查询结果 2. 等待模式
POST /my-index/_async_search?wait_for_completion_timeout=30s { "query": { "match_all": {} } } # 最多等待30秒，如果搜索完成则返回结果，否则返回异步ID wait_for_completion_timeout 参数允许客户端指定等待搜索完成的时间。此配置项限制该参数的最大值，防止客户端设置过长的等待时间。
使用示例 #  # 默认配置（1分钟） async_search.max_wait_for_completion_timeout: 1m # 缩短上限（30秒） async_search."
---


## 配置项作用

`async_search.max_wait_for_completion_timeout` 配置项限制异步搜索请求中 `wait_for_completion_timeout` 参数的最大值。该配置项作为安全机制，防止客户端设置过长的等待时间导致资源占用。

## 配置项类型

该配置项为**动态配置**，可以在运行时通过集群更新 API 进行修改，无需重启节点。

## 默认值

```
1m（1分钟）
```

## 是否必需

**可选配置项**

## 取值范围

```
正数时间值（如 10s、1m、5m 等）
```

## 工作原理

异步搜索 API 支持两种执行模式：

**1. 异步模式（默认）**
```bash
POST /my-index/_async_search
{
  "query": { "match_all": {} }
}
# 立即返回异步搜索ID，用户稍后查询结果
```

**2. 等待模式**
```bash
POST /my-index/_async_search?wait_for_completion_timeout=30s
{
  "query": { "match_all": {} }
}
# 最多等待30秒，如果搜索完成则返回结果，否则返回异步ID
```

`wait_for_completion_timeout` 参数允许客户端指定等待搜索完成的时间。此配置项限制该参数的最大值，防止客户端设置过长的等待时间。

## 使用示例

```yaml
# 默认配置（1分钟）
async_search.max_wait_for_completion_timeout: 1m

# 缩短上限（30秒）
async_search.max_wait_for_completion_timeout: 30s

# 延长上限（5分钟）
async_search.max_wait_for_completion_timeout: 5m
```

## 行为示例

```bash
# 场景：async_search.max_wait_for_completion_timeout = 1m

# 请求1：wait_for_completion_timeout=10s → 等待10秒
POST /index/_async_search?wait_for_completion_timeout=10s

# 请求2：wait_for_completion_timeout=1m → 等待1分钟
POST /index/_async_search?wait_for_completion_timeout=1m

# 请求3：wait_for_completion_timeout=10m → 实际只等待1分钟（被限制）
POST /index/_async_search?wait_for_completion_timeout=10m
```

## API 响应

**等待时间内搜索完成：**
```json
{
  "id": "Fm_QRn8BRiWfSeIP-2Xk7A",
  "is_partial": false,
  "is_running": false,
  "hits": { ... }
}
```

**等待超时：**
```json
{
  "id": "Fm_QRn8BRiWfSeIP-2Xk7A",
  "is_partial": true,
  "is_running": true
}
```

## 推荐设置建议

**生产环境建议**：根据业务需求合理设置

**推荐配置：**

```yaml
# 快速查询场景（30秒）
async_search.max_wait_for_completion_timeout: 30s

# 一般场景（1分钟）
async_search.max_wait_for_completion_timeout: 1m

# 复杂查询场景（5分钟）
async_search.max_wait_for_completion_timeout: 5m
```

**设置考虑因素：**

1. **用户体验**：较短的等待时间可以更快地返回响应
2. **资源占用**：等待期间会占用连接和线程资源
3. **查询复杂度**：确保大部分查询能在时限内完成
4. **API安全**：防止恶意客户端设置过长的等待时间

## 相关配置项

| 配置项 | 作用 | 默认值 |
|-------|------|-------|
| `async_search.max_search_running_time` | 搜索最大运行时间 | 12小时 |
| `async_search.max_keep_alive` | 结果最大保留时间 | 5天 |
| `async_search.node_concurrent_running_searches` | 并发搜索数量限制 | 20 |

## 工作流程

```
客户端提交异步搜索
        │
        ▼
检查 wait_for_completion_timeout
        │
        ▼
与 max_wait_for_completion_timeout 比较
        │
    ┌───┴────┐
    │        │
超时       未超时
    │        │
    ▼        ▼
截断为最大值   使用原值
    │        │
    └───┬────┘
        ▼
   等待搜索完成
        │
    ┌───┴────────────┐
    │                │
超时前完成        超时
    │                │
    ▼                ▼
返回完整结果      返回异步ID
(搜索仍在运行)
```

## 注意事项

1. **动态更新**：修改此配置后立即生效，仅影响新提交的异步搜索请求
2. **不影响搜索执行**：此配置只控制等待时间，不影响搜索的最大运行时间
3. **连接管理**：等待期间会占用 HTTP 连接，需确保服务器有足够的连接处理能力
4. **客户端超时**：客户端可能有自己的超时设置，需协调配置
5. **合理设置**：设置过短可能导致用户需要额外的轮询请求，设置过长则影响服务器资源利用