elasticsearch-esql

Elasticsearch ES|QL

Elasticsearch に対して ES|QL クエリを実行します。スキーマを確認し、タスクに適した ES|QL 機能を選択して、最も簡潔で正しいクエリを生成し、実行します。

環境設定

このスキルは、elastic CLI を通じて Elasticsearch の操作を実行します。 elastic CLI がインストールされていない場合は、何に必要なのかをユーザーに伝えてください。認証情報を推測したり、HTTP API を直接呼び出したり、ほかの回避策を試したりしないでください。

このスキルでは、HTTP 省略記法で操作を記載しています（例：GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）。このドキュメント末尾の 操作表で、それぞれの省略記法に対応する elastic CLI コマンドを確認できます。HTTP API を直接呼び出すのではなく、必ず CLI を使用してください。

ES|QL とは？

ES|QL（Elasticsearch Query Language）は、Elasticsearch のパイプライン型クエリ言語です。次のものとは異なります。

• Elasticsearch Query DSL（JSON ベース）
• SQL
• EQL（Event Query Language）

ES|QL ではパイプ（|）を使ってコマンドを連結します。 FROM index | WHERE condition | STATS aggregation BY field | SORT field | LIMIT n

前提条件： ES|QL を使用するには、クエリ対象のインデックスで _source が有効になっている必要があります。_source が無効なインデックス（例： "_source": { "enabled": false }）では、ES|QL クエリは失敗します。

バージョンの互換性： ES|QL は 8.11 で導入され（テクニカルプレビュー）、8.14 で GA になりました。LOOKUP JOIN（8.18 以降）、MATCH（8.17 以降）、INLINE STATS（9.2 以降）などの機能は、後のバージョンで追加されました。8.18 より前のクラスターでは、LOOKUP JOIN の代替として ENRICH を使用してください（生成時のヒントを参照）。9.2 より前のバージョンでは、INLINE STATS とカウンターフィールドの RATE() に代替機能はありません。バージョンごとの機能の提供状況については、references/esql-version-history.md を確認してください。

クラスターの検出： GET / を呼び出して、クラスターの種類とバージョンを確認します。

• build_flavor: "serverless" — Elastic Cloud Serverless です。version.number は開発中のスタック系列（main からの次のマイナーバージョン）を表すため、semver の比較のみを行うクライアントでは、Serverless が「最新」と判定される場合があります。version.number を使って機能の利用可否を判定しないでください。 build_flavor が "serverless" の場合は、すべての GA およびプレビュー版の ES|QL 機能が利用可能だと見なしてください。
• build_flavor: "default" — Stack（セルフマネージドまたはクラウドホスト型）です。機能の利用可否の判定には version.number を使用してください。
• スナップショットビルドの version.number は、9.4.0-SNAPSHOT のようになります。-SNAPSHOT サフィックスを取り除き、バージョン確認にはメジャーとマイナーを使用してください。スナップショットビルドには、そのバージョンまでのすべての機能に加え、開発中でまだリリースされていない機能が含まれる場合があります。クエリで不明な関数やコマンドのエラーが発生した場合、その機能はまだ取り込まれていないだけの可能性があります。Elastic の従業員は、テストにスナップショットビルドをよく使用します。

手順

1. 接続を確認し、デプロイの種類を検出します。 最初に GET / を呼び出します。これにより、接続を確認し、デプロイが Serverless プロジェクト（すべての機能を利用可能）か、バージョン管理されたクラスター（機能の利用可否はバージョンによる）かを検出できます。build_flavor フィールドが信頼できる判定基準です。値が "serverless" の場合は、報告されたバージョン番号を無視し、すべての ES|QL 機能を自由に使用してください。この呼び出しが失敗した場合は、処理を中止し、エンドポイントや認証情報を推測するのではなく、CLI の設定手順をユーザーに案内してください。

