fabriciq-ontology-consumption-cli

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

• GitHub Copilot CLI / VS Code：check-updates スキルを呼び出します（例：/fabric-skills:check-updates）。
• Claude Code / Cowork / Cursor / Windsurf / Codex：ローカルの package.json のバージョンを読み取り、git fetch origin main --quiet && git show origin/main:package.json（または GitHub API）を使ってリモートと比較します。リモートのほうが新しい場合は、変更履歴と更新手順を表示します。
• このセッション中にすでに確認済みの場合はスキップしてください。

重要な注意事項

1. Ontology は プレビュー版 です。項目タイプの値は Ontology です。ワイヤ形式と制限事項は変更される可能性があるため、本番環境で使用する前に最新のドキュメントを確認してください。
2. このスキルは 読み取り専用 です。createItem や updateDefinition は呼び出しません。スキーマを変更する場合は、fabriciq-ontology-authoring-cli に委任してください。
3. このスキルはソースデータを直接クエリしません。Ontology のグラウンディングコンテキストを列挙した後、実際のデータ読み取りを、バインド元の種類に合致するデータソース別の利用スキルに 委任 します（クエリのルーティングを参照）。
4. プロジェクション（Ontology エンティティに対するセマンティッククエリレイヤー）は、まだ GA ではありません。提供開始までは、バインディングの propertyBindings[] で宣言された列を使用して、すべてのデータクエリを ソース テーブル（LakehouseTable または KustoTable）に対して実行します。
5. ワークスペース名からワークスペースの詳細（ID を含む）を確認するには、すべてのワークスペースを一覧表示し、JMESPath でフィルタリングします。
6. ワークスペース ID と項目名から Ontology 項目 ID を確認するには、そのワークスペース内のタイプ Ontology の項目をすべて一覧表示し、JMESPath でフィルタリングします。

fabriciq-ontology-consumption-cli — CLI による Fabric Ontology の利用

目次

タスク	参照	備考
Fabric 内のワークスペースと項目の検索	COMMON-CLI.md § Fabric 内のワークスペースと項目の検索	必須 — 列挙する前にワークスペース/項目 ID を解決します
Fabric トポロジーと主要な概念	COMMON-CORE.md § Fabric トポロジーと主要な概念	ワークスペース → 項目の階層
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	コントロールプレーンには https://api.fabric.microsoft.com オーディエンスを使用します
コア コントロールプレーン REST API	COMMON-CORE.md § コア コントロールプレーン REST API	項目定義の取得
長時間実行操作 (LRO)	COMMON-CORE.md § 長時間実行操作 (LRO)	getDefinition は LRO を返します
レート制限とスロットリング	COMMON-CORE.md § レート制限とスロットリング
認証レシピ	COMMON-CLI.md § 認証レシピ	az login、トークンの取得
az rest 経由の Fabric コントロールプレーン API	COMMON-CLI.md § az rest 経由の Fabric コントロールプレーン API	常に --resource https://api.fabric.microsoft.com を渡します
長時間実行操作 (LRO) パターン	COMMON-CLI.md § 長時間実行操作 (LRO) パターン	Succeeded になるまで operations/{x-ms-operation-id} をポーリングします
注意点とトラブルシューティング (CLI 固有)	COMMON-CLI.md § 注意点とトラブルシューティング (CLI 固有)	トークン オーディエンス、シェル エスケープ
定義エンベロープ (parts、payloadType)	ITEM-DEFINITIONS-CORE.md § 定義エンベロープ	InlineBase64 parts パターン — オントロジーはこの形状を返します
オントロジー定義ツリー	ONTOLOGY-AUTHORING-CORE.md § 定義ツリー	デコードする parts の権威あるファイル/フォルダー レイアウト
EntityType と EntityTypeProperty スキーマ	ONTOLOGY-AUTHORING-CORE.md § EntityType ファイル	valueType カタログ、キー / 表示名のコントラクト
DataBinding スキーマ + ソースタイプ マッピング	ONTOLOGY-AUTHORING-CORE.md § DataBinding ファイル	LakehouseTable と KustoTable、propertyBindings[] の形状
RelationshipType + コンテキスト化	ONTOLOGY-AUTHORING-CORE.md § RelationshipType ファイル	ソース/ターゲット + リンクテーブルのコントラクト
接続の基本 (EH ソース クエリ)	EVENTHOUSE-CONSUMPTION-CORE.md § 接続の基本	KustoTable バインディングのクラスター URI + DB 検出
パフォーマンスのベスト プラクティス (EH ソース クエリ)	EVENTHOUSE-CONSUMPTION-CORE.md § パフォーマンスのベスト プラクティス	時間フィルター、has と contains
Spark 消費パターン (Lakehouse ソース)	SPARK-CONSUMPTION-CORE.md	LakehouseTable バインディングでは、読み取りを委任します
SQL 消費パターン (SQL エンドポイント / DW)	SQLDW-CONSUMPTION-CORE.md	LakehouseTable の SQL エンドポイント読み取りとウェアハウス読み取りの場合
オントロジーの概念	SKILL.md § オントロジー消費の概念	エンティティ / リレーションシップ / バインディング / グラウンディング コンテキスト
ツール スタック	SKILL.md § ツール スタック
接続	SKILL.md § 接続	ワークスペース、オントロジー ID を検出、項目定義の取得
消費スコープ	SKILL.md § 消費スコープ	このスキルが行うこと / 行わないこと
グラウンディング コンテキストの抽出 (詳細リファレンス)	grounding-extraction.md	parts をデコード → エージェント用のグラウンディング JSON
クエリ ルーティング (詳細リファレンス)	routing.md	バインディングの種類 → データソース別スキル + クエリ形状
実例	examples.md	エンドツーエンドの bash レシピ (列挙 → ルーティング → クエリ)
グラフ ウォーク (アンカーからの N ホップ近傍)	graph-walks.md	アンカー エンティティ + ホップ バジェット → スクリプトなしでインライン読み取りを構成
迅速な応答の規律	SKILL.md § 迅速な応答の規律	インライン優先、ステートフルまたは再実行可能な場合のみスクリプト
必須 / 推奨 / 回避 / トラブルシューティング	SKILL.md § 必須 / 推奨 / 回避 / トラブルシューティング	LLM の決定ルール
エージェント ワークフロー	SKILL.md § エージェント ワークフロー	グラウンディングしてからクエリするループ、スキーマ認識クエリ生成
エージェント統合の注意事項	SKILL.md § エージェント統合の注意事項	このスキルがオーサリング / データソース別スキルとどのように組み合わされるか

