eventhouse-authoring-cli

更新の確認 — セッションごとに1回（必須） このスキルをセッションで初めて使用する際は、先に check-updates スキルを実行してください。

• GitHub Copilot CLI / VS Code：check-updates スキルを呼び出してください。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルとリモートの package.json のバージョンを比較してください。
• このセッションで既に確認を実施している場合は、スキップしてください。

重要な注意事項

1. ワークスペース名からワークスペースの詳細（IDを含む）を取得するには、すべてのワークスペースを一覧表示し、その後、JMESPath で絞り込んでください。
2. ワークスペース ID、項目の種類、項目名から項目の詳細（IDを含む）を取得するには、そのワークスペース内の該当する種類の項目をすべて一覧表示し、その後、JMESPath で絞り込んでください。

eventhouse-authoring-cli — CLI による Eventhouse の作成と管理

目次

タスク	参照	備考
Fabric でワークスペースとアイテムを検索する	COMMON-CLI.md § Fabric でワークスペースとアイテムを検索する	必須 — 最初にリンクを読む [ワークスペース／アイテム ID の解決に必要]
Fabric のトポロジと主要概念	COMMON-CORE.md § Fabric のトポロジと主要概念	階層、Fabric 内の項目の検索
環境 URL	COMMON-CORE.md § 環境 URL	KQL クラスター URI、KQL インジェスト URI
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	対象が間違っていると 401 が発生します。KQL の対象：kusto.kusto.windows.net
コア コントロールプレーン REST API	COMMON-CORE.md § コア コントロールプレーン REST API	ワークスペースの一覧表示、アイテムの一覧表示、アイテムの作成
ページネーション	COMMON-CORE.md § ページネーション
長時間実行操作（LRO）	COMMON-CORE.md § 長時間実行操作（LRO）
レート制限とスロットリング	COMMON-CORE.md § レート制限とスロットリング
OneLake データアクセス	COMMON-CORE.md § OneLake データアクセス	Fabric トークンではなく、storage.azure.com トークンが必要です
ジョブの実行	COMMON-CORE.md § ジョブの実行
キャパシティ管理	COMMON-CORE.md § キャパシティ管理
注意事項とトラブルシューティング	COMMON-CORE.md § 注意事項とトラブルシューティング
ベストプラクティス	COMMON-CORE.md § ベストプラクティス
ツール選択の根拠	COMMON-CLI.md § ツール選択の根拠
認証レシピ	COMMON-CLI.md § 認証レシピ	az login のフローとトークンの取得
az rest による Fabric コントロールプレーン API	COMMON-CLI.md § az rest による Fabric コントロールプレーン API	必ず --resource https://api.fabric.microsoft.com を指定してください。指定しないと az rest は失敗します
ページネーションのパターン	COMMON-CLI.md § ページネーションのパターン
長時間実行操作（LRO）のパターン	COMMON-CLI.md § 長時間実行操作（LRO）のパターン
curl による OneLake データアクセス	COMMON-CLI.md § curl による OneLake データアクセス	az rest ではなく curl を使用してください（トークンの対象が異なります）
SQL / TDS データプレーンアクセス	COMMON-CLI.md § SQL / TDS データプレーンアクセス	sqlcmd（Go）— KQL には使用できませんが、ワークロード間のアクセスに便利です
ジョブの実行（CLI）	COMMON-CLI.md § ジョブの実行
OneLake ショートカット	COMMON-CLI.md § OneLake ショートカット
キャパシティ管理（CLI）	COMMON-CLI.md § キャパシティ管理
複合レシピ	COMMON-CLI.md § 複合レシピ
注意事項とトラブルシューティング（CLI 固有）	COMMON-CLI.md § 注意事項とトラブルシューティング（CLI 固有）	az rest の対象、シェルのエスケープ、トークンの有効期限
クイックリファレンス：az rest テンプレート	COMMON-CLI.md § クイックリファレンス：az rest テンプレート
クイックリファレンス：トークンの対象／CLI ツールの対応表	COMMON-CLI.md § クイックリファレンス：トークンの対象 ↔ CLI ツールの対応表	各サービスに使用する --resource とツール
作成機能の対応表	EVENTHOUSE-AUTHORING-CORE.md § 作成機能の対応表	最初に読む — KQL データベースとショートカット（読み取り専用）の違い。接続には Admin／Ingestor ロールが必要です
テーブル管理とスキーマの進化	EVENTHOUSE-AUTHORING-CORE.md § テーブル管理とスキーマの進化	テーブルの作成、Create-Merge（冪等）、変更／名前変更／削除、スキーマの進化（名前変更、入れ替え／ブルーグリーン）
インジェストとデータマッピング	EVENTHOUSE-AUTHORING-CORE.md § インジェストとデータマッピング	インライン、Set-or-Append／Replace、ストレージから、ストリーミング、データマッピング（CSV、JSON）
ポリシー	EVENTHOUSE-AUTHORING-CORE.md § ポリシー	保持、キャッシュ、パーティション分割、マージ
マテリアライズド ビュー	EVENTHOUSE-AUTHORING-CORE.md § マテリアライズド ビュー	作成、変更、ライフサイクル、サポートされる集計
ストアド関数と更新ポリシー	EVENTHOUSE-AUTHORING-CORE.md § ストアド関数と更新ポリシー	ストアド関数、更新ポリシー（インジェスト時の自動変換）
外部テーブル	EVENTHOUSE-AUTHORING-CORE.md § 外部テーブル	OneLake／ADLS 外部テーブル、外部テーブルへのクエリ
アクセス許可モデル	EVENTHOUSE-AUTHORING-CORE.md § アクセス許可モデル	データベースのロール、アクセス許可の付与
作成に関する注意事項とトラブルシューティング	EVENTHOUSE-AUTHORING-CORE.md § 作成に関する注意事項とトラブルシューティングのリファレンス	原因と修正方法を含む、番号付きの 10 個の問題
Bash テンプレート	authoring-script-templates.md § Bash テンプレート	テーブルの作成とインジェスト、スキーマのデプロイ、スキーマのエクスポート、保持／キャッシュの設定
PowerShell テンプレート	authoring-script-templates.md § PowerShell テンプレート	テーブルの作成とインジェスト、スキーマのデプロイ
ツールスタック	SKILL.md § ツールスタック
接続	SKILL.md § 接続
作成の範囲	SKILL.md § 作成の範囲
KQL コマンドの実行	SKILL.md § KQL コマンドの実行	az rest のパターン — JSON 本文を記述してから実行します
CLI によるテーブル管理	SKILL.md § CLI によるテーブル管理	テーブルの作成、列の追加、テーブルの削除
CLI によるデータのインジェスト	SKILL.md § CLI によるデータのインジェスト	インライン、ストレージから、OneLake から、Set-or-Append
CLI によるポリシー設定	SKILL.md § CLI によるポリシー設定	保持、キャッシュ、ストリーミング インジェスト
CLI によるマテリアライズド ビューの管理	SKILL.md § CLI によるマテリアライズド ビューの管理
CLI による関数と更新ポリシーの管理	SKILL.md § CLI による関数と更新ポリシーの管理	関数の作成、更新ポリシーの作成
CLI によるスキーマの進化	SKILL.md § CLI によるスキーマの進化	安全なスキーマ デプロイ スクリプト、現在のスキーマのエクスポート
作成操作の監視	SKILL.md § 作成操作の監視
必須／推奨／回避／トラブルシューティング	SKILL.md § 必須／推奨／回避／トラブルシューティング	必須／回避／推奨チェックリスト
エージェント型ワークフロー	SKILL.md § エージェント型ワークフロー	作成前の調査、スクリプト生成ワークフロー
例	SKILL.md § 例
エージェント統合に関する注意事項	SKILL.md § エージェント統合に関する注意事項