2. スキーマを確認します（必須。インデックス名やフィールド名を決して推測しないでください）。 GET /_cat/indices で候補となるインデックスを一覧表示し（絞り込むにはパターンを指定します）、選択したインデックスのフィールド型を GET /{index}/_mapping で取得します。 クエリを生成する前に、必ずスキーマを検出してください。インデックス名とフィールド名はデプロイ環境によって異なるため、確実に推測することはできません。「logs」のようによく見かけるデータであっても、logs-test、logs-app-*、application_logs という名前のインデックスに格納されている場合があります。フィールド名には ECS のドット記法（source.ip、service.name）やフラットなカスタム名が使われることがあるため、確認する以外に方法はありません。

   シンプルさを優先してください： ユーザーから複数のソースにまたがるデータを明示的に求められない限り、単一のインデックスをクエリしてください。特に指示がない限り、スキーマが異なるインデックスを COALESCE で結合しないでください。質問に最も関連性の高い単一のインデックスを選んでください。類似したデータを含むインデックスが複数ある場合は、対象のタスクに最も適した、スキーマが最も完全なインデックスを優先してください。

   時系列インデックスを検出してください。 GET /{index}/_settings/index.mode でインデックスモードを確認します。time_series の場合は、FROM ではなく TS <data-stream>、DATE_TRUNC ではなく TBUCKET(interval) を使い、カウンターフィールドを SUM(RATE(...)) で囲みます。時系列クエリを作成する前に、Generation Tips の TS に関するセクション全体をお読みください。9.4 以降の TSDS インデックスでは、マッピングを調べるよりも、インラインの検出コマンドである METRICS_INFO と TS_INFO（どちらも GA）を優先してください。これらのコマンドはメトリックカタログと各時系列のディメンションラベルを直接列挙し、POST /_query を使った ES|QL クエリとして実行します。metric_type（counter／gauge／histogram）と field_type（分布メトリックの場合は histogram、tdigest、exponential_histogram）については、METRICS_INFO を信頼できる情報源として扱ってください。どちらのコマンドも TS の後、STATS／SORT／LIMIT の前に指定する必要があります。Time Series Queries を参照してください：

   TS metrics-tsds | METRICS_INFO | SORT metric_name
   TS metrics-tsds | TS_INFO | KEEP metric_name, dimensions | SORT metric_name
   

3. タスクに適した ES|QL 機能を選択してください。 クエリを作成する前に、ユーザーの意図に最も適した ES|QL 機能を選びます。基本的なクエリを複数使うより、高度なクエリを 1 つ使うことを優先してください。

   • 「パターンを見つける」「分類する」「類似したメッセージをグループ化する」→ CATEGORIZE(field)
   • 「急増」「低下」「異常」「X はいつ変化したか」→ CHANGE_POINT value ON key
   • 「時間経過に伴う傾向」「時系列」→ STATS ... BY BUCKET(@timestamp, interval)。TSDB の場合は TS
   • 「PromQL」、「Prometheus のクエリ／ダッシュボード／アラート」、sum by (instance) (...)、{cluster="prod"} のようなラベルマッチャー → PROMQL ソースコマンド（9.4 以降はプレビュー）。PROMQL Command を参照してください。ネイティブな ES|QL の表現では TS を優先してください。
   • 「検索する」「条件に一致するドキュメントを見つける」→ MATCH（デフォルト）、QSTR（高度なブール検索）、KQL（Kibana からの移行）。コンテンツ／ドキュメントの関連性検索については、ES|QL Search Strategy に従ってください。
   • 「件数」「平均」「内訳」→ 集計関数を使った STATS
   • 「概算」「推定」「おおよその数値」「大規模データの高速／低コストな統計」→ STATS クエリの前に SET approximation=true; を指定します（9.5 以降／Serverless では GA、9.4 ではプレビュー）。Query Approximation を参照してください。

4. クエリを生成する前に、リファレンスを読んでください：

   • 生成のヒント - 主なパターン（TS/TBUCKET/RATE、集計ごとの WHERE、LOOKUP JOIN、 CIDR_MATCH）、一般的なテンプレート、曖昧さへの対処
   • 時系列クエリ - TS クエリを実行する前に必ず読んでください：内側／外側の集計 モデル、TBUCKET の構文、RATE の制約、ヒストグラムメトリクス
   • PROMQL コマンド — PROMQL クエリを実行する前に必ず読んでください：オプション、出力スキーマ、 制限事項、PROMQL と TS の選択基準表（9.4 以降のプレビュー）
   • ES|QL 完全リファレンス - すべてのコマンドと関数の完全な構文
   • ES|QL 検索戦略 — コンテンツ／ドキュメントの関連性検索向け（取得 → 融合 → 再ランキング）
   • ES|QL 検索リファレンス — 全文検索関数の構文（MATCH、QSTR、KQL、 スコアリング）
   • クエリ近似 — SET approximation を使用する前に必ず読んでください：出力 列、サンプリング／信頼水準の調整、未サポートの関数とパターン（9.5 以降／Serverless では GA、9.4 では プレビュー）