---

オントロジーの利用に関する概念

Fabric オントロジー項目は、項目定義内に JSON ファイルのツリーとしてスキーマを保持します（作成時と同じ構造です）。Get Item Definition は各パーツを Base64 エンコードされたペイロードとして返します。利用フローは常に 取得 → デコード → 解析 → グラウンディング → 委譲です。

概念	定義のパーツ	エージェントに伝える内容
エンティティ型	EntityTypes/{entityTypeId}/definition.json	論理型名、キーのプロパティ（entityIdParts）、表示名のプロパティ、静的な properties[]、timeseriesProperties[]、値型カタログ
データバインディング	EntityTypes/{entityTypeId}/DataBindings/{guid}.json	このエンティティ型の基となる物理テーブル、ソースの種類（LakehouseTable / KustoTable）、dataBindingType（NonTimeSeries / TimeSeries）、列とプロパティのマッピング、および時系列の場合はタイムスタンプ列
リレーションシップ型	RelationshipTypes/{relTypeId}/definition.json	2 つのエンティティ型間のリンク（ソース／ターゲット）、名前、カーディナリティのヒント
コンテキスト化	RelationshipTypes/{relTypeId}/Contextualizations/{guid}.json	リレーションシップを実現するための（ソースキー、ターゲットキー）のペアを保持する Lakehouse リンクテーブル

グラウンディングコンテキストとは、ツリーをフラット化した、エージェントが利用しやすい形式の投影です。LLM が クエリするエンティティ型、キーを保持する列、クエリするテーブル、呼び出す利用スキルを判断するために読み取れる JSON サマリーです。完全な形式と抽出手順については、grounding-extraction.md を参照してください。

プロパティ valueType で使用できる値（厳密一致）は、String、Boolean、DateTime、Object、BigInt、Double です。整数は BigInt（Int64 ではありません）、GUID は String としてモデル化されます。ソース列から valueType への完全なマッピングについては、ONTOLOGY-AUTHORING-CORE.md § EntityTypeProperty を参照してください。

---

ツールスタック

オントロジーの利用では、ほかの CLI スキルと同じ Fabric コントロールプレーンのツールスタックを使用します。正規の一覧（インストールコマンド、前提条件の確認、Base64 ヘルパー、JSON ツール）については、COMMON-CLI.md § Tool Selection Rationale を参照してください。az login とトークンの取得については、COMMON-CLI.md § Authentication Recipes を参照してください。

