eventhouse-consumption-cli について
Microsoft Fabric Eventhouse のデータ探索向けコマンドラインスキルです。エージェントによるスキーマ確認と読み取り専用 KQL クエリを支援し、接続、認証、クエリ作成、結果処理、監視診断を扱います。
主な機能
- 01az CLI による Fabric ワークスペースと項目の検索
- 02読み取り専用 KQL クエリの実行
- 03クエリ作成前のスキーマ確認
- 04クエリ性能とセキュリティの指針
- 05クエリ結果の整形とエクスポート
- 06実行中のクエリとコマンドの監視
活用シーン
- 01未知の Eventhouse テーブルの探索
- 02時間範囲を指定したイベントや指標の分析
- 03クエリタイムアウトや空の結果の診断
- 04Eventhouse のクエリ活動の監視
MCP 対応
エージェント統合ワークフローでは Fabric KQL MCP サーバーの利用を推奨しています。主なクエリ手順は az rest を使用します。
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/eventhouse-consumption-cliを入力して読み込まれたか確認します。
同梱ファイルreferences/discovery-queries.md
詳細
更新の確認 — セッションごとに1回（必須） このスキルをセッションで初めて使用するときは、続行する前に check-updates スキルを実行してください。
- GitHub Copilot CLI / VS Code：
check-updatesスキルを呼び出してください。- Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルとリモートの package.json のバージョンを比較してください。
- このセッション中にすでに確認を実施している場合は、スキップしてください。
重要な注意事項
- ワークスペース名から詳細（ID を含む）を見つけるには、すべてのワークスペースを一覧表示してから、JMESPath フィルタリングを使用してください。
- ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（ID を含む）を見つけるには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示してから、JMESPath フィルタリングを使用してください。
eventhouse-consumption-cli — CLI 経由の読み取り専用 KQL クエリ
目次
ツールスタック
| ツール | 用途 | インストール |
|---|---|---|
| az cli | Kusto REST API を介した KQL クエリと管理コマンド、Fabric コントロールプレーンの検出 | winget install Microsoft.AzureCLI |
| jq | JSON の処理と出力のフォーマット | winget install jqlang.jq |
接続
ステップ 1 — KQL データベースのクエリ URI を検出する
# Get workspace ID (if not known)
WS_ID=$(az rest --method GET \
--url "https://api.fabric.microsoft.com/v1/workspaces" \
--resource "https://api.fabric.microsoft.com" \
| jq -r '.value[] | select(.displayName=="MyWorkspace") | .id')
# List KQL Databases and get connection properties
az rest --method GET \
--url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/kqlDatabases" \
--resource "https://api.fabric.microsoft.com" \
| jq '.value[] | {name: .displayName, id: .id, queryUri: .properties.queryServiceUri, dbName: .properties.databaseName}'
ステップ 2 — 接続変数を設定する
CLUSTER_URI="https://<cluster>.kusto.fabric.microsoft.com"
DB_NAME="MyKqlDatabase"
ステップ 3 — 接続を確認する
重要 — ボディファイルのパターン：KQL クエリには
|（パイプ）文字が含まれており、bash と PowerShell の両方でシェルのエスケープ処理が壊れます。必ず JSON ボディを一時ファイルに書き込み、--body @<file>で参照してください。これは、すべてのaz restKQL 呼び出しで推奨される方法です。 PowerShell では、@{db="X";csl="..."} | ConvertTo-Json -Compress | Out-File $env:TEMP\kql_body.json -Encoding utf8NoBOMを使用してから、--body "@$env:TEMP\kql_body.json"を指定してください。
# Write body to temp file (avoids pipe escaping issues)
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyKqlDatabase","csl":"print Message = 'Connected successfully', Cluster = current_cluster_endpoint(), Timestamp = now()"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
| jq '.Tables[0].Rows'
エージェントによる探索
「データとチャット」— 検出シーケンス
ユーザーがテーブルを指定せずに Eventhouse の探索やクエリを依頼した場合：
Step 1 → .show tables // discover tables
Step 2 → .show table <TABLE> schema as json // understand columns + types
Step 3 → <TABLE> | take 10 // see sample data
Step 4 → <TABLE> | summarize count() by bin(Timestamp, 1h) | render timechart // shape of data
Step 5 → Formulate targeted query based on user's question
スキーマを考慮したクエリの生成
スキーマを検出した後は、実際の列名と型を使ってクエリを生成します。
// Example: user asks "show me errors in the last hour"
// After discovering table "AppEvents" with columns: Timestamp, Level, Message, Source
AppEvents
| where Timestamp > ago(1h)
| where Level == "Error"
| summarize ErrorCount = count() by Source, bin(Timestamp, 5m)
| order by ErrorCount desc
クエリの実行
az rest 経由
--bodyには必ず一時ファイルのパターンを使用してください。KQL のパイプ（|）は、インラインのシェルエスケープを壊します。
# Run a KQL query
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":"Events | where Timestamp > ago(1h) | count"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
| jq '.Tables[0].Rows'
出力のフォーマット
# Pretty-print results as a table with jq
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":".show tables"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
| jq '.Tables[0] | [.Columns[].ColumnName] as $cols | .Rows[] | [$cols, .] | transpose | map({(.[0]): .[1]}) | add'
# Save results to file
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":"Events | where Timestamp > ago(1h) | summarize count() by EventType"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
--output-file results.json
監視
// Active queries
.show queries
// Recent commands (last hour)
.show commands
| where StartedOn > ago(1h)
| project StartedOn, CommandType, Text = substring(Text, 0, 80), Duration, State
| order by StartedOn desc
// Ingestion failures (for context when data seems stale)
.show ingestion failures
| where FailedOn > ago(24h)
| summarize count() by ErrorCode
| top 5 by count_
必須事項／推奨事項／回避事項／トラブルシューティング
必須事項
- 必ず時間フィルターを含めてください — 時系列テーブルでは、
where Timestamp > ago(...)を指定する必要があります。 - クエリを実行する前にスキーマを検出してください — 最初に
.show tablesと.show table T schema as jsonを実行します。 - 用語の検索には
hasを使用してください — インデックスが使われるため高速です。部分文字列の検索が必要な場合に限り、containsにフォールバックします。 - クラスター URI を確認してください — KQL データベースの URI は項目ごとに異なるため、必ず Fabric REST API 経由で解決します。
推奨事項
- CLI でのクエリセッションには
az restを、エージェントと統合されたワークフローには Fabric KQL MCP サーバー を使用します。 - 集計の前に、早い段階で
projectを使って不要な列を除外します。 - サブ式を複数回使用する場合は
materialize()を使用します。 - 初回の探索では
take 100を使用し、テーブル全体のスキャンは避けます。 - 時系列には
render timechartを、分布にはrender piechartを使用します。
回避事項
- 大きなテーブルでの
contains— インデックスが使われず、全件スキャンになります。hasまたはhas_csを使用してください。 - 両方のテーブルを先にフィルタリングせずに
joinを使用すること — メモリが急増します。 - 幅の広いテーブルでの
SELECT *相当の処理（すべての列をprojectすること）。 - 時系列の
summarizeでのbin()の省略 — タイムスタンプごとに 1 行が生成されます。 - クラスター URI のハードコード — 必ず Fabric REST API または環境変数から解決してください。
トラブルシューティング
| 症状 | 対処方法 |
|---|---|
az rest の認証に失敗する | 最初に az login を実行し、--resource "https://kusto.kusto.windows.net" が設定されていることを確認します |
| 有効なテーブルなのに結果が空になる | データベースのコンテキストを確認します。database("name").table が必要な場合があります |
| クエリがタイムアウトする | 時間フィルターの範囲を狭め、競合するクエリがないか .show queries で確認します |
Forbidden (403) | KQL データベースで viewer ロールをリクエストします |
| 結果が切り詰められる | デフォルトの上限は 500K 行です。クエリの前に set truncationmaxrecords = N; を追加します |
KQL のパイプ | が PowerShell または bash で問題を起こす | KQL を --body にインラインで指定しないでください。JSON を一時ファイルに書き込み、--body @file.json を使用します（クエリの実行を参照） |
例
例 1：検出してクエリを実行する
# 1. Set connection variables (after discovering URI via Step 1)
CLUSTER_URI="https://<your-cluster>.kusto.fabric.microsoft.com"
DB_NAME="SalesDB"
# 2. Discover tables
cat > /tmp/kql_body.json << EOF
{"db":"${DB_NAME}","csl":".show tables"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
| jq '.Tables[0].Rows'
# 3. Explore schema
cat > /tmp/kql_body.json << EOF
{"db":"${DB_NAME}","csl":".show table Orders schema as json"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
| jq '.Tables[0].Rows'
# 4. Sample data
cat > /tmp/kql_body.json << EOF
{"db":"${DB_NAME}","csl":"Orders | take 10"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
| jq '.Tables[0].Rows'
// 5. Analytical query (via az rest --body @file)
Orders
| where OrderDate > ago(30d)
| summarize
TotalOrders = count(),
TotalRevenue = sum(Amount)
by bin(OrderDate, 1d)
| render timechart
例 2：データベースをまたぐクエリ
// Query across KQL databases in the same Eventhouse
let orders = database("SalesDB").Orders | where OrderDate > ago(7d);
let products = database("CatalogDB").Products;
orders
| join kind=inner (products) on ProductId
| summarize Revenue = sum(Amount) by ProductName
| top 10 by Revenue desc
例 3：結果をファイルにエクスポートする
# Run query and save results to JSON
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":"Events | where Timestamp > ago(1d) | summarize count() by EventType"}
EOF
az rest --method POST \
--url "${CLUSTER_URI}/v1/rest/query" \
--resource "https://kusto.kusto.windows.net" \
--headers "Content-Type=application/json" \
--body @/tmp/kql_body.json \
--output-file results.json
# Convert to CSV with jq
cat results.json \
| jq -r '.Tables[0] | (.Columns | map(.ColumnName)), (.Rows[]) | @csv' > results.csv
エージェント統合に関する注意事項
- このスキルは読み取り専用です。データベースオブジェクトの作成、変更、削除は行いません。
- オーサリング操作（テーブル管理、データ取り込み、ポリシー）については、eventhouse-authoring-cliに委任してください。
- ワークロードをまたぐオーケストレーション（Spark + SQL + KQL）については、FabricDataEngineerエージェントに委任してください。
- エージェント統合によるクエリ実行には、
az restの代わりにFabric KQL MCP server（mcp-setup/mcp-config-template.json内のfabric-kql）を使用できます。
コメント
Markdown 対応