--- title: "提交异步搜索" date: 2026-02-13 lastmod: 2026-02-13 description: "在指定索引上提交异步搜索请求，执行长时间运行的复杂查询而不阻塞客户端" tags: ["搜索", "异步搜索", "查询"] summary: "在指定索引上提交异步搜索请求，允许执行长时间运行的复杂查询而不阻塞客户端。 API # POST /{index}/_async_search API 的作用 # 该 API 用于在指定索引上提交异步搜索请求。异步搜索可以： 长时间运行而不阻塞客户端 使用返回的任务 ID 来检查搜索状态和获取结果 避免客户端长时间等待复杂查询的完成 限制 # 不支持滚动（scroll）查询 不支持仅建议（suggest-only）查询 主要用于需要长时间运行的复杂查询 API 的参数 # 路由参数 # 参数 类型 是否必填 描述 {index} 字符串 必需 要执行搜索的索引名称 Query String 参数 # 异步搜索特有参数 # 参数 类型 是否必填 默认值 描述 wait_for_completion_timeout 时间值 否 1s 请求应该等待的最小时间才返回部分结果 keep_alive 时间值 否 1d 结果过期前保持的时间（最小 1 分钟） keep_on_completion 布尔值 否 false 在完成或失败时是否保留资源 request_cache 布尔值 否 true 是否使用请求缓存 batched_reduce_size 整数 否 5 批量减少操作的文档数量 搜索通用参数 # 参数 类型 是否必填 默认值 描述 from 整数 否 0 分页偏移量 size 整数 否 10 返回的文档数量 query 字符串 否 - Lucene 查询字符串 sort 字符串 否 - 排序字段，格式为 “field:asc” 或 “field:desc” explain 布尔值 否 false 是否返回每个命中文档的评分解释 timeout 时间值 否 - 等待每个分片返回的超时时间 terminate_after 整数 否 - 处理完指定数量的文档后终止 track_scores 布尔值 否 false 是否在返回结果中包含评分 track_total_hits 布尔值/整数 否 true 是否返回总命中数 stored_fields 字符串 否 - 要返回的存储字段 docvalue_fields 字符串 否 - 要返回的 Doc 值字段 preference 字符串 否 - 分片选择偏好 routing 字符串 否 - 特定路由值 search_type 字符串 否 - 搜索执行类型 stats 字符串 否 - 要收集的统计信息组 max_concurrent_shard_requests 整数 否 - 并发分片请求数量的最大值 allow_partial_search_results 布尔值 否 - 是否允许部分分片返回结果 pre_filter_shard_size 整数 否 1 在每个分片上评估查询的文档数量阈值 ccs_minimize_roundtrips 布尔值 否 false 最小化跨集群搜索的往返次数 请求体参数 # 请求体必须包含搜索请求的 JSON 格式，包括：" --- 在指定索引上提交异步搜索请求，允许执行长时间运行的复杂查询而不阻塞客户端。 ## API ``` POST /{index}/_async_search ``` ## API 的作用 该 API 用于在指定索引上提交异步搜索请求。异步搜索可以： - 长时间运行而不阻塞客户端 - 使用返回的任务 ID 来检查搜索状态和获取结果 - 避免客户端长时间等待复杂查询的完成 ### 限制 - 不支持滚动（scroll）查询 - 不支持仅建议（suggest-only）查询 - 主要用于需要长时间运行的复杂查询 ## API 的参数 ### 路由参数 | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `{index}` | 字符串 | 必需 | 要执行搜索的索引名称 | ### Query String 参数 #### 异步搜索特有参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `wait_for_completion_timeout` | 时间值 | 否 | 1s | 请求应该等待的最小时间才返回部分结果 | | `keep_alive` | 时间值 | 否 | 1d | 结果过期前保持的时间（最小 1 分钟） | | `keep_on_completion` | 布尔值 | 否 | false | 在完成或失败时是否保留资源 | | `request_cache` | 布尔值 | 否 | true | 是否使用请求缓存 | | `batched_reduce_size` | 整数 | 否 | 5 | 批量减少操作的文档数量 | #### 搜索通用参数 | 参数 | 类型 | 是否必填 | 默认值 | 描述 | |------|------|----------|--------|------| | `from` | 整数 | 否 | 0 | 分页偏移量 | | `size` | 整数 | 否 | 10 | 返回的文档数量 | | `query` | 字符串 | 否 | - | Lucene 查询字符串 | | `sort` | 字符串 | 否 | - | 排序字段，格式为 "field:asc" 或 "field:desc" | | `explain` | 布尔值 | 否 | false | 是否返回每个命中文档的评分解释 | | `timeout` | 时间值 | 否 | - | 等待每个分片返回的超时时间 | | `terminate_after` | 整数 | 否 | - | 处理完指定数量的文档后终止 | | `track_scores` | 布尔值 | 否 | false | 是否在返回结果中包含评分 | | `track_total_hits` | 布尔值/整数 | 否 | true | 是否返回总命中数 | | `stored_fields` | 字符串 | 否 | - | 要返回的存储字段 | | `docvalue_fields` | 字符串 | 否 | - | 要返回的 Doc 值字段 | | `preference` | 字符串 | 否 | - | 分片选择偏好 | | `routing` | 字符串 | 否 | - | 特定路由值 | | `search_type` | 字符串 | 否 | - | 搜索执行类型 | | `stats` | 字符串 | 否 | - | 要收集的统计信息组 | | `max_concurrent_shard_requests` | 整数 | 否 | - | 并发分片请求数量的最大值 | | `allow_partial_search_results` | 布尔值 | 否 | - | 是否允许部分分片返回结果 | | `pre_filter_shard_size` | 整数 | 否 | 1 | 在每个分片上评估查询的文档数量阈值 | | `ccs_minimize_roundtrips` | 布尔值 | 否 | false | 最小化跨集群搜索的往返次数 | ### 请求体参数 请求体必须包含搜索请求的 JSON 格式，包括： | 参数 | 类型 | 是否必填 | 描述 | |------|------|----------|------| | `query` | 对象 | 是 | 搜索查询条件 | | `aggregations` | 对象 | 否 | 聚合查询 | | `sort` | 数组 | 否 | 排序条件 | | `size` | 整数 | 否 | 返回结果数量 | | `from` | 整数 | 否 | 起始位置 | | `highlight` | 对象 | 否 | 高亮显示 | | `suggest` | 对象 | 否 | 搜索建议 | ## 示例 ### 基本异步搜索 ```bash POST /my_index/_async_search { "query": { "match": { "title": "easysearch" } } } ``` **响应示例（搜索仍在进行中）：** ```json { "id": "FmRldE8zSIYPf-3s6EmyOg", "is_partial": true, "is_running": true, "start_time_in_millis": 1641234567890, "expiration_time_in_millis": 1641320967890, "response": { "took": 100, "timed_out": false, "hits": { "total": 10000, "hits": [ { "_id": "1", "_score": 1.0, "_source": { "title": "easysearch introduction" } } ] } } } ``` **响应示例（搜索已完成）：** ```json { "id": "FmRldE8zSIYPf-3s6EmyOg", "is_partial": false, "is_running": false, "expiration_time_in_millis": 1641320967890, "response": { "took": 2500, "timed_out": false, "hits": { "total": 10000, "max_score": 1.0, "hits": [...] } } } ``` ### 设置等待完成超时 ```bash POST /my_index/_async_search?wait_for_completion_timeout=5s { "query": { "match_all": {} } } ``` ### 保持结果更长时间 ```bash POST /my_index/_async_search?keep_alive=2d { "query": { "range": { "timestamp": { "gte": "now-7d" } } }, "aggs": { "by_day": { "date_histogram": { "field": "timestamp", "calendar_interval": "day" } } } } ``` ### 完成后保留结果 ```bash POST /my_index/_async_search?keep_on_completion=true { "query": { "bool": { "must": [ { "match": { "title": "search" } }, { "range": { "created": { "gte": "2026-01-01" } } } ] } } } ``` ### 使用聚合 ```bash POST /sales/_async_search { "size": 0, "aggs": { "by_category": { "terms": { "field": "category.keyword" }, "aggs": { "total_revenue": { "sum": { "field": "price" } } } } } } ``` ### 检查异步搜索状态 使用返回的任务 ID 检查搜索状态： ```bash GET /_async_search/FmRldE8zSIYPf-3s6EmyOg ``` ### 获取异步搜索结果 ```bash GET /_async_search/FmRldE8zSIYPf-3s6EmyOg ``` ### 删除异步搜索结果 ```bash DELETE /_async_search/FmRldE8zSIYPf-3s6EmyOg ``` ## 响应字段说明 | 字段 | 类型 | 描述 | |------|------|------| | `id` | 字符串 | 异步搜索任务的唯一标识符 | | `is_partial` | 布尔值 | 结果是否为部分结果 | | `is_running` | 布尔值 | 搜索是否仍在运行中 | | `start_time_in_millis` | 整数 | 搜索开始的时间戳 | | `expiration_time_in_millis` | 整数 | 结果过期的时间戳 | | `response` | 对象 | 搜索结果响应 | ## 注意事项 1. 异步搜索结果会占用存储空间，建议使用完成后及时删除 2. `keep_alive` 参数设置的结果保留时间会影响存储消耗 3. 如果只需要确认搜索完成，可以使用较小的 `wait_for_completion_timeout` 4. 对于快速查询，建议使用同步搜索 API 而非异步搜索