データソースごとの読み取りは委譲されるため、このスキルで列挙を行うだけであれば、Kusto、Spark、SQL の CLI ツールをインストールする必要はありません。これらのツールが必要になるのは、同じセッションで後続の利用スキルも呼び出す場合のみです。

---

接続

オントロジーの利用では Fabric コントロールプレーンを対象とします。必要なのは ワークスペース ID と オントロジー項目 ID です。それ以外（エンティティ型、バインディング、ソーステーブル、クラスター URI）は、定義をデコードして取得します。

• サインインして Fabric コントロールプレーンのトークンを取得する → COMMON-CLI.md § Authentication Recipes（常に --resource https://api.fabric.microsoft.com を指定します）。
• displayName でワークスペース ID を解決し、GET /v1/workspaces/{WS_ID}/items?type=Ontology を displayName でフィルターしてオントロジー項目 ID を取得する → COMMON-CLI.md § Finding Workspaces and Items in Fabric（ページネーションと JMESPath によるフィルタリングについて説明しています）。
• 汎用的な az rest 呼び出しテンプレート → COMMON-CLI.md § Fabric Control-Plane API via az rest。

定義の取得（Ontology プレビューの LRO に関する注意点）

Get Item Definition は Long-Running-Operation に対応しています。テナントや SKU によって、POST が定義のエンベロープをインラインで返す（200 OK）場合と、x-ms-operation-id ヘッダーとともに 202 Accepted を返す場合があります。202 の場合は、https://api.fabric.microsoft.com/v1/operations/{operationId} を Succeeded になるまでポーリングし、その後 GET …/operations/{operationId}/result を実行して parts[] 配列を取得します。一般的な LRO の手順（x-ms-operation-id の取得、ポーリング、結果の取得）は、COMMON-CLI.md § Long-Running Operations (LRO) Pattern に記載されています。

Ontology プレビューに関する注意点 — Location ヘッダーよりも operations/{id} エンドポイントのポーリングを優先してください。 Fabric の公開 LRO 契約ではどちらもサポートされていますが、この Ontology LRO では、Location ヘッダーが *.analysis.windows.net ホストにリダイレクトされることが確認されています。Fabric を対象とするトークンでポーリングすると、不安定になることがあります（401/403 が断続的に発生）。代わりに、Fabric ホスト上の https://api.fabric.microsoft.com/v1/operations/{operationId} をポーリングしてください。Location に従う必要がある場合は、その URL で必要となるオーディエンスを使用してください。ポーリングで 2xx 以外が返された場合は、必ず操作の .error を確認して停止してください。決して POST を無条件に再試行しないでください。

このスキルの取得・デコードの全フロー（LRO の取得、パーツのデコード、ツリーの再構築、Bash + PowerShell + Python のヘルパー）は、grounding-extraction.md § Fetch and Decode にあります。関連する fabriciq-ontology-authoring-cli では、LRO Header Capture section に同じリダイレクト先ホストの回避策が記載されています。一方を変更する場合は、両方の内容を一致させてください。

ソースデータ接続（委任）

データクエリ自体（KQL / Spark SQL / T-SQL）の実行には、関連する消費スキルが管理する接続パターンを使用します。

• Eventhouse（KustoTable バインディング）→ EVENTHOUSE-CONSUMPTION-CORE.md § Connection Fundamentals + eventhouse-consumption-cli
• Lakehouse（LakehouseTable バインディング）→ sqldw-consumption-cli（既定、SQL analytics endpoint）または spark-consumption-cli（ユーザーが明示的に PySpark / DataFrame を使った作業を希望する場合のみ）
• Warehouse バインディング → ❓ 現在共有されている ontology スキーマでは文書化されていません（LakehouseTable と KustoTable のみ）。見つかった場合は、sqldw-consumption-cli を暗黙に想定せず、ユーザーに提示してください。

委任先が必要とする clusterUri、databaseName、workspaceId、itemId はすべて、デコード済みのバインディングペイロードにすでに含まれています。アイテム API を使って再取得しないでください。

---

利用範囲

