« 搜索 API 时间点 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›搜索 API

异步搜索

编辑

异步搜索

编辑

异步搜索 API 允许您异步执行搜索请求，监控其进度，并在部分结果可用时检索它们。

提交异步搜索 API

编辑

异步执行搜索请求。它接受与 搜索 API 相同的参数和请求体。

resp = client.async_search.submit(
    index="sales*",
    size="0",
    sort=[
        {
            "date": {
                "order": "asc"
            }
        }
    ],
    aggs={
        "sale_date": {
            "date_histogram": {
                "field": "date",
                "calendar_interval": "1d"
            }
        }
    },
)
print(resp)
response = client.async_search.submit(
  index: 'sales*',
  size: 0,
  body: {
    sort: [
      {
        date: {
          order: 'asc'
        }
      }
    ],
    aggregations: {
      sale_date: {
        date_histogram: {
          field: 'date',
          calendar_interval: '1d'
        }
      }
    }
  }
)
puts response
const response = await client.asyncSearch.submit({
  index: "sales*",
  size: 0,
  sort: [
    {
      date: {
        order: "asc",
      },
    },
  ],
  aggs: {
    sale_date: {
      date_histogram: {
        field: "date",
        calendar_interval: "1d",
      },
    },
  },
});
console.log(response);
POST /sales*/_async_search?size=0
{
  "sort": [
    { "date": { "order": "asc" } }
  ],
  "aggs": {
    "sale_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "1d"
      }
    }
  }
}

响应包含正在执行的搜索的标识符。您可以使用此 ID 稍后检索搜索的最终结果。当前可用的搜索结果将作为 response 对象的一部分返回。

{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=", 
  "is_partial" : true, 
  "is_running" : true, 
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "response" : {
    "took" : 1122,
    "timed_out" : false,
    "num_reduce_phases" : 0,
    "_shards" : {
      "total" : 562, 
      "successful" : 3, 
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 157483, 
        "relation" : "gte"
      },
      "max_score" : null,
      "hits" : [ ]
    }
  }
}

异步搜索的标识符，可用于监控其进度、检索其结果和/或删除它

当查询不再运行时，指示搜索是失败还是在所有分片上成功完成。当查询正在执行时，is_partial 始终设置为 true

指示搜索仍在执行还是已完成

搜索将在其上执行的分片总数

已成功完成搜索的分片数

当前与查询匹配的文档数，这些文档属于已完成搜索的分片

尽管查询不再运行，因此 is_running 设置为 false，但结果可能是不完整的。这发生在某些分片返回结果后搜索失败，或者协调异步搜索的节点死亡时。

可以通过提供 wait_for_completion_timeout 参数来阻止和等待搜索完成，直到达到某个超时时间，该参数默认为 1 秒。当异步搜索在此超时时间内完成时，响应不会包含 ID，因为结果不会存储在集群中。可以将默认为 false 的 keep_on_completion 参数设置为 true，以便在搜索在 wait_for_completion_timeout 内完成时请求存储结果以供稍后检索。

您还可以通过 keep_alive 参数指定异步搜索需要保持可用的时间，该参数默认为 5d（五天）。在此期间之后，正在进行的异步搜索和任何已保存的搜索结果将被删除。

当结果的主排序是索引字段时，分片会根据它们为该字段持有的最小值和最大值进行排序，因此部分结果将按照请求的排序标准提供。

提交异步搜索 API 支持与搜索 API 相同的 参数，但某些参数具有不同的默认值

  • batched_reduce_size 默认为 5：这会影响部分结果的可用频率，每当减少分片结果时就会发生。每当协调节点收到一定数量的新分片响应时（默认情况下为 5），就会执行部分减少。
  • request_cache 默认为 true
  • pre_filter_shard_size 默认为 1 且无法更改：这是为了强制执行预过滤往返，以从每个分片检索统计信息，以便跳过那些肯定不包含与查询匹配的任何文档的分片。
  • ccs_minimize_roundtrips 默认为 false。当执行跨集群搜索时，将其设置为 true 可能会提高整体搜索延迟，尤其是在搜索具有大量分片的集群时。但是，当设置为 true 时，在所有集群上的搜索完成之前，不会收到远程集群上搜索的进度。有关更多信息，请参阅跨集群搜索。

异步搜索不支持 滚动 或仅包含 建议部分 的搜索请求。

