kql

KQL スキル

Azure データプラットフォーム全体で、KQL クエリの作成、デバッグ、最適化、変換、自動化を行います。

ワークフローの振り分け

ワークフロー	トリガー	ファイル
WriteQuery	「クエリを作成」「KQL を作成」「〜のクエリ」「〜のイベントを検索」「表示して」	workflows/WriteQuery.md
DebugOptimize	「最適化」「クエリが遅い」「この KQL を修正」「パフォーマンスを改善」「クエリをデバッグ」	workflows/DebugOptimize.md
Translate	「SQL を KQL に」「Splunk を KQL に」「SPL を KQL に」「このクエリを変換」	workflows/Translate.md
Tooling	「KQL を検証」「CLI でクエリを実行」「クエリを自動化」「アラートをスケジュール」「REST API」	workflows/Tooling.md

特定のワークフローに該当しない場合は、デフォルトで WriteQuery を使用します。

リファレンスファイル

必要に応じて読み込んでください。最初にすべてを読み込む必要はありません。

リファレンス	読み込むタイミング	ファイル
演算子と関数	クエリの作成またはレビュー時	references/operators.md
サービスのテーブル	特定のサービスで利用できるテーブルを確認するとき	references/service-tables.md
パターンとアンチパターン	クエリの最適化またはベストプラクティスのレビュー時	references/patterns.md
SQL から KQL への対応表	SQL から変換するとき	references/sql-to-kql.md

サンプルクエリ

samples/ ディレクトリには、サービス別に整理された、本番環境ですぐに使える .kql ファイルがあります。同様のクエリを作成するときに参照してください。期待されるファイル形式と規約が示されています。

出力形式

生成するクエリはすべて、次の .kql ファイル形式を使用する必要があります。

// ============================================================
// Title: <descriptive title>
// Service: <Log Analytics | Sentinel | ADX | App Insights>
// Tables: <comma-separated list of tables used>
// Description: <what this query does and when to use it>
// Parameters: <any variables the user should customize>
// Complexity: <Beginner | Intermediate | Advanced>
// ============================================================

// <the query, with inline comments for non-obvious logic>

ファイル名

kebab-case を使用します：failed-sign-ins-by-location.kql、high-cpu-vms-last-24h.kql

基本原則

1. 対象のサービスを必ず指定する — KQL は Azure サービスによって異なります。Sentinel 用のクエリが ADX でも動作するとは限りません。
2. デフォルトで時間範囲を指定する — テーブル全体のスキャンを防ぐため、TimeGenerated フィルター（または同等のフィルター）を含めます。ユーザーから別の指定がない限り、直近 24 時間をデフォルトにします。
3. パフォーマンスを最優先する — 早い段階でフィルターを適用し（join／summarize の前に where）、文字列の照合には contains より has を使い、列数の多いテーブルで * による射影を避けます。
4. パラメーター化する — ユーザーがカスタマイズする値（時間範囲、しきい値、リソース名）には let ステートメントを使います。
5. クエリを説明する — 特に mv-expand、parse、正規表現、複雑な summarize 式など、単純ではないロジックにはインラインコメントを追加します。

サービス固有の注意事項

• Log Analytics：管理コマンド（.create、.alter）は使用できません。テーブルには Heartbeat、Perf、Event、Syslog、AzureActivity などがあります。
• Sentinel：Log Analytics を拡張したもので、SecurityEvent、SecurityAlert、SigninLogs、ThreatIntelligenceIndicator に加え、カスタム分析ルール関数を利用できます。
• ADX：完全な KQL エンジンです。管理コマンド、マテリアライズドビュー、継続的なエクスポート、外部テーブルに対応しています。最も強力ですが、クエリの移植性がない場合があります。
• Application Insights：Log Analytics エンジンを共有しています。主なテーブルは requests、dependencies、exceptions、traces、customEvents、performanceCounters です。

例

例 1 — クエリの作成：

「過去 7 日間に米国以外から行われたサインイン失敗を検索する KQL クエリを作成して」 振り分け先：workflows/WriteQuery.md → Sentinel／Log Analytics を対象とし、SigninLogs を使用

例 2 — 最適化：

「このクエリの実行に非常に時間がかかります。速くできますか？」（KQL を貼り付け） 振り分け先：workflows/DebugOptimize.md

例 3 — 変換：

「この SQL クエリを KQL に変換して：SELECT * FROM events WHERE severity > 3 GROUP BY source」 振り分け先：workflows/Translate.md

例 4 — ツール：

「Azure CLI からこのクエリを実行して CSV にエクスポートするにはどうすればよいですか？」 振り分け先：workflows/Tooling.md

---

注意点

• ago() は行の時点ではなく、クエリの解析時に評価されます — where TimeGenerated > ago(1h) と | extend Age = now() - TimeGenerated では、使用される now() のスナップショットが数ミリ秒異なります。比較が重要な場合は、let now_ = now(); で値をキャッシュしてください。
• contains は大文字と小文字を区別せず、インデックスも使用しません。has はインデックスを使用しますが、トークン境界に限定されます。 where Message has "error" は errors（別のトークン）には一致しません。部分文字列の一致には、全件スキャンになることを理解したうえで contains_cs ／ contains を使用してください。
• by を指定しない summarize は1行を返し、グループ化に関する問題を隠します — by 句を忘れて1行だけ返された場合は、それが原因です。開発中は必ず、少なくとも1つのディメンションをプロジェクトしてください。
• クラスターをまたぐ join は問題ありませんが、ワークスペースをまたぐ join は、テーブル名が重複すると最初のワークスペースのデータセットまで暗黙的に切り詰められます。 両側で workspace("foo").Table の別名を使用してください。
• extend は遅延評価されます — その後の where は extend の計算前にフィルター処理されるため高速ですが、where で参照する列がすでに存在している必要があります。順序を入れ替え、先に where、次に extend を指定してください。
• Sentinel の SigninLogs と AADSignInEventsBeta は、スキーマが異なる別々のテーブルです — 一方を対象に作成したクエリをもう一方で実行すると、「列が見つからない」という分かりにくいエラーが発生します。print Tables = "<expected>" と getschema の結果を照合してください。
• Sentinel の分析ルールは、実行ごとに結果が最大10,000件に制限されます（通知なし） — 対話形式で5万行を返したハンティングクエリでも、アラートには1万件しか含まれません。テスト中に制限を明示するには、| take 10000 を指定してください。