操作	このスキル	委任先
エンティティ型、プロパティ、キー、表示名の列挙	✅	—
バインディング（ソースの種類、対象アイテム、プロパティマップ、タイムスタンプ）の列挙	✅	—
リレーションシップとコンテキスト化の列挙	✅	—
LLM 向けグラウンディング JSON の生成	✅	—
差分確認／レビューのための定義ツリー全体のデコード	✅	—
Eventhouse のオントロジーに基づくデータのクエリ	委任	eventhouse-consumption-cli
Lakehouse の SQL エンドポイント経由でのオントロジーに基づくデータのクエリ（デフォルト）	委任	sqldw-consumption-cli
Lakehouse の Spark 経由でのオントロジーに基づくデータのクエリ（Spark を明示的に指定された場合のみ）	委任	spark-consumption-cli
Warehouse のオントロジーに基づくデータのクエリ	提示（❓ バインディングの形式は共通スキーマに含まれていません）	—
エンティティ型／リレーションシップの作成・変更・再バインド	❌	fabriciq-ontology-authoring-cli
オントロジーのインデックス状態の更新	❌	プレビュー CLI の対象外

プロジェクションが提供されるまでは、すべてのデータ読み取りはソースクエリです。propertyBindings[] に記載された列を使用して、物理的な LakehouseTable または KustoTable に対して実行されます。プロジェクションを必要とするセマンティック機能（推論による結合、派生メジャー）は、このスキルでは利用できません。その旨をユーザーに伝え、ソースレベルのフィルタリングで進めてください。

---

グラウンディングコンテキスト

詳しい手順と完全な JSON の形式については、grounding-extraction.md を参照してください。クイックインデックス：

トピック	リファレンス
取得＋LRO＋パーツのデコード	grounding-extraction.md § Fetch and Decode
メモリ内で定義ツリーを再構築	grounding-extraction.md § Tree Reconstruction
グラウンディング JSON の要約を生成（エンティティ＋バインディング＋リレーションシップ）	grounding-extraction.md § Grounding Summary Schema
2 つのオントロジーバージョンの差分を確認	grounding-extraction.md § Diff Two Ontologies

グラウンディング JSON の仕様 — 正式な形式は grounding-extraction.md § Grounding Summary Schema に記載されています。ルーティングの判断では、各バインディングの以下のフィールドを参照します。

• source.kind（LakehouseTable | KustoTable）— 委任先の種類を決定します。
• source.workspaceId + source.itemId — オントロジーではなく、バインディングから読み取ります（ワークスペースをまたぐバインディングも有効です）。
• source.sourceSchema + source.sourceTableName — スキーマがあるのは Lakehouse のみです。
• source.clusterUri + source.databaseName — Kusto のみです。
• dataBindingType（NonTimeSeries | TimeSeries）+ timestampColumnName — TS のルーティングに必須です。
• propertyBindings[].sourceColumnName — オントロジープロパティから物理列へのマッピングです。クエリを組み立てる前に適用します。
• relationshipTypes[].contextualizations[].sourceKeyRefBindings[] / targetKeyRefBindings[] — 配列です。複合キーも有効です。すべてのエントリを使用して結合してください。

この JSON の必要な部分だけを絞り込み、下流のスキルに渡してください（生の base64 definition.parts[] は渡さないでください）。

---

クエリのルーティング

詳細なレシピとスキルごとの呼び出しテンプレートについては、routing.md を参照してください。簡単な判断表：

バインド元の種類	dataBindingType	委譲先（既定／代替）	クエリの形式
LakehouseTable	NonTimeSeries	sqldw-consumption-cli（既定、SQL エンドポイント）— ユーザーが明示的に PySpark／DataFrames を希望する場合に限り spark-consumption-cli	SELECT <propertyColumns> FROM <schema>.<sourceTableName> WHERE <keyColumn> = <value>
LakehouseTable	TimeSeries	sqldw-consumption-cli（既定）— Spark 専用機能には spark-consumption-cli	SELECT ..., <timestampColumn> FROM <schema>.<sourceTableName> WHERE <keyColumn> = <v> AND <timestampColumn> >= DATEADD(hour,-1,SYSUTCDATETIME())
KustoTable	TimeSeries	eventhouse-consumption-cli	<sourceTableName> | where <keyColumn> == "<v>" | where <timestampColumn> > ago(1h) | project <propertyColumns>
KustoTable	NonTimeSeries	無効 — プレビューでは禁止されています	拒否し、オントロジーのバインドが誤っていることをユーザーに伝えます
あらゆるリレーションシップのコンテキスト化	—	sqldw-consumption-cli（既定。リンクテーブルは Lakehouse にあるため、T-SQL での結合がより簡潔です）— spark-consumption-cli は代替	SELECT <targetKeyColumns> FROM <linkTable> WHERE <sourceKeyColumns> = <source-values> を実行し、続けてターゲット側のバインドを結合する呼び出しを行います