5. ES|QL の構文に従ってクエリを生成します。質問に答えるために最もシンプルなクエリを優先してください。ユーザーから求められていない限り、インデックス、フィールド、変換を追加しないでください。質問への回答に直接必要なフィールドのみを KEEP に含めてください。ユーザーが指定した条件以外のフィルター条件を追加しないでください（たとえば、ユーザーが単に「エラー」と言った場合に、OR level == "ERROR" を追加しないでください）。

   • FROM index-pattern から始めます（時系列インデックスの場合は TS index-pattern）
   • フィルタリングには WHERE を追加します（9.3 以降の時間範囲には TRANGE を使用）
   • 計算フィールドには EVAL を使用します
   • 集計には STATS ... BY を使用します
   • 時系列メトリクスの場合：カウンターには SUM(RATE(...)) を伴う TS、ゲージには AVG(...)、ヒストグラムメトリクスには標準の集計 （SUM、AVG、PERCENTILE、… — *_OVER_TIME ではありません）、時間のバケット化には TBUCKET(interval) を使用します — 生成のヒント の TS セクションと ヒストグラムメトリクスを参照してください
   • スパイク、低下、異常を検出するには、時間でバケット化した集計の後に CHANGE_POINT を使用します
   • 必要に応じて SORT と LIMIT を追加します

6. POST /_query を使用してクエリを実行します。読みやすく、後処理しやすい、装飾のないすっきりとした結果を得るため、表形式（TSV）で出力するようリクエストしてください。

ES|QL クイックリファレンス

バージョンの提供状況： 読みやすさのため、このセクションではバージョンの注釈を省略しています。Elasticsearch のバージョンごとの機能の提供状況については、 ES|QL バージョン履歴を確認してください。

基本構造

FROM index-pattern
| WHERE condition
| EVAL new_field = expression
| STATS aggregation BY grouping
| SORT field DESC
| LIMIT n

よくあるパターン

フィルタリングと件数制限：

FROM logs-*
| WHERE @timestamp > NOW() - 24 hours AND level == "error"
| SORT @timestamp DESC
| LIMIT 100

時間で集計する場合： 時系列（TSDS）インデックスでは、FROM と DATE_TRUNC の組み合わせよりも、TRANGE と TBUCKET を伴う TS を優先してください（下記の時系列セクションを参照）。

TS metrics-*
| WHERE TRANGE(7 days)
| STATS avg_cpu = AVG(cpu.percent) BY bucket = TBUCKET(1 hour)
| SORT bucket DESC

件数を含む上位 N 件：

FROM web-logs
| STATS count = COUNT(*) BY response.status_code
| SORT count DESC
| LIMIT 10

テキスト検索（8.17 以降）： 全文検索では、LIKE／RLIKE の代わりに MATCH をデフォルトとして使用してください。大幅に高速で、関連度スコアリングにも対応しています。text フィールドに対する MATCH だけで通常は十分です。ユーザーが明示的にフィルタリングを要求していない限り、MATCH に加えて冗長なキーワードの等価条件（例：category == "X"）を追加しないでください。高度なブール論理、ワイルドカード、または1つの式での複数フィールド検索が必要な場合にのみ QSTR を使用してください。MATCH の最初の引数には、実在するフィールド名を1つ指定する必要があります。複数のフィールドを並べた文字列（例："title,content"）や、複数のフィールド引数は指定できません。MATCH(a, "q") OR MATCH(b, "q") のようにフィールドを組み合わせてください。KQL は 8.18／9.0 以降で利用できます。コンテンツ／ドキュメント検索のユースケースでは、ES|QL 検索戦略に従ってください。関数の詳しいガイドについては、ES|QL 検索リファレンスを参照してください。

