ES|QL非同期クエリアPI（ES|QL async query API）

ES|QL 非同期クエリ API

非同期 ES|QL クエリ を実行します。

非同期クエリ API は、クエリリクエストを非同期に実行し、その進行状況を監視し、結果が利用可能になったときに取得することを可能にします。

API は、同期 クエリ API と同じパラメータとリクエストボディを受け入れ、以下に示す追加の非同期関連プロパティも受け入れます。

Python

resp = client.esql.async_query(
   body={
   "query": "\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
   "wait_for_completion_timeout": "2s"
   },
)
print(resp)

Js

const response = await client.esql.asyncQuery({
  body: {
   query:
   "\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
   wait_for_completion_timeout: "2s",
  },
});
console.log(response);

コンソール

POST /_query/async
{
  "query": """
   FROM library
   | EVAL year = DATE_TRUNC(1 YEARS, release_date)
   | STATS MAX(page_count) BY year
   | SORT year
   | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s"
}

指定されたタイムアウト期間内に結果が利用できない場合（この場合は2秒）、結果は返されず、次の内容を含む応答が返されます：

• クエリ ID
• is_running の値が true であり、クエリが進行中であることを示します

クエリは、他のリクエストをブロックすることなくバックグラウンドで実行され続けます。

コンソール-結果

{
  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running": true
}

そうでない場合、応答の is_running の値が false であれば、非同期クエリは完了し、結果が返されます。

コンソール-結果

{
  "is_running": false,
  "columns": ...
}

リクエスト

POST /_query/async

前提条件

• Elasticsearch のセキュリティ機能が有効になっている場合、クエリするデータストリーム、インデックス、またはエイリアスに対して read インデックス権限 を持っている必要があります。

パスパラメータ

API は、同期 クエリ API と同じパラメータを受け入れます。

リクエストボディ

API は、同期 クエリ API と同じリクエストボディを受け入れ、以下のパラメータも受け入れます：

• wait_for_completion_timeout

• （オプション、時間値） リクエストが完了するまで待機するタイムアウト期間。デフォルトは1秒で、クエリ結果を得るためにリクエストが1秒待機します。
  この期間中にクエリが完了した場合、結果が返されます。そうでない場合、クエリ id が返され、後で結果を取得するために使用できます。
  この期間中にリクエストが完了しない場合、クエリ id が返されます。

• keep_on_completion
• （オプション、Boolean） true の場合、クエリとその結果はクラスターに保存されます。
  false の場合、リクエストが wait_for_completion_timeout パラメータで設定された期間中に完了しない場合にのみ、クエリとその結果がクラスターに保存されます。デフォルトは false です。
• keep_alive
• （オプション、時間値） クエリとその結果がクラスターに保存される期間。デフォルトは 5d （5日）です。
  この期間が終了すると、クエリとその結果は削除されます。クエリがまだ進行中であってもです。
  keep_on_completion パラメータが false の場合、Elasticsearch はこの値に関係なく、設定された期間内に完了しない非同期クエリのみを保存します。

レスポンスボディ

API は、同期 クエリ API と同じレスポンスボディを返し、以下のプロパティも含まれます：

• id
• （文字列） クエリの識別子。
  このクエリ ID は、次の条件のいずれかが満たされた場合にのみ提供されます：
  • クエリリクエストが wait_for_completion_timeout パラメータのタイムアウト期間中に完全な結果を返さない。
  • クエリリクエストの keep_on_completion パラメータが true である。
    この ID を使用して、ES|QL 非同期クエリ取得 API でクエリの現在のステータスと利用可能な結果を取得できます。
• is_running
• （Boolean） true の場合、クエリリクエストはまだ実行中です。