---
title: "持久化异步搜索失败结果"
date: 2026-03-17
lastmod: 2026-03-17
description: "控制是否将失败的异步搜索结果持久化到系统索引的配置项说明"
tags: ["异步搜索", "错误处理", "数据持久化"]
summary: "配置项作用 #  async_search.persist_search_failures 配置项控制是否将执行失败的异步搜索结果持久化到系统索引（.async-search）中。默认情况下，只有成功执行的异步搜索结果才会被持久化。
配置项类型 #  该配置项为动态配置，可以在运行时通过集群更新 API 进行修改，无需重启节点。
默认值 #  false（不持久化失败结果） 是否必需 #  可选配置项
配置值说明 #     值 说明     true 持久化所有异步搜索结果，包括失败的搜索   false 仅持久化成功的异步搜索结果（默认）    工作原理 #  当异步搜索执行失败时：
设置为 false（默认）：
搜索失败 → 不保存结果 → 客户端获取错误 → 结果不被保留 设置为 true：
搜索失败 → 保存失败状态 → 可通过异步搜索ID查询错误信息 失败状态示例 #  当此配置为 true 时，查询失败的异步搜索会返回：
{ "id": "Fm_QRn8BRiWfSeIP-2Xk7A", "status": "failed", "error": { "type": "search_phase_execution_exception", "reason": "all shards failed", "caused_by": { "type": "illegal_argument_exception", "reason": "Fielddata is disabled on text fields by default" } }, "start_time_in_millis": 1706899200000, "expiration_time_in_millis": 1706985600000 } 使用示例 #  # 默认配置（不持久化失败结果） async_search."
---


## 配置项作用

`async_search.persist_search_failures` 配置项控制是否将执行失败的异步搜索结果持久化到系统索引（`.async-search`）中。默认情况下，只有成功执行的异步搜索结果才会被持久化。

## 配置项类型

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

## 默认值

```
false（不持久化失败结果）
```

## 是否必需

**可选配置项**

## 配置值说明

| 值 | 说明 |
|---|---|
| `true` | 持久化所有异步搜索结果，包括失败的搜索 |
| `false` | 仅持久化成功的异步搜索结果（默认） |

## 工作原理

当异步搜索执行失败时：

**设置为 `false`（默认）：**
```
搜索失败 → 不保存结果 → 客户端获取错误 → 结果不被保留
```

**设置为 `true`：**
```
搜索失败 → 保存失败状态 → 可通过异步搜索ID查询错误信息
```

## 失败状态示例

当此配置为 `true` 时，查询失败的异步搜索会返回：

```json
{
  "id": "Fm_QRn8BRiWfSeIP-2Xk7A",
  "status": "failed",
  "error": {
    "type": "search_phase_execution_exception",
    "reason": "all shards failed",
    "caused_by": {
      "type": "illegal_argument_exception",
      "reason": "Fielddata is disabled on text fields by default"
    }
  },
  "start_time_in_millis": 1706899200000,
  "expiration_time_in_millis": 1706985600000
}
```

## 使用示例

```yaml
# 默认配置（不持久化失败结果）
async_search.persist_search_failures: false

# 启用失败结果持久化
async_search.persist_search_failures: true
```

## 推荐设置建议

**生产环境建议**：根据调试和监控需求设置

**推荐配置：**

```yaml
# 生产环境（节省存储）
async_search.persist_search_failures: false

# 开发/测试环境（便于调试）
async_search.persist_search_failures: true

# 需要审计失败查询的场景
async_search.persist_search_failures: true
```

**设置考虑因素：**

1. **存储空间**：启用后会增加 `.async-search` 系统索引的存储需求
2. **调试需求**：持久化失败结果有助于诊断查询问题
3. **审计要求**：某些场景需要记录所有搜索尝试，包括失败的
4. **清理策略**：失败结果同样受 `max_keep_alive` 限制，会被自动清理

## 使用场景

**启用持久化的场景：**

1. **问题诊断**：开发测试阶段便于分析查询失败原因
2. **审计日志**：需要记录所有搜索操作的历史
3. **错误监控**：通过定期扫描失败的异步搜索实现错误告警
4. **重试机制**：应用程序可以根据持久化的错误信息决定是否重试

**禁用持久化的场景：**

1. **生产环境**：减少不必要的存储开销
2. **高频操作**：大量失败的异步搜索会占用较多空间
3. **已有监控**：通过其他方式监控和记录错误

## 相关配置项

| 配置项 | 作用 | 默认值 |
|-------|------|-------|
| `async_search.max_keep_alive` | 结果最大保留时间 | 5天 |
| `async_search.expired.persisted_response.cleanup_interval` | 过期结果清理间隔 | 30分钟 |

## 查询失败结果

当启用失败结果持久化时，可以像查询普通异步搜索一样获取失败信息：

```bash
# 获取失败的异步搜索结果
GET /_async_search/Fm_QRn8BRiWfSeIP-2Xk7A

# 响应包含错误详情
{
  "status": "failed",
  "error": { ... }
}
```

## 注意事项

1. **动态更新**：修改此配置后立即生效，影响新提交的异步搜索请求
2. **存储影响**：启用后会增加 `.async-search` 系统索引的文档数量
3. **清理机制**：失败的异步搜索结果同样会在超过 `max_keep_alive` 后被清理
4. **状态标记**：失败的异步搜索状态为 `failed`，可通过状态字段区分
5. **与 max_keep_alive 的关系**：失败结果也会占用 keep_alive 时间，需要在考虑存储时计入