提交异步搜索

在指定索引上提交异步搜索请求，允许执行长时间运行的复杂查询而不阻塞客户端。

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`	对象	否	搜索建议

示例 #

基本异步搜索 #

POST /my_index/_async_search
{
  "query": {
    "match": {
      "title": "easysearch"
    }
  }
}

响应示例（搜索仍在进行中）：

{
  "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"
          }
        }
      ]
    }
  }
}

响应示例（搜索已完成）：

{
  "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": [...]
    }
  }
}

设置等待完成超时 #

POST /my_index/_async_search?wait_for_completion_timeout=5s
{
  "query": {
    "match_all": {}
  }
}

保持结果更长时间 #

POST /my_index/_async_search?keep_alive=2d
{
  "query": {
    "range": {
      "timestamp": {
        "gte": "now-7d"
      }
    }
  },
  "aggs": {
    "by_day": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "day"
      }
    }
  }
}

完成后保留结果 #

POST /my_index/_async_search?keep_on_completion=true
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "search" } },
        { "range": { "created": { "gte": "2026-01-01" } } }
      ]
    }
  }
}

使用聚合 #

POST /sales/_async_search
{
  "size": 0,
  "aggs": {
    "by_category": {
      "terms": {
        "field": "category.keyword"
      },
      "aggs": {
        "total_revenue": {
          "sum": {
            "field": "price"
          }
        }
      }
    }
  }
}

检查异步搜索状态 #

使用返回的任务 ID 检查搜索状态：

GET /_async_search/FmRldE8zSIYPf-3s6EmyOg

获取异步搜索结果 #

GET /_async_search/FmRldE8zSIYPf-3s6EmyOg

删除异步搜索结果 #

DELETE /_async_search/FmRldE8zSIYPf-3s6EmyOg

响应字段说明 #

字段	类型	描述
`id`	字符串	异步搜索任务的唯一标识符
`is_partial`	布尔值	结果是否为部分结果
`is_running`	布尔值	搜索是否仍在运行中
`start_time_in_millis`	整数	搜索开始的时间戳
`expiration_time_in_millis`	整数	结果过期的时间戳
`response`	对象	搜索结果响应

注意事项 #

异步搜索结果会占用存储空间，建议使用完成后及时删除
keep_alive 参数设置的结果保留时间会影响存储消耗
如果只需要确认搜索完成，可以使用较小的 wait_for_completion_timeout
对于快速查询，建议使用同步搜索 API 而非异步搜索

标签

搜索异步搜索查询