FROM documents METADATA _score
| WHERE MATCH(content, "search terms")
| SORT _score DESC
| LIMIT 20

文字列の抽出： 構造化された区切り文字ベースのパターンには DISSECT（推奨 — 名前付きフィールドを生成）を、正規表現ベースの抽出には GROK を使用します。単純なケースでは、固定位置から抽出する SUBSTRING(s, start, len)、 複数値に分割する SPLIT(s, delim)、文字の位置を検索する LOCATE(substr, s) を使用します。SPLIT は複数値を返すため、要素を選ぶには MV_FIRST、MV_LAST、または MV_SLICE を使用します。INSTR と STRPOS は存在しないため、LOCATE を使用します。 REGEXP_EXTRACT は存在しないため、GROK を使用します。

// Extract domain from email using DISSECT (preferred — produces named fields)
FROM customers
| DISSECT email "%{local}@%{domain}"
| STATS count = COUNT(*) BY domain

// Alternative: extract domain from email using SPLIT
FROM customers
| EVAL domain = MV_LAST(SPLIT(email, "@"))
| STATS count = COUNT(*) BY domain

// Parse HTTP log lines
FROM logs-*
| DISSECT message "%{method} %{path} %{status_text}"
| KEEP @timestamp, method, path, status_text

ログの分類（Platinum ライセンス）： CATEGORIZE を使用して、ログメッセージをパターングループに自動クラスタリングします。非構造化テキストを調査したりパターンを見つけたりする際は、 複数の STATS ... BY field クエリを実行するよりも、こちらを優先してください。

FROM logs-*
| WHERE @timestamp > NOW() - 24 hours
| STATS count = COUNT(*) BY category = CATEGORIZE(message)
| SORT count DESC
| LIMIT 20

変化点の検出（Platinum ライセンス）： CHANGE_POINT を使用して、メトリック系列の急増、急減、トレンドの変化を検出します。時間バケットごとの件数を手動で調べるよりも、 こちらを優先してください。

FROM logs-*
| STATS c = COUNT(*) BY t = BUCKET(@timestamp, 30 seconds)
| SORT t
| CHANGE_POINT c ON t
| WHERE type IS NOT NULL

時系列メトリック： TS では、時間によるフィルタリングに TRANGE（9.3 以降）を使用するか、完全に省略します。TBUCKET と併せて冗長な WHERE @timestamp > NOW() - ... を追加しないでください。TBUCKET の期間によって集計ウィンドウが定義されます。

// Counter metric: SUM(RATE(...)) with TBUCKET(duration)
TS metrics-tsds
| WHERE TRANGE(1 hour)
| STATS SUM(RATE(requests)) BY TBUCKET(1 hour), host

// Gauge metric: AVG(...) — no RATE needed
TS metrics-tsds
| STATS avg_cpu = AVG(cpu) BY service.name, bucket = TBUCKET(5 minutes)
| SORT bucket

// Histogram metric: standard aggregation (merge); cast for wildcard/mixed streams
TS metrics-*
| STATS total_gc = SUM(jvm.gc.duration::exponential_histogram) BY TBUCKET(1 hour), service.name

PromQL 構文による時系列（9.4 以降のプレビュー）： ユーザーが明示的に PromQL を求めている場合、Prometheus 構文（sum by (instance) (...)、{cluster="prod"} などのラベルマッチャー）を参照している場合、または Prometheus のダッシュボードやアラートを移行している場合は、ソースコマンド PROMQL を使用します。PROMQL コマンドは、オプションの index、step、 buckets、start、end、scrape_interval を指定して標準の PromQL を受け付け、後続の ES|QL パイプラインで処理できるテーブルを生成します。範囲セレクターは省略可能です。省略した場合、ウィンドウは max(step, scrape_interval) になります。それ以外の場合は TS（9.4 で GA）を優先してください。 PROMQL はグループ修飾子、集合演算子（or／and／unless）、histogram_quantile、predict_linear、label_join などの関数をサポートしていません。これらには TS を使用してください。詳細は PROMQL Command を参照してください。

// Adaptive Kibana query — date picker drives time range and step
PROMQL index=metrics-* sum by (instance) (rate(http_requests_total))