引き継ぎ時の呼び出し契約 — このスキルはソースメタデータを解決し、ターゲットの方言でクエリを組み立ててから、その両方を委譲先に渡します。実際の接続と実行は、委譲先（兄弟スキル）が担当します。

• Eventhouse の委譲先 → 解決済みの接続（clusterUri、databaseName）＋ sourceTableName を対象とし、timestampColumnName のフィルターとキー述語を含む 組み立て済みの KQL テキスト。
• SQL エンドポイントの委譲先（Lakehouse の既定）→ 解決済みの接続（workspaceId、itemId、sourceSchema）＋ 組み立て済みの T-SQL テキスト。
• Spark の委譲先（Lakehouse の代替）→ 同じ解決済みの接続＋ 組み立て済みの Spark SQL テキスト — Spark ネイティブの時間関数（current_timestamp() - INTERVAL 1 HOUR）を使用してください。Spark に T-SQL の DATEADD／SYSUTCDATETIME を出力しないでください。
• 必ず、組み立てたクエリテキスト内でオントロジーのプロパティ名を propertyBindings[].sourceColumnName に変換してください。委譲先が参照するのは物理列のみで、オントロジー識別子は解決しません。
• 必ず、複合キーの sourceKeyRefBindings[]／targetKeyRefBindings[] を渡してください。最初の要素だけでなく、すべての要素を使って結合します。

プロジェクションはまだ GA ではないため（重要な注意事項 #4 を参照）、委譲先のクエリを組み立てる前に、ユーザーが指定したオントロジーのプロパティ名を propertyBindings[] を介して物理ソース列名に必ず変換してください。オントロジーのプロパティ名を兄弟スキルに渡さないでください。兄弟スキルはそれを解決しません。

---

必須／推奨／回避／トラブルシューティング

必須

• ここにルーティングする前に、オントロジーのコンテキストを明示的に要求してください — プロンプトには「オントロジー」という語を含めるか、ID／名前でオントロジー項目を参照する必要があります。オントロジーのコンテキストがない一般的な「Fabric IQ」やレポート／データセットに関するプロンプトは、オントロジーのタスクではありません。一致するデータスキル（例：Power BI レポートの場合は powerbi-consumption-cli）に委ねてください。これにより、共通ブランドである「Fabric IQ」を理由に、このスキルが過剰に起動されるのを防げます。
• 曖昧なプロンプトをルーティングする前に確認してください — ユーザーが「航空機の測定値を表示して」と依頼し、複数のエンティティタイプが航空機に関連するテーブルにバインドされている場合は、どのエンティティタイプ／バインディングを使用するか尋ねてください。確認せずに推測すると、誤ったデータが返されます。
• 定義を取得する前に WS_ID と ONT_ID を解決してください — GUID のハードコードは、主な失敗要因の一つです。
• getDefinition では LRO パターンに従ってください — x-ms-operation-id を伴う 202 は正常な応答ですが、成功として扱わないでください。Succeeded になるまで operations/{operationId} をポーリングし、その後 …/operations/{operationId}/result に GET してください。生の Location のポーリングより operations/{operationId} を優先してください（Fabric オーディエンスのトークンでは、analysis.windows.net へのリダイレクトが不安定な場合があります）。Location に従う場合は、その URL が要求するオーディエンスを使用してください。ポーリングが Failed／非 2xx の場合は .error を確認して停止し、無条件に再試行しないでください。
• 回答する前に、関連するすべての部分をデコードしてください — オントロジーの部分的なキャッシュ表示から回答しないでください。前回の読み取り以降に、呼び出し元がエンティティタイプを追加／変更している可能性があります。
• KQL／Spark SQL／T-SQL を生成する前に、propertyBindings[] を使ってオントロジーのプロパティ名をソース列名に変換してください — 兄弟のコンシュームスキルから見えるのは物理列のみです。
• バインディングの種類を尊重してください — TimeSeries には timestampColumnName に対する時間フィルターが必要です。これを省略すると全件スキャンになり、後続のスキルで拒否されることもよくあります。
• 各バインディングの workspaceId と itemId を保持してください — オントロジーのバインディングは、オントロジー自体とは異なるワークスペースのソース項目を参照する場合があります。同じ場所にあると仮定しないでください。
• メタデータ呼び出しを行う前に、メモリ内のグラウンディングを参照してください — セッション用にグラウンディング JSON をデコードした後は、その後のすべての探索／クエリで、ソース列名、リンクテーブル名、項目 GUID、clusterUri、databaseName を、新たな list items／get eventhouse の往復ではなく、グラウンディングから読み取ってください。すでに取得済みのメタデータを再取得することが、呼び出し回数が膨らむ最大の原因です。
• ソース URL では、わかりやすい名前ではなく GUID を使用してください — 多くのテナントでは FriendlyNameSupportDisabled が有効になっており、OneLake DFS／Fabric REST URL 内の MyLakehouse.Lakehouse のような名前は、何の通知もなく拒否されます。必ずグラウンディングから GUID を取得し、URL に設定してください。