默认情况下，Elasticsearch 不允许存储大于 10Mb 的异步搜索响应，尝试这样做会导致错误。可以通过更改 search.max_async_search_response_size 集群级别设置来设置存储的异步搜索响应的最大允许大小。

获取异步搜索

编辑

获取异步搜索 API 检索给定 ID 的先前提交的异步搜索请求的结果。

如果启用了 Elasticsearch 安全功能，则对特定异步搜索结果的访问仅限于 提交它的用户或 API 密钥。

resp = client.async_search.get(
    id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
response = client.async_search.get(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response
const response = await client.asyncSearch.get({
  id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});
console.log(response);
GET /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_partial" : false, 
  "is_running" : false, 
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986, 
  "completion_time_in_millis" : 1583945903130, 
  "response" : {
    "took" : 12144,
    "timed_out" : false,
    "num_reduce_phases" : 46, 
    "_shards" : {
      "total" : 562,
      "successful" : 188, 
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 456433,
        "relation" : "eq"
      },
      "max_score" : null,
      "hits" : [ ]
    },
    "aggregations" : { 
      "sale_date" :  {
        "buckets" : []
      }
    }
  }
}

当查询不再运行时，指示搜索是失败还是在所有分片上成功完成。当查询正在执行时，is_partial 始终设置为 true

指示搜索仍在执行还是已完成

异步搜索何时过期

当异步搜索完成时，会指示 completion_time (start_time + took)

指示已执行的结果缩减次数。如果此数字与上次检索的结果相比增加，您可以预期搜索响应中会包含其他结果

指示有多少分片已执行查询。请注意，为了将分片结果包含在搜索响应中，需要先对其进行缩减。

来自已完成查询执行的分片的部分聚合结果。

在调用“获取异步搜索 API”时，还可以提供 wait_for_completion_timeout 参数，以便等待搜索完成，直到达到提供的超时时间。如果在超时时间到期之前可用，则将返回最终结果，否则，将在超时时间到期后返回当前可用的结果。默认情况下，不设置超时，这意味着将返回当前可用的结果，而无需任何额外的等待。

keep_alive 参数指定异步搜索应在集群中保持可用的时间。如果未指定，则将使用通过相应的提交异步请求设置的 keep_alive。否则，可以覆盖该值并延长请求的有效性。当此期限到期时，如果搜索仍在运行，则会取消该搜索。如果搜索已完成，则会删除其保存的结果。

获取异步搜索状态

编辑

获取异步搜索状态 API，无需检索搜索结果，仅显示给定 id 的先前提交的异步搜索请求的状态。

如果启用了 Elasticsearch 安全功能，则对特定异步搜索状态的访问仅限于

  • 提交原始异步搜索请求的用户或 API 密钥。
  • 具有 monitor 集群特权或更高级别的用户。

您还可以通过 keep_alive 参数指定异步搜索需要保持可用的时间，该参数默认为 5d（五天）。在此期间之后，正在进行的异步搜索和任何已保存的搜索结果将被删除。

resp = client.async_search.status(
    id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
response = client.async_search.status(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response
const response = await client.asyncSearch.status({
  id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});
console.log(response);
GET /_async_search/status/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : true,
  "is_partial" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 188, 
      "skipped" : 0,
      "failed" : 0
  }
}

指示到目前为止已执行查询的分片数。

对于已完成的异步搜索，状态响应具有额外的 completion_status 字段，该字段显示已完成的异步搜索的状态代码。

{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : false,
  "is_partial" : false,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 562,
      "skipped" : 0,
      "failed" : 0
  },
 "completion_status" : 200 
}

指示异步搜索已成功完成。

 
{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_running" : false,
  "is_partial" : true,
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "_shards" : {
      "total" : 562,
      "successful" : 450,
      "skipped" : 0,
      "failed" : 112
  },
 "completion_status" : 503 
}

指示异步搜索已完成，但出现错误。

删除异步搜索

编辑

您可以使用删除异步搜索 API 通过 ID 手动删除异步搜索。如果搜索仍在运行，则将取消搜索请求。否则，将删除保存的搜索结果。

resp = client.async_search.delete(
    id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
response = client.async_search.delete(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response
const response = await client.asyncSearch.delete({
  id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});
console.log(response);
DELETE /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=

如果启用了 Elasticsearch 安全功能，则对特定异步搜索的删除仅限于

  • 提交原始异步搜索请求的用户或 API 密钥。
  • 具有 cancel_task 集群特权或更高级别的用户。
« 搜索 API 时间点 API »