// Named result, post-processed with ES|QL
PROMQL index=k8s step=1h bytes=(max by (cluster) (network.bytes_in))
| STATS max_bytes = MAX(bytes) BY cluster
| SORT cluster

LOOKUP JOIN によるデータの拡充： 基本の ON 句では、両方のインデックス内にあるフィールド名を照合します （LOOKUP JOIN idx ON field_name）。結合キーの名前がソース内で異なる場合は、まず RENAME を使用して名前を揃えます。9.2 以降のテクニカルプレビューでは、式による述語（ON expr == expr）もサポートされています。詳細は ES|QL Complete Reference を参照してください。LOOKUP JOIN の後は、ルックアップ列を元のフィールド名で参照できます。テーブル名を付けないでください（たとえば、threat_intel.threat_level ではなく threat_level と記述します）。並べ替えのヒント： 質問が上位 N 件の結果を求めている場合は、拡充コストを抑えるため、LOOKUP JOIN の前に SORT と LIMIT を指定します。一般的な一覧表示や完全なデータ拡充では、FROM／WHERE の直後に LOOKUP JOIN を配置してください。

// Field name mismatch — RENAME before joining
FROM support_tickets
| RENAME product AS product_name
| LOOKUP JOIN knowledge_base ON product_name

// Aggregate, limit, THEN enrich (top-N only)
FROM orders
| STATS total_spent = SUM(total) BY customer_id
| SORT total_spent DESC
| LIMIT 3
| LOOKUP JOIN customers_lookup ON customer_id
| KEEP name, customer_id, total_spent

// Multi-field join (9.2+)
FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment
| KEEP service_name, environment, owner_team

複数値フィールドのフィルタリング： 複数値フィールドに特定の値が含まれているか確認するには MV_CONTAINS を使用します。値の数を数えるには MV_COUNT を使用します。

// Filter by multivalue membership
FROM employees
| WHERE MV_CONTAINS(languages, "Python")

// Find entries matching multiple values
FROM employees
| WHERE MV_CONTAINS(languages, "Java") AND MV_CONTAINS(languages, "Python")

// Count multivalue entries
FROM employees
| EVAL num_languages = MV_COUNT(languages)
| SORT num_languages DESC

変化点の検出（別の例）： ユーザーが急増、急減、異常について尋ねた場合に使用します。時間バケットでの集計、SORT、その後の CHANGE_POINT が必要です。

FROM logs-*
| STATS error_count = COUNT(*) BY bucket = DATE_TRUNC(1 hour, @timestamp)
| SORT bucket
| CHANGE_POINT error_count ON bucket AS type, pvalue

近似 STATS（9.5 以降／Serverless で GA、9.4 でプレビュー）： 正確な値が不要な大規模データセットで、サンプリングと外挿による高速な推定値を取得するには、STATS クエリの先頭に SET approximation=true; を追加します。結果には推定値ごとに _approximation_confidence_interval(col) 列と _approximation_certified(col) 列が追加されます。これらの範囲を報告し、推定値を正確な値として提示しないでください。COUNT_DISTINCT、MIN、MAX、FIRST、LAST、TOP（およびその他いくつか）はサポートされておらず、正確な実行にフォールバックします。これらには SAMPLE コマンドを使用してください。STATS が 2 つ以上あるパイプラインや、ソースコマンド TS／PROMQL を使用するパイプラインもフォールバックします。Query Approximation を参照してください。

SET approximation=true;
FROM web_traffic
| WHERE @timestamp >= NOW() - 1 week
| STATS total_hits = COUNT(*), avg_load_time = AVG(page_load_ms) BY country_code
| SORT total_hits DESC
| LIMIT 5

完全なリファレンス

すべてのコマンド、関数、演算子を含む ES|QL 構文の完全な情報については、以下を参照してください。

• ES|QL 完全リファレンス
• ES|QL 検索リファレンス - 全文検索：MATCH、QSTR、KQL、MATCH_PHRASE、スコアリング、 セマンティック検索
• ES|QL 検索戦略 - コンテンツインデックス向けの関連性検索戦略：取得 → 融合 → 再ランキング
• ES|QL バージョン履歴 - Elasticsearch のバージョンごとの機能の利用可否
• クエリパターン - 自然言語から ES|QL への変換
• 生成のヒント - クエリ生成のベストプラクティス
• 時系列クエリ - TS コマンド、時系列集計関数、TBUCKET
• PROMQL コマンド - TSDS インデックス向けの PromQL ソースコマンド（9.4+ プレビュー）
• クエリの近似 - サンプリング／外挿による近似 STATS（9.5+/Serverless で GA、 9.4 でプレビュー）
• DSL から ES|QL への移行 - Query DSL を ES|QL に変換