---

ツールスタック

ツール	用途	インストール
az cli	Kusto REST API を介した KQL 管理コマンド、Fabric コントロールプレーンの検出	winget install Microsoft.AzureCLI
jq	JSON の処理と出力の整形	winget install jqlang.jq

---

接続

イベントハウス消費 CLIと同じです。作成には昇格されたロールが必要です。

# Discover KQL Database query URI
WS_ID="<workspace-id>"
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, queryUri: .properties.queryServiceUri}'

# Set connection variables
CLUSTER_URI="https://<cluster>.kusto.fabric.microsoft.com"
DB_NAME="MyDatabase"

# Verify admin access
cat > /tmp/kql_body.json << EOF
{"db":"${DB_NAME}","csl":".show database ${DB_NAME} principals | where Role == 'Admin'"}
EOF
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/mgmt" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

---

作成の対象範囲

操作	コマンドパターン
テーブルの作成	.create-merge table T (cols)
列の追加	.alter-merge table T (NewCol: type)
テーブルの削除	.drop table T ifexists
データの取り込み	.ingest into table T (...)
保持期間の設定	.alter table T policy retention ...
キャッシュの設定	.alter table T policy caching hot = Nd
関数の作成	.create-or-alter function F() { ... }
マテリアライズドビューの作成	.create materialized-view MV on table T { ... }
更新ポリシーの作成	.alter table T policy update ...
データマッピングの作成	.create table T ingestion csv mapping ...

