REST API

ES|QL REST API

概要

ES|QLクエリAPIは、queryパラメータにES|QLクエリ文字列を受け入れ、それを実行して結果を返します。例えば:

Python

resp = client.esql.query(
   format="txt",
   query="FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5",
)
print(resp)

Js

const response = await client.esql.query({
  format: "txt",
  query:
   "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5",
});
console.log(response);

コンソール

POST /_query?format=txt
{
  "query": "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5"
}

返されるのは:

テキスト

author      |        name        |  page_count   | release_date
-----------------+--------------------+---------------+------------------------
Peter F. Hamilton|Pandora's Star      |768            |2004-03-02T00:00:00.000Z
Vernor Vinge     |A Fire Upon the Deep|613            |1992-06-01T00:00:00.000Z
Frank Herbert    |Dune                |604            |1965-06-01T00:00:00.000Z
Alastair Reynolds|Revelation Space    |585            |2000-03-15T00:00:00.000Z
James S.A. Corey |Leviathan Wakes     |561            |2011-06-02T00:00:00.000Z

Kibanaコンソール

Kibana Consoleを使用している場合（強く推奨されます）、クエリを作成する際に三重引用符"""を活用してください。これにより、クエリ文字列内の二重引用符（"）が自動的にエスケープされるだけでなく、複数行のリクエストもサポートされます:

Python

resp = client.esql.query(
   format="txt",
   query="\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
)
print(resp)

Js

const response = await client.esql.query({
  format: "txt",
  query:
   "\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
});
console.log(response);

コンソール

POST /_query?format=txt
{
  "query": """
   FROM library
   | KEEP author, name, page_count, release_date
   | SORT page_count DESC
   | LIMIT 5
  """
}

レスポンスフォーマット

ES|QLは、以下の人間が読みやすい形式とバイナリ形式でデータを返すことができます。フォーマットは、URL内のformatパラメータを指定するか、AcceptまたはContent-TypeHTTPヘッダーを設定することで指定できます。

URLパラメータはHTTPヘッダーよりも優先されます。どちらも指定されていない場合、レスポンスはリクエストと同じフォーマットで返されます。


| | | |
| —- | —- | —- |
| format | HTTPヘッダー | 説明 |
| 人間が読みやすい |
| csv | text/csv | カンマ区切り値 |
| json | application/json | JSON（JavaScriptオブジェクト表記）人間が読みやすい形式 |
| tsv | text/tab-separated-values | タブ区切り値 |
| txt | text/plain | CLIのような表現 |
| yaml | application/yaml | YAML（YAMLはマークアップ言語ではない）人間が読みやすい形式 |
| バイナリ |
| cbor | application/cbor | 簡潔なバイナリオブジェクト表現 |
| smile | application/smile | Smile）CBORに似たバイナリデータ形式 |
| arrow | application/vnd.apache.arrow.stream | 実験的。 Apache Arrowデータフレーム、IPCストリーミング形式 |

### Elasticsearch Query DSLを使用したフィルタリング
`````filter`````パラメータにQuery DSLクエリを指定して、ES|QLクエリが実行されるドキュメントのセットをフィルタリングします。
#### Python
``````python
resp = client.esql.query(
   format="txt",
   query="\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
   filter={
   "range": {
   "page_count": {
   "gte": 100,
   "lte": 200
   }
   }
   },
)
print(resp)
`

Js

const response = await client.esql.query({
  format: "txt",
  query:
   "\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
  filter: {
   range: {
   page_count: {
   gte: 100,
   lte: 200,
   },
   },
  },
});
console.log(response);

コンソール

POST /_query?format=txt
{
  "query": """
   FROM library
   | KEEP author, name, page_count, release_date
   | SORT page_count DESC
   | LIMIT 5
  """,
  "filter": {
   "range": {
   "page_count": {
   "gte": 100,
   "lte": 200
   }
   }
  }
}

返されるのは:

テキスト

author     |                name                |  page_count   | release_date
---------------+------------------------------------+---------------+------------------------
Douglas Adams  |The Hitchhiker's Guide to the Galaxy|180            |1979-10-12T00:00:00.000Z

列形式の結果

デフォルトでは、ES|QLは結果を行として返します。例えば、FROMは各個別のドキュメントを1行として返します。json、yaml、cborおよびsmile フォーマットに対して、ES|QLは結果を列形式で返すことができ、1行が結果の特定の列のすべての値を表します。

Python

resp = client.esql.query(
   format="json",
   query="\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
   columnar=True,
)
print(resp)

Js

const response = await client.esql.query({
  format: "json",
  query:
   "\n    FROM library\n    | KEEP author, name, page_count, release_date\n    | SORT page_count DESC\n    | LIMIT 5\n  ",
  columnar: true,
});
console.log(response);

コンソール

POST /_query?format=json
{
  "query": """
   FROM library
   | KEEP author, name, page_count, release_date
   | SORT page_count DESC
   | LIMIT 5
  """,
  "columnar": true
}

返されるのは:

コンソール-結果

{
  "columns": [
   {"name": "author", "type": "text"},
   {"name": "name", "type": "text"},
   {"name": "page_count", "type": "integer"},
   {"name": "release_date", "type": "date"}
  ],
  "values": [
   ["Peter F. Hamilton", "Vernor Vinge", "Frank Herbert", "Alastair Reynolds", "James S.A. Corey"],
   ["Pandora's Star", "A Fire Upon the Deep", "Dune", "Revelation Space", "Leviathan Wakes"],
   [768, 613, 604, 585, 561],
   ["2004-03-02T00:00:00.000Z", "1992-06-01T00:00:00.000Z", "1965-06-01T00:00:00.000Z", "2000-03-15T00:00:00.000Z", "2011-06-02T00:00:00.000Z"]
  ]
}

ローカライズされた結果の返却

リクエストボディ内のlocaleパラメータを使用して、ロケールの規則に従ってフォーマットされた結果（特に日付）を返します。localeが指定されていない場合、デフォルトはen-US（英語）です。JDKサポートロケールを参照してください。

構文：localeパラメータは、（大文字と小文字を区別しない）形式xyおよびxy-XYの言語タグを受け入れます。

例えば、フランス語で月の名前を返すには:

Python

resp = client.esql.query(
   locale="fr-FR",
   query="\n          ROW birth_date_string = \"2023-01-15T00:00:00.000Z\"\n          | EVAL birth_date = date_parse(birth_date_string)\n          | EVAL month_of_birth = DATE_FORMAT(\"MMMM\",birth_date)\n          | LIMIT 5\n   ",
)
print(resp)

Js

const response = await client.esql.query({
  locale: "fr-FR",
  query:
   '\n          ROW birth_date_string = "2023-01-15T00:00:00.000Z"\n          | EVAL birth_date = date_parse(birth_date_string)\n          | EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date)\n          | LIMIT 5\n   ',
});
console.log(response);

コンソール

POST /_query
{
  "locale": "fr-FR",
  "query": """
   ROW birth_date_string = "2023-01-15T00:00:00.000Z"
   | EVAL birth_date = date_parse(birth_date_string)
   | EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date)
   | LIMIT 5
   """
}

クエリへのパラメータの渡し方

条件のための値は、クエリ文字列自体に値を統合することによって「インライン」でクエリに渡すことができます:

Python

resp = client.esql.query(
   query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > 300 AND author == \"Frank Herbert\"\n    | STATS count = COUNT(*) by year\n    | WHERE count > 0\n    | LIMIT 5\n  ",
)
print(resp)

Js

const response = await client.esql.query({
  query:
   '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > 300 AND author == "Frank Herbert"\n    | STATS count = COUNT(*) by year\n    | WHERE count > 0\n    | LIMIT 5\n  ',
});
console.log(response);

コンソール

POST /_query
{
  "query": """
   FROM library
   | EVAL year = DATE_EXTRACT("year", release_date)
   | WHERE page_count > 300 AND author == "Frank Herbert"
   | STATS count = COUNT(*) by year
   | WHERE count > 0
   | LIMIT 5
  """
}

ハッキングやコードインジェクションの試みを避けるために、値を別のパラメータリストに抽出します。クエリ文字列内の各パラメータに対して、疑問符プレースホルダー（?）を使用します:

Python

resp = client.esql.query(
   query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > ? AND author == ?\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?\n    | LIMIT 5\n  ",
   params=[
   300,
   "Frank Herbert",
   0
   ],
)
print(resp)

Js

const response = await client.esql.query({
  query:
   '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > ? AND author == ?\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?\n    | LIMIT 5\n  ',
  params: [300, "Frank Herbert", 0],
});
console.log(response);

コンソール

POST /_query
{
  "query": """
   FROM library
   | EVAL year = DATE_EXTRACT("year", release_date)
   | WHERE page_count > ? AND author == ?
   | STATS count = COUNT(*) by year
   | WHERE count > ?
   | LIMIT 5
  """,
  "params": [300, "Frank Herbert", 0]
}

パラメータは、名前付きパラメータまたは位置パラメータである可能性があります。

名前付きパラメータは、文字列の後に疑問符プレースホルダー（?）を使用します。

Python

resp = client.esql.query(
   query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > ?page_count AND author == ?author\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?count\n    | LIMIT 5\n  ",
   params=[
   {
   "page_count": 300
   },
   {
   "author": "Frank Herbert"
   },
   {
   "count": 0
   }
   ],
)
print(resp)

Js

const response = await client.esql.query({
  query:
   '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > ?page_count AND author == ?author\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?count\n    | LIMIT 5\n  ',
  params: [
   {
   page_count: 300,
   },
   {
   author: "Frank Herbert",
   },
   {
   count: 0,
   },
  ],
});
console.log(response);

コンソール

POST /_query
{
  "query": """
   FROM library
   | EVAL year = DATE_EXTRACT("year", release_date)
   | WHERE page_count > ?page_count AND author == ?author
   | STATS count = COUNT(*) by year
   | WHERE count > ?count
   | LIMIT 5
  """,
  "params": [{"page_count" : 300}, {"author" : "Frank Herbert"}, {"count" : 0}]
}

位置パラメータは、整数の後に疑問符プレースホルダー（?）を使用します。

Python

resp = client.esql.query(
   query="\n    FROM library\n    | EVAL year = DATE_EXTRACT(\"year\", release_date)\n    | WHERE page_count > ?1 AND author == ?2\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?3\n    | LIMIT 5\n  ",
   params=[
   300,
   "Frank Herbert",
   0
   ],
)
print(resp)

Js

const response = await client.esql.query({
  query:
   '\n    FROM library\n    | EVAL year = DATE_EXTRACT("year", release_date)\n    | WHERE page_count > ?1 AND author == ?2\n    | STATS count = COUNT(*) by year\n    | WHERE count > ?3\n    | LIMIT 5\n  ',
  params: [300, "Frank Herbert", 0],
});
console.log(response);

コンソール

POST /_query
{
  "query": """
   FROM library
   | EVAL year = DATE_EXTRACT("year", release_date)
   | WHERE page_count > ?1 AND author == ?2
   | STATS count = COUNT(*) by year
   | WHERE count > ?3
   | LIMIT 5
  """,
  "params": [300, "Frank Herbert", 0]
}

非同期ES|QLクエリの実行

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

ES|QLクエリの実行は通常非常に速いですが、大規模なデータセットや凍結データに対するクエリは時間がかかることがあります。長時間の待機を避けるために、非同期ES|QLクエリを実行します。

非同期クエリAPIによって開始されたクエリは、結果を返す場合と返さない場合があります。wait_for_completion_timeoutプロパティは、結果を待つ時間を決定します。この時間内に結果が利用できない場合、クエリIDが返され、後で結果を取得するために使用できます。例えば:

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
}

非同期クエリの進行状況を確認するには、クエリIDを使用してES|QL非同期クエリ取得APIを使用します。完全な結果を待つ時間をwait_for_completion_timeoutパラメータで指定します。

Python

resp = client.esql.async_query_get(
   id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
   wait_for_completion_timeout="30s",
   body=None,
)
print(resp)

Ruby

response = client.esql.async_query_get(
  id: 'FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=',
  wait_for_completion_timeout: '30s'
)
puts response

Js

const response = await client.esql.asyncQueryGet({
  id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  wait_for_completion_timeout: "30s",
  body: null,
});
console.log(response);

コンソール

GET /_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s

レスポンスのis_running値がfalseである場合、クエリは完了し、結果が返されます。

コンソール-結果

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

 [](#67b71a95b6fe6c83faae51ea038a1bf1)
#### コンソール
``````console
DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=
`