Elasticsearch ES|QL

Elasticsearch に対して ES|QL クエリを実行します。

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 を使用してください（生成のヒントを参照）。INLINE STATS とカウンターフィールドの RATE() は 9.2 より前ではフォールバックがありません。references/esql-version-history.md でバージョン別の機能の利用可能性を確認してください。

クラスタ検出： GET / レスポンスを使用してクラスタ タイプとバージョンを確認します：

• build_flavor: "serverless" — Elastic Cloud Serverless。version.number は積極的に開発中のスタック ライン（メインからの次のマイナー バージョン）を追跡するため、semver でのみ比較するクライアントは Serverless を「最新」として扱う可能性があります。機能をゲートするために version.number を使用しないでください。build_flavor が "serverless" の場合、すべての GA およびプレビュー ES|QL 機能が利用可能と想定してください。
• build_flavor: "default" — セルフマネージドまたは Elastic Cloud ホステッド。機能の利用可能性について version.number を使用してください。
• スナップショット ビルドは 9.4.0-SNAPSHOT のような version.number を持ちます。-SNAPSHOT サフィックスを削除し、バージョン チェックに major.minor を使用してください。スナップショット ビルドはそのバージョンからのすべての機能に加えて、開発中の潜在的に未リリース機能を含みます。クエリが未知の関数/コマンドで失敗した場合、単にまだランディングしていない可能性があります。Elastic の従業員は一般的にテスト用にスナップショット ビルドを使用します。

環境構成

完全な接続構成オプション（Elastic Cloud、直接 URL、基本認証、ローカル開発）については、環境セットアップ を参照してください。

接続を確認するには、node scripts/esql.js test を実行してください。テストが失敗した場合、ユーザーに環境セットアップ ガイドを参照するよう指示してから、停止してください。接続テストが成功するまで、さらに探索を試みないでください。

使用方法

インデックス情報の取得（スキーマ発見用）

node scripts/esql.js indices                    # すべてのインデックスをリスト
node scripts/esql.js indices "logs-*"           # マッチするインデックスをリスト
node scripts/esql.js schema "logs-2024.01.01"   # インデックスのフィールド マッピングを取得

生の ES|QL を実行

node scripts/esql.js raw "FROM logs-* | STATS count = COUNT(*) BY host.name | SORT count DESC | LIMIT 5"

TSV 出力で実行

node scripts/esql.js raw "FROM logs-* | STATS count = COUNT(*) BY component | SORT count DESC" --tsv

TSV 出力オプション：

• --tsv または -t：タブ区切り値として出力（クリーン、装飾なし）
• --no-header：ヘッダー行を省略

接続をテスト

node scripts/esql.js test

ガイドライン

1. デプロイメント タイプを検出：常に最初に node scripts/esql.js test を実行してください。これはデプロイメントが Serverless プロジェクト（すべての機能が利用可能）かバージョン付きクラスタ（機能はバージョンに依存）かを検出します。GET / からの build_flavor フィールドが公式な信号です。"serverless" に等しい場合、報告されたバージョン番号を無視し、すべての ES|QL 機能を自由に使用してください。

2. スキーマを発見（必須 — インデックス名またはフィールド名を推測しないでください）：

   node scripts/esql.js indices "pattern*"
   node scripts/esql.js schema "index-name"
   

   クエリを生成する前に、常にスキーマ発見を実行してください。インデックス名とフィールド名はデプロイメント間で異なり、確実に推測することはできません。一般的に聞こえるデータでも（例：「ログ」）、logs-test、logs-app-*、または application_logs という名前のインデックスに存在する可能性があります。フィールド名は ECS ドット表記（source.ip、service.name）またはフラットなカスタム名を使用する場合があります。確実に知る唯一の方法は確認することです。

   シンプルさを優先：ユーザーが複数のソースにまたがるデータを明示的に要求しない限り、単一のインデックスをクエリしてください。異なるスキーマを持つインデックスを COALESCE を使用して結合しないでください。特に要求されている場合を除き、最も関連のある単一のインデックスを選択してください。複数のインデックスに同様のデータが含まれている場合、タスクに最も完全なスキーマを持つものを優先してください。

   schema コマンドはインデックス モードをレポートします。Index mode: time_series と表示される場合、出力にはデータ ストリーム名とコピー可能な TS 構文が含まれます。TS <data-stream>（FROM ではなく）、TBUCKET(interval)（DATE_TRUNC ではなく）を使用し、カウンター フィールドを SUM(RATE(...)) でラップしてください。時系列クエリを作成する前に、生成のヒント の完全な TS セクションを読んでください。Elasticsearch インデックス設定 API を使用してインデックス モードを直接確認することもできます：

   curl -s "$ELASTICSEARCH_URL/<index-name>/_settings/index.mode" -H "Authorization: ApiKey $ELASTICSEARCH_API_KEY"
   