推奨

• |、"、または改行を含む後続の KQL／SQL ペイロードには、--body @file.json を指定した az rest を使用してください。インラインの --body はシェルのエスケープ処理で動作しなくなります。EVENTHOUSE-CONSUMPTION-CORE.md を参照してください。
• 別のエージェントにコンテキストを渡す場合は、生の definition.json ダンプよりグラウンディングの要約 JSON を優先してください（上記のスキーマを参照）。
• エンティティのデータを初めて読み取るときは take 100／TOP 100 を使い、その後絞り込んでください。
• 読み取り専用のコンシューム作業では、Python スクリプトよりインラインの az rest／curl を優先してください — グラフ探索、単一エンティティの検索、臨時のファンアウト読み取りは、シェル内で合計およそ 15 回以下の REST 呼び出しで構成できるはずです。スクリプトを使うのは、作業が状態を持つ場合（エンベロープの組み立て、ID マップ、ユーザーが再実行を希望する LRO など）に限ってください。簡潔な応答の原則 と graph-walks.md を参照してください。
• デコードした定義は、1 セッションの間キャッシュしてください — オントロジー定義はソースデータより桁違いに小さく、タスクの途中で変更されることもほとんどありません。ユーザーがオーサリング作業に言及した場合は、再取得してください。
• 物理テーブル全体ではなく、バインドされたソース列のみを project／SELECT してください — オントロジーのバインディングは、列が明示的にホワイトリスト化されていることを意味します。

避けること

• オントロジーのプロパティ名を使ってソーステーブルをクエリすること — それらは物理スキーマに存在しません。必ず propertyBindings[] を経由してください。
• TimeSeries／KustoTable の読み取りで where <timestampColumn> > ago(...) を省略すること — ストリーミングテーブルのフルスキャンは、クエリ失敗の最大の原因です。
• 1 回の委譲呼び出しでデータソースの種類をまたいで結合すること — リレーションシップの両側が異なるソースの種類に存在する場合、委譲側では結合を表現できません。両側を別々に取得し、エージェント内で結合してください。
• このスキルからオントロジーを変更すること — スキーマの変更はすべて fabriciq-ontology-authoring-cli に引き渡してください。
• 未加工の base64 パーツを下流のスキル／モデルに渡すこと — 必ず最初にデコードし、グラウンディング用の JSON に整形してください。
• 不明なパーツパスを黙って無視すること — 新しいプレビューリリースでパーツの種類が追加されている可能性があります。ログに記録して処理を続けても構いませんが、新しいパーツ名をユーザーに伝えてください。

トラブルシューティング

症状	対処方法
az rest が 401 Unauthorized を返す	az login を実行してください。コントロールプレーンの呼び出しで --resource "https://api.fabric.microsoft.com" を指定していることと、委譲時に下流で必要な対象ユーザー（EH の場合は https://kusto.kusto.windows.net）を指定していることを確認してください。
getDefinition が本文なしで 202 を返す	想定どおりです。LRO パターンに従い、x-ms-operation-id を取得して operations/{operationId} を Succeeded になるまでポーリングし、その後 …/operations/{operationId}/result に GET を送信してください。operations/{operationId} を推奨します。Location をポーリングする場合は、その URL で必要な対象ユーザーを使用してください（analysis.windows.net のリダイレクトは、Fabric 対象ユーザーのトークンでは失敗することがあります）。
getDefinition で 403 Forbidden が発生する	オントロジーには、ワークスペースへのアクセスに加えて、Contributor または オントロジー項目に対する Reader が必要です。ロールの割り当てを依頼してください。
definition.parts[] が空	項目は作成されましたが、エンティティ型が追加されていません。ユーザーに伝え、まず fabriciq-ontology-authoring-cli を実行するよう提案してください。
下流の KQL が 0 行を返すが、ソーステーブルにはデータがある	バインディングの sourceTableName の大文字・小文字と、バインディングの clusterUri／databaseName が稼働中のクラスターと一致していることを確認してください。大文字・小文字の不一致は、結果が空でもエラーを出さない原因になります。
SELECT <propertyName> が「invalid column」で失敗する	ソース列名ではなく、オントロジーのプロパティ名を渡しています。propertyBindings[].sourceColumnName を使って対応付けてください。
リレーションシップの走査で、予想より大幅に少ない行が返る	Contextualization の sourceTableName（Lakehouse のリンクテーブル）が空、または古い可能性があります。オントロジーを疑う前に、sqldw-consumption-cli で確認してください。
バインディングと稼働中の Eventhouse で itemId／clusterUri が一致しない	バックエンドの Eventhouse が再作成されています。オントロジーの作成側での更新が必要です。fabriciq-ontology-authoring-cli に引き渡してください。
base64 のデコード結果がバイナリの文字化けになる	パーツのペイロードが InlineBase64 ではありません。payloadType を確認してください。VsixPackage または不明な種類の場合はスキップし、警告してください。

