持久化异步搜索失败结果

配置项作用 #

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

配置项类型 #

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

默认值 #

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.persist_search_failures: false

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

推荐设置建议 #

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

推荐配置：

# 生产环境（节省存储）
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. 已有监控：通过其他方式监控和记录错误

相关配置项 #

查询失败结果 #

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

# 获取失败的异步搜索结果
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 时间，需要在考虑存储时计入