検索API - 非同期検索（Async search） - 《Elasticsearchガイドv8.15》日本語

非同期検索
非同期検索APIの送信
非同期検索の削除

非同期検索

非同期検索APIを使用すると、検索リクエストを非同期に実行し、その進行状況を監視し、部分的な結果を利用可能になると取得できます。

非同期検索APIの送信

検索リクエストを非同期に実行します。これは、検索APIと同じパラメータとリクエストボディを受け入れます。

Python

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)

Ruby

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

Js

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に設定されますが、結果は部分的である可能性があります。これは、いくつかのシャードが結果を返した後に検索が失敗した場合や、非同期検索を調整しているノードが死んだ場合に発生します。


`````keep_alive`````パラメータを通じて、非同期検索がどれくらいの期間利用可能である必要があるかを指定することもできます。デフォルトは`````5d`````（5日）です。この期間が経過すると、進行中の非同期検索と保存された検索結果は削除されます。  
結果の主なソートがインデックスされたフィールドである場合、シャードはそのフィールドの最小値と最大値に基づいてソートされるため、要求されたソート基準に従って部分的な結果が利用可能になります。  
非同期検索APIは、検索APIと同じ[パラメータ](89159571f146b334.md#search-search-api-query-params)をサポートしていますが、一部はデフォルト値が異なります：  
-  `````batched_reduce_size`````は`````5`````がデフォルトです：これは、部分的な結果がどれくらいの頻度で利用可能になるかに影響します。これは、シャードの結果が減少するたびに発生します。調整ノードが新しいシャードの応答を一定数受信するたびに部分的な減少が行われます（デフォルトでは`````5`````）。  
-  `````request_cache`````は`````true`````がデフォルトです  
-  `````pre_filter_shard_size`````は`````1`````がデフォルトで変更できません：これは、各シャードから統計を取得するために事前フィルタのラウンドトリップを実行することを強制するためです。これにより、クエリに一致するドキュメントを持たないことが確実なものがスキップされます。  
-  `````ccs_minimize_roundtrips`````は`````false`````がデフォルトです。クロスクラスター検索を行う場合、`````true`````に設定すると、特に多くのシャードを持つクラスターを検索する際に全体の検索レイテンシが改善される可能性があります。ただし、`````true`````に設定すると、リモートクラスターでの検索の進行状況は、すべてのクラスターで検索が完了するまで受信されません。詳細については、[クラスター間の検索](/read/elasticsearch-8-15/8b404b6bab699ac7.md)を参照してください。
非同期検索は、[スクロール](238327401f76c2ac.md#scroll-search-results)や、[サジェストセクション](/read/elasticsearch-8-15/39d4e7248968ca4f.md)のみを含む検索リクエストをサポートしていません。  
デフォルトでは、Elasticsearchは10Mbを超える非同期検索レスポンスを保存することを許可しておらず、これを試みるとエラーが発生します。保存された非同期検索レスポンスの最大許可サイズは、`````search.max_async_search_response_size`````クラスターの設定を変更することで設定できます。
## 非同期検索の取得
get async search APIは、指定されたIDの以前に送信された非同期検索リクエストの結果を取得します。  
Elasticsearchのセキュリティ機能が有効になっている場合、特定の非同期検索の結果へのアクセスは、[それを送信したユーザーまたはAPIキーのみに制限されます](d6e9ac8dde47c41d.md#can-access-resources-check)。
#### Python
``````python
resp = client.async_search.get(
   id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
`

Ruby

response = client.async_search.get(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response

Js

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）
	結果の減少が何回行われたかを示します。この数が最後に取得した結果と比較して増加した場合、検索レスポンスに追加の結果が含まれることが期待できます
	クエリを実行したシャードの数を示します。シャードの結果が検索レスポンスに含まれるためには、最初に減少される必要があります。
	クエリの実行をすでに完了したシャードからの部分的な集計結果。

wait_for_completion_timeoutパラメータは、Get Async Search APIを呼び出す際にも提供でき、指定されたタイムアウトまで検索が完了するのを待つことができます。タイムアウトが切れる前に利用可能な最終結果が返されます。そうでない場合、タイムアウトが切れた後に現在利用可能な結果が返されます。デフォルトではタイムアウトは設定されておらず、現在利用可能な結果が追加の待機なしに返されます。


## 非同期検索のステータス取得
get async search status APIは、検索結果を取得せずに、指定された`````id`````の以前に送信された非同期検索リクエストのステータスのみを表示します。  
Elasticsearchのセキュリティ機能が有効になっている場合、特定の非同期検索のステータスへのアクセスは次のように制限されます：  
-  元の非同期検索リクエストを送信した[ユーザーまたはAPIキー](d6e9ac8dde47c41d.md#can-access-resources-check)。  
-  `````monitor`````クラスター特権以上を持つユーザー。
`````keep_alive`````パラメータを通じて、非同期検索がどれくらいの期間利用可能である必要があるかを指定することもできます。デフォルトは`````5d`````（5日）です。この期間が経過すると、進行中の非同期検索と保存された検索結果は削除されます。
#### Python
``````python
resp = client.async_search.status(
   id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)
`

Ruby

response = client.async_search.status(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response

Js

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
}


	非同期検索がエラーで完了したことを示します。

非同期検索の削除

delete async search APIを使用して、IDで非同期検索を手動で削除できます。検索がまだ実行中の場合、検索リクエストはキャンセルされます。そうでない場合、保存された検索結果は削除されます。

Python

resp = client.async_search.delete(
   id="FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
)
print(resp)

Ruby

response = client.async_search.delete(
  id: 'FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc='
)
puts response

Js

const response = await client.asyncSearch.delete({
  id: "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
});
console.log(response);

コンソール

DELETE /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=

Elasticsearchのセキュリティ機能が有効になっている場合、特定の非同期検索の削除は次のように制限されます：

元の非同期検索リクエストを送信したユーザーまたはAPIキー。
cancel_taskクラスター特権以上を持つユーザー。