---

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

機敏な応答の規律

消費は読み取り専用であり、高速に感じられるべきです。既定のモードはシェルでのインライン構成であり、Python ラッパーではありません。スクリプトに手を伸ばす前に、このチェックリストを使用してください：

状況	インライン (az rest / curl)	Python / シェルスクリプト
単一エンティティの参照	✅	❌
時系列ウィンドウの読み取り	✅	❌
グラフ走査、ホップ ≤ 2（graph-walks.md を参照）	✅	❌
ソース間の関係トラバーサル（LH キー → KQL ファンアウト）	✅	❌
グラウンディング JSON の抽出（ワンショット）	✅	❌
ユーザーが再実行を望む LRO getDefinition ポーリングループ	➖	✅
オントロジーのオーサリング / 変更（35 パートのエンベロープ、ID 相互参照）	❌	✅（fabriciq-ontology-authoring-cli へのハンドオフ）
長時間実行されるシーディング / リトライとチェックポイントを伴うバッチロード	❌	✅

インラインファーストの原則

1. 構成せよ、スクリプト化するな。 各 REST 呼び出しは独立して意味を持ちます。.py でラップするのではなく、&& / | / jq で連結してください。
2. ファンアウトを並列化せよ。 独立した読み取り（リンクテーブルクエリ、エンティティタイプごとの IN リスト読み取り）は、逐次的な for ループではなく、& と wait で実行してください。
3. グループごとに 1 回のラウンドトリップ。 N×WHERE id = '...' ではなく WHERE id IN (...) を使用してください。
4. グラウンディング JSON をセッション中キャッシュせよ — これはクエリ間で変化せず、再取得するとすべての走査のレイテンシが倍増します。
5. 早期にストリームせよ。 アンカー行と最初の隣接グループは、返されたらすぐに表示してください。ウォーク全体の完了を待って表示をブロックしないでください。
6. 求められない限りスクリプト化するな。 ユーザーが「後で使えるように保存して」または「毎晩再実行して」と言った場合にのみ、スクリプトとしてパッケージ化してください。それ以外の場合は、作業をチャットで再生可能なシェルにとどめてください。

タスクが約 20 回を超える REST 呼び出し、2 ホップ超、または呼び出し間の永続的な状態を必要とするように見え始めた場合は、スクリプト化する前にユーザーにこれを提示してください — 通常、それは質問を自動化するのではなく絞り込むべきであることを意味します。

「グラウンディングしてからクエリ」シーケンス

ユーザーがオントロジーのレンズを通じてデータをクエリするよう求めた場合：

Step 1 → Resolve WS_ID + ONT_ID (list workspaces, list items type=Ontology)
Step 2 → getDefinition (LRO) → decode all parts → reconstruct tree
Step 3 → Build grounding JSON (entities, properties, bindings, relationships)
Step 4 → Disambiguate with the user if multiple entity types / bindings could satisfy the intent
Step 5 → For the chosen entity type + binding:
           a. Remap ontology property names → source column names
           b. Compose the source query (KQL / Spark SQL / T-SQL)
           c. Hand off to the matching sibling consumption skill with minimal fields
Step 6 → Post-process results back into ontology-property naming for the user (optional but helpful)

スキーマを意識したクエリ生成

グラウンディングパスの後、オントロジー名ではなく、propertyBindings[] に記録された物理列を使用してクエリを生成してください：

Entity type "Aircraft" with binding:
  source kind = KustoTable
  sourceTableName = "AircraftReadings"
  timestampColumnName = "PreciseTimestamp"
  propertyBindings: { AltitudeFt → SourceColumn "Temp_C", TailNumber → SourceColumn "AssetId" }