3. タスクに適切な ES|QL 機能を選択：クエリを作成する前に、ユーザーの意図を最も適切な ES|QL 機能にマッピングしてください。複数の基本的なクエリより単一の高度なクエリを優先してください。

   • 「パターンを検索」、「分類」、「類似メッセージをグループ化」 → CATEGORIZE(field)
   • 「スパイク」、「ディップ」、「異常」、「いつ X が変更されたか」 → CHANGE_POINT value ON key
   • 「時系列トレンド」、「時系列」 → STATS ... BY BUCKET(@timestamp, interval) または TSDB 用 TS
   • 「検索」、「マッチするドキュメントを検索」 → MATCH（デフォルト）、QSTR（高度なブール）、KQL（Kibana 移行）。コンテンツ/ドキュメント関連性検索については、ES|QL 検索戦略 に従ってください。
   • 「カウント」、「平均」、「内訳」 → STATS と集計関数

4. クエリを生成する前にリファレンスを読む：

   • 生成のヒント - 主なパターン（TS/TBUCKET/RATE、集計ごとの WHERE、LOOKUP JOIN、CIDR_MATCH）、一般的なテンプレート、曖昧さの処理
   • 時系列クエリ - 任意の TS クエリの前に読んでください：内部/外部集計モデル、TBUCKET 構文、RATE 制約
   • ES|QL 完全リファレンス - すべてのコマンドと機能の完全な構文
   • ES|QL 検索戦略 — コンテンツ/ドキュメント関連性検索用（取得 → 融合 → 再ランク）
   • ES|QL 検索リファレンス — フルテキスト検索関数構文用（MATCH、QSTR、KQL、スコアリング）

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

   • FROM index-pattern（または時系列インデックスの場合 TS index-pattern）で開始
   • フィルタリング用に WHERE を追加（9.3+ の時間範囲に TRANGE を使用）
   • 計算フィールド用に EVAL を使用
   • 集計用に STATS ... BY を使用
   • 時系列メトリクスの場合：TS で SUM(RATE(...))（カウンター用）、AVG(...)（ゲージ用）、TBUCKET(interval)（時間バケッティング用）を使用。生成のヒント の TS セクションを参照して、3 つの重要な構文規則を確認してください。
   • スパイク、ディップ、または異常を検出する場合、時間バケット集計後に CHANGE_POINT を使用
   • 必要に応じて SORT と LIMIT を追加

6. TSV フラグで実行：

   node scripts/esql.js raw "FROM index | STATS count = COUNT(*) BY field" --tsv
   

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

バージョン利用可能性： このセクションは読みやすさのためにバージョン注釈を省略しています。ES|QL バージョン履歴 で Elasticsearch バージョン別の機能の利用可能性を確認してください。

基本構造

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

時間別集計：

FROM metrics-*
| WHERE @timestamp > NOW() - 7 days
| STATS avg_cpu = AVG(cpu.percent) BY bucket = DATE_TRUNC(1 hour, @timestamp)
| SORT bucket DESC

カウント付き Top 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"）を追加しないでください。ユーザーが明示的にフィルタリングをリクエストした場合のみです。高度なブール ロジック、ワイルドカード、または単一の式での複数フィールド検索が必要な場合は、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 を使用してください。

// DISSECT を使用してメール から ドメインを抽出（優先 — 名前付きフィールドを生成）
FROM customers
| DISSECT email "%{local}@%{domain}"
| STATS count = COUNT(*) BY domain