---

KQL コマンドの実行

このスキルのすべての KQL 管理コマンドは、同じ az rest パターンに従います。CLUSTER_URI と DB を設定した後、JSON 本文を /tmp/kql_body.json に書き込み、次のように実行します。

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":"<KQL management command>"}
EOF
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/mgmt" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

ネストされた JSON — KQL に埋め込み JSON（ポリシー、マッピング）が含まれるコマンドでは、シェルによるバックスラッシュでエスケープされた引用符の展開を防ぐため、<< 'EOF'（シングルクォートで囲んだもの）を使用し、${DB} をデータベース名のリテラルに置き換えてください。

PowerShell 相当のコマンド — @{db=$Database;csl=$Command} | ConvertTo-Json -Compress | Out-File $env:TEMP\kql_body.json -Encoding utf8NoBOM の後に、--body "@$env:TEMP\kql_body.json" を実行します。PowerShell テンプレートを参照してください。

---

CLI によるテーブル管理

テーブルの作成（冪等）

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".create-merge table Events (Timestamp: datetime, EventType: string, UserId: string, Properties: dynamic, Duration: real)"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

列の追加

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".alter-merge table Events (Region: string)"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

テーブルの削除

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".drop table Events ifexists"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

---

CLI によるデータの取り込み

インライン取り込み（テスト）

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".ingest inline into table Events <| 2025-01-15T10:00:00Z,Login,user1,{},0.5\n2025-01-15T10:01:00Z,Click,user2,{},0.2"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

ストレージからの取り込み

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".ingest into table Events (h'https://mystorage.blob.core.windows.net/data/events.csv.gz;impersonate') with (format='csv', ingestionMappingReference='EventsCsvMapping', ignoreFirstRecord=true)"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

OneLake からの取り込み

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".ingest into table Events (h'abfss://[email protected]/lakehouse.Lakehouse/Files/events.parquet;impersonate') with (format='parquet')"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

クエリからの Set-or-Append

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".set-or-append CleanEvents <| RawEvents | where IsValid == true | project Timestamp, EventType, UserId"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

---

CLI によるポリシー設定

保持期間

# Set 365-day retention
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":".alter table Events policy retention '{\"SoftDeletePeriod\":\"365.00:00:00\",\"Recoverability\":\"Enabled\"}'"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

キャッシュ（ホットキャッシュ）

# Keep last 30 days in hot cache
cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".alter table Events policy caching hot = 30d"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

ストリーミング取り込み

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".alter table Events policy streamingingestion enable"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

---

CLI によるマテリアライズドビューの管理

# Create materialized view with backfill
cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".create materialized-view with (backfill=true) HourlyEventCounts on table Events { Events | summarize Count = count(), LastSeen = max(Timestamp) by EventType, bin(Timestamp, 1h) }"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

# Check health
cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".show materialized-view HourlyEventCounts statistics"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

---

CLI による関数と更新ポリシーの管理

関数の作成

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".create-or-alter function with (docstring='Parse raw events', folder='ETL') ParseRawEvents() { RawEvents | extend Parsed = parse_json(RawData) | project Timestamp = todatetime(Parsed.timestamp), EventType = tostring(Parsed.eventType), UserId = tostring(Parsed.userId) }"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

更新ポリシーの作成

cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":".alter table ParsedEvents policy update @'[{\"IsEnabled\":true,\"Source\":\"RawEvents\",\"Query\":\"ParseRawEvents()\",\"IsTransactional\":true}]'"}
EOF

/tmp/kql_body.json を実行してください — KQL コマンドの実行を参照

---

CLI によるスキーマの進化

安全なスキーマデプロイスクリプト

管理コマンドを .kql ファイルに（1 行に 1 つずつ）保存し、az rest を使って各コマンドを実行します。

# deploy_schema.kql contains one command per line:
# .create-merge table Events (Timestamp: datetime, EventType: string, UserId: string, Properties: dynamic)
# .create-merge table ParsedEvents (Timestamp: datetime, EventType: string, UserId: string, PageName: string)
# .alter table Events policy retention '{\"SoftDeletePeriod\":\"365.00:00:00\",\"Recoverability\":\"Enabled\"}'
# .alter table Events policy caching hot = 30d

# Execute each command from the file (see "Execute KQL Command" section)
while IFS= read -r cmd; do
  [[ "$cmd" =~ ^// ]] && continue   # skip comment lines
  [[ -z "$cmd" ]] && continue        # skip blank lines
  cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":"${cmd}"}
EOF
  az rest --method POST \
    --url "${CLUSTER_URI}/v1/rest/mgmt" \
    --resource "https://kusto.kusto.windows.net" \
    --headers "Content-Type=application/json" \
    --body @/tmp/kql_body.json \
    | jq '.Tables[0].Rows'
done < deploy_schema.kql

現在のスキーマのエクスポート

cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".show database ${DB} schema as csl script"}
EOF
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/mgmt" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq -r '.Tables[0].Rows[][0]' > current_schema.kql

---

作成操作の監視

// Recent management commands
.show commands
| where StartedOn > ago(1h)
| project StartedOn, CommandType, Text = substring(Text, 0, 100), State, Duration
| order by StartedOn desc

// Ingestion failures
.show ingestion failures
| where FailedOn > ago(24h)
| summarize FailureCount = count() by ErrorCode, Table
| order by FailureCount desc

// Materialized view health
.show materialized-views
| project Name, IsEnabled, IsHealthy, MaterializedTo

---

必須事項／推奨事項／避けるべき事項／トラブルシューティング

必須

• 曖昧なプロンプトは実行前に確認する — リクエストで対象のテーブル、操作の種類、またはスキーマが指定されていない場合（例：「Eventhouse をセットアップして」「データベースを構成して」）、ユーザーに何をしたいのかを尋ねてください。意図を推測して管理コマンドを自律的に実行してはいけません。取り消せない副作用（ポリシーの変更、スキーマの変更、データの取り込み）には、明示的なユーザーの意図が必要です。
• 冪等性のあるコマンドを使用する — .create-merge table、.create-or-alter function、.create table ifnotexists。
• 作成前に権限を確認する — Admin または Ingestor ロールが必要です。
• 更新ポリシーをテストする — ポリシーを適用する前に、関数を単独で実行します。
• OneLake または Blob Storage から取り込む場合は、ストレージ URI に impersonate を含める。

推奨

• 複数コマンドのスキーマファイルをデプロイする場合は、ループと az rest を使用する。
• エージェントと統合された取り込みおよび管理のワークフローには、Fabric KQL MCP サーバーを使用する。
• 安全にスキーマを進化させるには、.create table より .create-merge table を使用する。
• 繰り返し実行する負荷の高い集計クエリには、マテリアライズドビューを使用する。
• スクリプトベースの CI/CD を使用する — .show database DB schema as csl script でスキーマをエクスポートし、git に保存します。

避けること

• ifexists を付けずに .drop table を実行すること — テーブルが存在しない場合に失敗します。
• 列の追加に .alter table を使用すること — 代わりに .alter-merge table を使用します（追加のみ）。
• CSV/JSON の取り込みでマッピングを指定しないこと — 列の順序やフィールド名が一致しない可能性があります。
• ストレージ URI をハードコードすること — スクリプト内でパラメーター化します。
• 再バックフィルのコストを理解せずにマテリアライズドビューを無効化すること。

トラブルシューティング

症状	対処方法
.create table が「already exists」で失敗する	.create-merge table または .create table ifnotexists を使用します
取り込みは成功するが、テーブルが空	データマッピングを確認します：.show table T ingestion csv mappings
更新ポリシーが実行されない	関数を単独で実行できることを確認し、.show table T policy update を確認します
管理コマンドで Forbidden (403) が発生する	admin または ingestor のデータベースロールを申請します
マテリアライズドビューが停止している	.show materialized-view MV statistics を確認します。.disable／.enable が必要な場合があります
OneLake の取り込みで認証エラーが発生する	abfss:// URI に ;impersonate を追加します

---

エージェントのワークフロー

作成前の調査

何かを実行する前に、明示的な意図があるか必ず確認します：

Step 0 → Is the request specific? Does it name a table, operation, and/or schema?
         → NO  → Ask: "What would you like to set up? Options: create tables,
                  configure policies, set up ingestion mappings, create materialized views."
                  STOP — do not proceed until user specifies.
         → YES → Continue to Step 1.
Step 1 → .show tables details                        // what exists?
Step 2 → .show table <TABLE> schema as json          // current columns
Step 3 → .show table <TABLE> policy retention        // current policies
Step 4 → Plan changes (create-merge, alter, etc.)
Step 5 → Execute changes
Step 6 → Verify: .show table <TABLE> schema as json  // confirm changes

スクリプト生成ワークフロー

Step 1 → Understand requirements from user
Step 2 → Generate KQL management commands
Step 3 → Save to .kql file
Step 4 → Deploy via az rest (one command at a time)
Step 5 → Verify deployed state matches intent

---

例

例 1：ポリシーとマッピングを設定してテーブルを作成する

# Create table
cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".create-merge table SensorData (Timestamp: datetime, DeviceId: string, Temperature: real, Humidity: real, Location: dynamic)"}
EOF