User intent: "show altitude excursions on aircraft N42ZA in the last hour"

Generated KQL (delegated to eventhouse-consumption-cli):
  AircraftReadings
  | where AssetId == "N42ZA"
  | where PreciseTimestamp > ago(1h)
  | project PreciseTimestamp, Temp_C
  | where Temp_C > 80

関係トラバーサル

Relationship "operates" (Airline → Aircraft)
Contextualization: LakehouseTable "HubAircraftAssignment" with (AirlineId, TailNumber) columns
  AND two entity-type bindings (Airline on LakehouseTable "Airlines", Aircraft on KustoTable "AircraftReadings")

User intent: "which aircraft does Airline 'ZA' operate and what's their latest reading?"

Step 1: sqldw-consumption-cli → SELECT TailNumber FROM HubAircraftAssignment WHERE AirlineId = 'ZA'
Step 2: eventhouse-consumption-cli → AircraftReadings | where AssetId in (<TankIds>) | summarize arg_max(PreciseTimestamp, *) by AssetId
Step 3: Merge results in the agent; present with ontology-level column names.

完全なエンドツーエンドの bash レシピ（列挙 → グラウンディング → ルーティング → クエリ）は examples.md にあります。「X に関連するすべてを見せて」というプロンプトの場合は、graph-walks.md の N ホップウォークに直接進んでください。

グラフ走査（アンカーからの N ホップ）

ユーザーがあるインスタンス（「Panel7」、「aircraft N42ZA」、「customer 1234」）を提示し、単一の列ではなくその近傍を求めた場合は、質問ごとにレシピを考案するのではなく、専用のグラフ走査パターンを使用してください。

Anchor → relationships touching anchor (from grounding JSON, in-memory)
       → linking-table reads (parallel, one per relationship)
       → IN-list reads of neighbor entities (one per EntityType)
       → optional KustoTable telemetry sweep (one per EntityType with TS binding)

hop=1 の場合、これは通常 10 回以下のラウンドトリップであり、インラインのままです。完全なアルゴリズム、ファンアウトテンプレート、ホップ予算、および Panel7 の実例は graph-walks.md にあります。

---

例

エンドツーエンドの実例（オントロジーの列挙 → グラウンディング JSON の構築 → ソーステーブルクエリを正しい兄弟消費スキルへのルーティング → Lakehouse + Eventhouse をまたぐ関係のトラバーサル）は examples.md にあります。アンカーインスタンスからの N ホップ近傍走査（Panel7 形式）は graph-walks.md にあります。完全なフェッチとデコードのスクリプトは grounding-extraction.md にあります。バインディングタイプごとの呼び出しテンプレートは routing.md にあります。

---

エージェント連携に関するメモ

• このスキルはオントロジー項目に対して読み取り専用です。すべての作成操作（作成、変更、再バインド、名前変更）は fabriciq-ontology-authoring-cli が担当します。そちらに委任してください。
• このスキルはデータクエリを自ら実行しません。グラウンディングコンテキストとルーティングの判断を生成します。実際のソースクエリは、委任先のデータソースごとの利用スキル内で実行されます。
• 対応する後続スキル（プレビュー）：eventhouse-consumption-cli、spark-consumption-cli、sqldw-consumption-cli。単独で利用できるグラフ消費スキルはまだ存在しません。ユーザーがリレーションシップを対象とするグラフ形式のクエリを求めた場合は、この制限を伝え、Lakehouse／SQL でエッジごとに結合する方法に切り替えてください。
• オーケストレーターエージェントは、このスキルにワークスペース名／IDとオントロジーの表示名／IDを渡してください。このスキルは、定義を再取得せずに後続の委任呼び出しで再利用できるグラウンディング JSON を返します。
• セッション中に作成操作が行われた可能性がある場合（たとえば、ユーザーが fabriciq-ontology-authoring-cli を実行してからクエリに戻ってきた場合）は、グラウンディング処理を再実行してください。キャッシュされた定義は古くなっています。
• ユーザーの環境でFabric KQL MCP サーバーが構成されている場合、Eventhouse への委任では az rest の代わりに使用できます。リポジトリの既定の mcp-setup/mcp-config-template.json には fabric-kql サーバーが登録されていないため、その名前が存在すると決めつけないでください。いずれの場合も、オントロジーのコントロールプレーン呼び出しには対応しないため、取得／グラウンディングの手順では引き続き az rest を使用します。