// 代替案：SPLIT を使用してメール から ドメインを抽出
FROM customers
| EVAL domain = MV_LAST(SPLIT(email, "@"))
| STATS count = COUNT(*) BY domain

// HTTP ログ行を解析
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 の期間は集計ウィンドウを定義します。

// カウンター メトリック：SUM(RATE(...)) と TBUCKET(duration)
TS metrics-tsds
| WHERE TRANGE(1 hour)
| STATS SUM(RATE(requests)) BY TBUCKET(1 hour), host

// ゲージ メトリック：AVG(...) — RATE は不要
TS metrics-tsds
| STATS avg_cpu = AVG(cpu) BY service.name, bucket = TBUCKET(5 minutes)
| SORT bucket

LOOKUP JOIN によるデータ エンリッチメント： 基本的な ON 句は両方のインデックスのフィールド名でマッチします（LOOKUP JOIN idx ON field_name）。結合キーがソースで異なる名前を持つ場合、最初に RENAME を使用して名前を揃えます。9.2+ テック プレビューは式述語もサポートします（ON expr == expr）。詳細については、ES|QL 完全リファレンス を参照してください。LOOKUP JOIN の後、ルックアップ列は元のフィールド名で利用可能です — テーブル修飾を使用しないでください（例えば threat_intel.threat_level ではなく threat_level と記述してください）。順序のヒント： 質問が Top-N 結果を求める場合、エンリッチメント コストを削減するために LOOKUP JOIN の前に SORT と LIMIT を実行してください。一般的なリスティングまたは完全なエンリッチメントの場合、FROM/WHERE の直後に LOOKUP JOIN を配置します。

// フィールド名の不一致 — 結合の前に RENAME
FROM support_tickets
| RENAME product AS product_name
| LOOKUP JOIN knowledge_base ON product_name

// 集計、制限、次にエンリッチ（Top-N のみ）
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

// マルチフィールド結合（9.2+）
FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment
| KEEP service_name, environment, owner_team

マルチバリュー フィールド フィルタリング： MV_CONTAINS を使用して、マルチバリュー フィールドが特定の値を含むかどうかを確認してください。値をカウントするには MV_COUNT を使用してください。

// マルチバリュー メンバーシップでフィルタ
FROM employees
| WHERE MV_CONTAINS(languages, "Python")

// 複数の値にマッチするエントリを検索
FROM employees
| WHERE MV_CONTAINS(languages, "Java") AND MV_CONTAINS(languages, "Python")

// マルチバリュー エントリをカウント
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

完全リファレンス

すべてのコマンド、機能、および演算子を含む完全な ES|QL 構文については、以下を参照してください：

• ES|QL 完全リファレンス
• ES|QL 検索リファレンス - フルテキスト検索：MATCH、QSTR、KQL、MATCH_PHRASE、スコアリング、セマンティック検索
• ES|QL 検索戦略 - コンテンツ インデックスの関連性検索戦略：取得 → 融合 → 再ランク
• ES|QL バージョン履歴 - Elasticsearch バージョン別の機能の利用可能性
• クエリ パターン - 自然言語から ES|QL への翻訳
• 生成のヒント - クエリ生成のベストプラクティス
• 時系列クエリ - TS コマンド、時系列集計関数、TBUCKET
• DSL から ES|QL への移行 - Query DSL を ES|QL に変換
• 環境セットアップ - 接続構成オプション

エラー処理

クエリ実行が失敗すると、スクリプトは以下を返します：

• 生成された ES|QL クエリ
• Elasticsearch からのエラー メッセージ
• 一般的な問題の提案

一般的な問題：

• フィールドが存在しない → クエリを作成する前に、常に get_schema と list_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) を使用してください。

例

# スキーマ発見
node scripts/esql.js test
node scripts/esql.js indices "logs-*"
node scripts/esql.js schema "logs-2024.01.01"

# クエリ実行
node scripts/esql.js raw "FROM logs-* | STATS count = COUNT(*) BY host.name | LIMIT 10"
node scripts/esql.js raw "FROM metrics-* | STATS avg = AVG(cpu.percent) BY hour = DATE_TRUNC(1 hour, @timestamp)" --tsv