/tmp/kql_body.json を実行します — KQL コマンドの実行を参照してください

# Set retention
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":".alter table SensorData policy retention '{\"SoftDeletePeriod\":\"90.00:00:00\",\"Recoverability\":\"Enabled\"}'"}
EOF

/tmp/kql_body.json を実行します — KQL コマンドの実行を参照してください

# Set caching
cat > /tmp/kql_body.json << EOF
{"db":"${DB}","csl":".alter table SensorData policy caching hot = 7d"}
EOF

/tmp/kql_body.json を実行します — KQL コマンドの実行を参照してください

# Create JSON mapping
cat > /tmp/kql_body.json << 'EOF'
{"db":"MyDB","csl":".create table SensorData ingestion json mapping 'SensorJsonMapping' '[{\"column\":\"Timestamp\",\"path\":\"$.ts\",\"datatype\":\"datetime\"},{\"column\":\"DeviceId\",\"path\":\"$.deviceId\",\"datatype\":\"string\"},{\"column\":\"Temperature\",\"path\":\"$.temp\",\"datatype\":\"real\"},{\"column\":\"Humidity\",\"path\":\"$.humidity\",\"datatype\":\"real\"},{\"column\":\"Location\",\"path\":\"$.location\",\"datatype\":\"dynamic\"}]'"}
EOF

/tmp/kql_body.json を実行します — KQL コマンドの実行を参照してください

例 2：更新ポリシーを使用した ETL

// 1. Target table
.create-merge table ParsedLogs (Timestamp: datetime, Level: string, Message: string, Source: string)

// 2. Transform function
.create-or-alter function ParseRawLogs() {
    RawLogs
    | extend J = parse_json(RawMessage)
    | project
        Timestamp = todatetime(J.timestamp),
        Level = tostring(J.level),
        Message = tostring(J.message),
        Source = tostring(J.source)
}

// 3. Attach update policy
.alter table ParsedLogs policy update
@'[{"IsEnabled":true,"Source":"RawLogs","Query":"ParseRawLogs()","IsTransactional":true}]'

---

エージェント統合に関する注意事項

• このスキルでは作成操作（データベースオブジェクトの作成／変更とデータの取り込み）を扱います。
• 読み取り専用のクエリとデータの調査は、eventhouse-consumption-cli に委任してください。
• ワークロードをまたぐオーケストレーションは、FabricDataEngineer エージェントに委任してください。
• すべての管理コマンドには、昇格されたデータベースロール（Admin または Ingestor）が必要です。