SQL検索（SQL search）

SQL検索API

SQL検索の結果を返します[$3e883b439e3ba6b8.md]。

Python

resp = client.sql.query(
   format="txt",
   query="SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
)
print(resp)

Js

const response = await client.sql.query({
  format: "txt",
  query: "SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
});
console.log(response);

Console

POST _sql?format=txt
{
  "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
}

Request

GET _sql

POST _sql

Prerequisites

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

Limitations

SQLの制限についてはSQL Limitationsを参照してください。

Query parameters

• delimiter
• (オプション、文字列) CSV結果の区切り文字。デフォルトは,です。このパラメータはCSVレスポンスにのみ対応しています。
• format
• (オプション、文字列) レスポンスのフォーマット。有効な値についてはレスポンスデータフォーマットを参照してください。
  Accept HTTPヘッダーを使用してフォーマットを指定することもできます。このパラメータとAccept HTTPヘッダーの両方を指定した場合、このパラメータが優先されます。

Request body

• allow_partial_search_results
• (オプション、ブール値) trueの場合、シャードリクエストのタイムアウトやシャード障害がある場合に部分的な結果を返します。falseの場合、部分的な結果なしでエラーを返します。デフォルトはfalseです。
• catalog
• (オプション、文字列) クエリのデフォルトカタログ（クラスター）。指定しない場合、クエリはローカルクラスター内のデータでのみ実行されます。
  [プレビュー] この機能は技術プレビュー中であり、将来のリリースで変更または削除される可能性があります。Elasticは問題を修正するために取り組みますが、技術プレビューの機能は公式GA機能のサポートSLAの対象ではありません。 クロスクラスター検索を参照してください。
• columnar
• (オプション、ブール値) trueの場合、結果を列形式で返します。デフォルトはfalseです。このパラメータはCBOR、JSON、SMILE、およびYAMLレスポンスにのみ対応しています。列形式の結果を参照してください。
• cursor

• (オプション、文字列) カーソルを使用してページネートされた結果のセットを取得します。cursorを指定した場合、APIはcolumnarおよびtime_zoneリクエストボディパラメータのみを使用します。他のリクエストボディパラメータは無視されます。

• fetch_size

• (オプション、整数) レスポンスで返す最大行数。デフォルトは1000です。

• field_multi_value_leniency
• (オプション、ブール値) falseの場合、APIは配列値を含むフィールドに対してエラーを返します。trueの場合、APIは配列から最初の値を返しますが、一貫した結果を保証するものではありません。デフォルトはfalseです。
• filter
• (オプション、オブジェクト) SQL検索のためにドキュメントをフィルタリングするために使用されるQuery DSL。Elasticsearch Query DSLを使用したフィルタリングを参照してください。
• index_include_frozen
• (オプション、ブール値) trueの場合、検索は凍結されたインデックスで実行できます。デフォルトはfalseです。
• keep_alive
• (オプション、時間値) 非同期または保存された同期検索の保持期間。デフォルトは5d（5日）です。
• keep_on_completion
• (オプション、ブール値) trueの場合、Elasticsearchはwait_for_completion_timeoutパラメータを指定した場合に同期検索を保存します。falseの場合、Elasticsearchはwait_for_completion_timeoutより前に完了しない非同期検索のみを保存します。デフォルトはfalseです。
• page_timeout
• (オプション、時間値) スクロールカーソルの最小保持期間。この期間を過ぎると、ページネーションリクエストが失敗する可能性があります。後続のスクロールリクエストは、スクロールリクエスト内のpage_timeoutの期間だけスクロールカーソルの寿命を延ばします。デフォルトは45s（45秒）です。
• params
• (オプション、配列) queryのパラメータの値。構文についてはクエリにパラメータを渡すを参照してください。
• query
• (必須、オブジェクト) 実行するSQLクエリ。構文についてはSQL言語を参照してください。
• request_timeout
• (オプション、時間値) リクエストが失敗する前のタイムアウト。デフォルトは90s（90秒）です。
• runtime_mappings
• (オプション、オブジェクトのオブジェクト) 検索リクエスト内の1つ以上のランタイムフィールドを定義します。これらのフィールドは、同じ名前のマッピングされたフィールドよりも優先されます。

  -   `````<field-name>

  • (必須、オブジェクト) ランタイムフィールドの設定。キーはフィールド名です。

    -   `````type

    • (必須、文字列) フィールドタイプ、次のいずれかである必要があります:
    • boolean
    • composite
    • date
    • double
    • geo_point
    • ip
    • keyword
    • long
    • lookup
    • script
    • (オプション、文字列) クエリ時に実行されるPainlessスクリプト。スクリプトは、元の_sourceおよびマッピングされたフィールドとその値を含むドキュメントの全コンテキストにアクセスできます。
      このスクリプトは、計算された値を返すためにemitを含む必要があります。例えば:

Js

"script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"

• time_zone
• (オプション、文字列) 検索のためのISO-8601タイムゾーンID。いくつかのSQL日付/時間関数はこのタイムゾーンを使用します。デフォルトはZ（UTC）です。
• wait_for_completion_timeout
• (オプション、時間値) 完全な結果を待つ期間。デフォルトはタイムアウトなし、つまりリクエストは完全な検索結果を待ちます。この期間内に検索が完了しない場合、検索は非同期になります。
  同期検索を保存するには、このパラメータとkeep_on_completionパラメータを指定する必要があります。

Response body

SQL検索APIはmultiple response formatsをサポートしています。ほとんどのレスポンスフォーマットは表形式のレイアウトを使用します。JSONレスポンスには次のプロパティが含まれます:

• id
• (文字列) 検索の識別子。この値は非同期および保存された同期検索に対してのみ返されます。CSV、TSV、TXTレスポンスの場合、この値はAsync-ID HTTPヘッダーに返されます。
• is_running
• (ブール値) trueの場合、検索はまだ実行中です。falseの場合、検索は完了しています。この値は非同期および保存された同期検索に対してのみ返されます。CSV、TSV、TXTレスポンスの場合、この値はAsync-partial HTTPヘッダーに返されます。
• is_partial
• (ブール値) trueの場合、レスポンスには完全な検索結果が含まれていません。is_partialがtrueで、is_runningがtrueの場合、検索はまだ実行中です。is_partialがtrueで、is_runningがfalseの場合、結果は失敗またはタイムアウトのため部分的です。
  この値は非同期および保存された同期検索に対してのみ返されます。CSV、TSV、TXTレスポンスの場合、この値はAsync-partial HTTPヘッダーに返されます。
• rows
• (配列の配列) 検索結果の値。
• columns
• (オブジェクトの配列) 検索結果の列見出し。各オブジェクトは1つの列です。

  -   `````name

  • (文字列) 列の名前。
  • type
  • (文字列) 列のデータ型。
• cursor
• (文字列) 次のページネートされた結果のためのカーソル。CSV、TSV、TXTレスポンスの場合、この値はCursor HTTPヘッダーに返されます。