エラー処理

クエリの実行に失敗した場合は、Elasticsearch のエラーメッセージを読み、クエリを修正してください。よくある問題は次のとおりです。

• フィールドが存在しない → クエリを書く前に必ずマッピング（GET /{index}/_mapping）を確認し、インデックス一覧（GET /_cat/indices）を取得してください。 フィールド名やインデックス名はデプロイごとに異なるため、決して推測しないでください。
• 型が一致しない → 型変換関数（TO_STRING、TO_INTEGER など）を使用してください。
• 構文エラー → 正しい構文について ES|QL リファレンスを確認してください。文字列には必ず二重引用符を使用し、単一引用符は使用しないでください。
• 結果がない → 時間範囲とフィルター条件を確認してください。
• 関数名が誤っている → ES|QL ではアンダースコアを含む名前を使用します。STDDEV() ではなく STD_DEV()、MAD() ではなく MEDIAN_ABSOLUTE_DEVIATION() を使用してください。文字列には + ではなく CONCAT() を使用してください。CASE WHEN...THEN...END ではなく CASE(cond, val, ...) を使用してください。
• 日付の部分が誤っている → DATE_EXTRACT では ES|QL の部分名を使用します。"hour" ではなく "hour_of_day"、"day" ではなく "day_of_month"、 "month" ではなく "month_of_year" を使用してください。日付の計算には減算ではなく DATE_DIFF("day", start, end) を使用してください。

例

各例では、まずマッピングを確認してから、最も簡潔で正しいクエリを書く手順に従います。

「直近1時間のリクエスト数が多い送信元 IP アドレス上位10件」 — 時間範囲で絞り込んでから、集計して順位付けします。

FROM logs-*
| WHERE @timestamp > NOW() - 1 hour
| STATS requests = COUNT(*) BY source.ip
| SORT requests DESC
| LIMIT 10

「5xx レスポンスのみを対象とした、サービスごとの平均応答時間」 — 集計前にエラーに絞り込みます。

FROM traces-*
| WHERE http.response.status_code >= 500
| STATS avg_ms = AVG(duration_ms) BY service.name
| SORT avg_ms DESC

「直近1週間の日ごとのエラー数」 — DATE_TRUNC で日単位に区切ります。

FROM logs-*
| WHERE log.level == "error" AND @timestamp > NOW() - 7 days
| STATS errors = COUNT(*) BY day = DATE_TRUNC(1 day, @timestamp)
| SORT day ASC

ガイドライン

• クエリの前に確認する。 クエリを書く前にマッピング（GET /{index}/_mapping）を読み、インデックス一覧（GET /_cat/indices）を取得してください。 フィールド名やインデックス名を決して推測しないでください。
• 早い段階で絞り込む。 集計対象の行数を最小限にするため、STATS の前に WHERE を置いてください。
• 常に結果を制限する。 調査用のクエリは LIMIT で終えてください。
• 引用符を正しく使う。 文字列リテラルには二重引用符を使用し、単一引用符は使用しないでください。
• バージョンごとの利用条件を守る。 LOOKUP JOIN や INLINE STATS などの新しいコマンドを使用する前に、GET /（build_flavor、version.number）と references/esql-version-history.md で機能の利用可否を確認してください。
• エラーが出たら修正し、推測しない。 Elasticsearch のエラーを読み、該当する問題を修正して再実行してください。

Operations

HTTP API (shorthand)	elastic CLI command
GET /	elastic es info
GET /_cat/indices	elastic es cat indices --index '<pattern>'
GET /{index}/_mapping	elastic es indices get-mapping --index '<index>'
GET /{index}/_settings/index.mode	elastic es indices get-settings --index '<index>' --name index.mode
POST /_query	elastic es esql query --format tsv --query "<esql>"