sqldw-consumption-cli

テレメトリ — 必須。 すべての api.fabric.microsoft.com 呼び出しには、 x-ms-fabric-skill: sqldw-consumption-cli（az rest の場合：--headers "x-ms-fabric-skill=sqldw-consumption-cli"）を付与する必要があります。 すべての LRO ポーリング、fabric_lro、再試行にも適用されます。スニペットでは省略されていますが、必ず追加してください。

更新チェック — セッションごとに 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 フィルタリングを使用してください。

SQL Endpoint Consumption — CLI スキル

⚠️ SQL 実行の優先指定： SQL データプレーンの実行では、このスキルが COMMON-CLI の SQL/TDS に関するガイダンスに優先します。Legacy CLI Fallback を明示的に使用する場合を除き、MCP fabric-sqlendpoint-execute_query を使用してください（ツールスタックを参照）。

目次

タスク	参照先	備考
Fabric のワークスペースとアイテムの検索	COMMON-CLI.md § Fabric のワークスペースとアイテムの検索	必須 — まずリンクを読む［名前からワークスペース ID、または名前、アイテムの種類、ワークスペース ID からアイテム ID を検索するために必要です］
Fabric のトポロジと主要な概念	COMMON-CORE.md § Fabric のトポロジと主要な概念
環境 URL	COMMON-CORE.md § 環境 URL
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	audience が誤っていると 401 が発生します。認証に関する問題があれば、まずお読みください
コアコントロールプレーン REST API	COMMON-CORE.md § コアコントロールプレーン REST API	ページネーション、LRO のポーリング、レート制限のパターンを含みます
OneLake データアクセス	COMMON-CORE.md § OneLake データアクセス	Fabric トークンではなく、storage.azure.com トークンが必要です
ジョブの実行	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 を指定してください。ページネーションと LRO ヘルパーを含みます
curl による OneLake データアクセス	COMMON-CLI.md § curl による OneLake データアクセス	az rest ではなく curl を使用してください（トークンの audience が異なります）
SQL／TDS データプレーンアクセス	SKILL.md § ツールスタック	fabric-sqlendpoint-execute_query MCP ツール — sqlcmd を置き換えます
ジョブの実行（CLI）	COMMON-CLI.md § ジョブの実行
OneLake ショートカット	COMMON-CLI.md § OneLake ショートカット
キャパシティ管理（CLI）	COMMON-CLI.md § キャパシティ管理
複合レシピ	COMMON-CLI.md § 複合レシピ
注意点とトラブルシューティング（CLI 固有）	COMMON-CLI.md § 注意点とトラブルシューティング（CLI 固有）	az rest の audience、シェルのエスケープ、トークンの有効期限
クイックリファレンス	COMMON-CLI.md § クイックリファレンス	az rest のテンプレートとトークン audience／ツールの対応表
アイテムの種類別機能マトリックス	SQLDW-CONSUMPTION-CORE.md § アイテムの種類別機能マトリックス	最初にお読みください — 読み取り専用（SQLEP）と読み書き可能（DW）の違いを示します
接続の基本	SQLDW-CONSUMPTION-CORE.md § 接続の基本	TDS、ポート 1433、Entra のみ、MARS なし
サポートされる T-SQL の範囲（データ消費に重点）	SQLDW-CONSUMPTION-CORE.md § サポートされる T-SQL の範囲	T-SQL を記述する前にお読みください — データ型を含みます（nvarchar／datetime／money は使用できません）
作成できる読み取り側のオブジェクト	SQLDW-CONSUMPTION-CORE.md § 作成できる読み取り側のオブジェクト	ビュー、TVF、スカラー UDF、プロシージャ
一時テーブル	SQLDW-CONSUMPTION-CORE.md § 一時テーブル	INSERT INTO SELECT をサポートするには、DISTRIBUTION = ROUND_ROBIN を使用してください
データベース間クエリ	SQLDW-CONSUMPTION-CORE.md § データベース間クエリ	3 部構成の名前指定、同一ワークスペース
データ消費のセキュリティ	SQLDW-CONSUMPTION-CORE.md § データ消費のセキュリティ	GRANT／DENY、RLS、CLS、DDM
監視と診断	SQLDW-CONSUMPTION-CORE.md § 監視と診断	クエリラベルを含みます。DMV（ライブ）と queryinsights.*（過去 30 日間の履歴）
パフォーマンス：ベストプラクティスとトラブルシューティング	SQLDW-CONSUMPTION-CORE.md § パフォーマンス：ベストプラクティスとトラブルシューティング	統計情報、キャッシュ、クラスタリング、クエリのヒント
REST API：SQL エンドポイントのメタデータを更新	SQLDW-CONSUMPTION-CORE.md § REST API：SQL エンドポイントのメタデータを更新	ETL 後に SQLEP のデータが古くなった場合、メタデータの同期を強制します
システムカタログクエリ（メタデータの調査）	SQLDW-CONSUMPTION-CORE.md § システムカタログクエリ	sys.tables、sys.columns、sys.views、sys.stats
一般的なデータ消費パターン（エンドツーエンドの例）	SQLDW-CONSUMPTION-CORE.md § 一般的なデータ消費パターン	レポート用ビュー、データベース間分析、一時テーブルへのステージング
注意点とトラブルシューティングのリファレンス	SQLDW-CONSUMPTION-CORE.md § 注意点とトラブルシューティングのリファレンス	原因と解決策を記載した 18 件の番号付き項目
クイックリファレンス：シナリオ別のデータ消費機能	SQLDW-CONSUMPTION-CORE.md § クイックリファレンス：データ消費機能	シナリオからアプローチを検索
スキーマとオブジェクトの検出	discovery-queries.md § スキーマとオブジェクトの検出	テーブル、列、ビュー、関数、プロシージャ、データベース間
セキュリティの検出	discovery-queries.md § セキュリティの検出
統計情報とパフォーマンスのメタデータ	discovery-queries.md § 統計情報とパフォーマンスのメタデータ
データエクスポートのワークフロー	script-templates.md § データエクスポートのワークフロー	クエリから CSV への出力と、日付範囲を指定したパラメーター化エクスポート
スキーマ検出のワークフロー	script-templates.md § スキーマ検出のワークフロー	MCP による完全なスキーマレポート
パフォーマンス調査のワークフロー	script-templates.md § パフォーマンス調査のワークフロー	アクティブなクエリ、低速クエリの分析
ツールスタック	SKILL.md § ツールスタック	fabric-sqlendpoint-execute_query MCP ツールと az CLI
接続	SKILL.md § 接続
エージェントによる探索（「データとチャットする」）	SKILL.md § エージェントによる探索	データ探索はここから始めてください
スクリプトの生成	consumption-cli-quickref.md § スクリプトの生成	単独で実行できる bash／PowerShell スクリプトを出力するタイミング、az rest による検出とレガシー CLI へのフォールバック
監視とパフォーマンス	consumption-cli-quickref.md § 監視とパフォーマンス	アクティブなクエリの DMV（読み取り専用。セッションの終了は対象外です）
注意点、ルール、トラブルシューティング	SKILL.md § 注意点、ルール、トラブルシューティング	必須／回避／推奨のチェックリスト
エージェント統合に関するメモ	consumption-cli-quickref.md § エージェント統合に関するメモ	エージェントごとの CLI のヒント

---

ツールスタック

ツール	役割	インストール
fabric-sqlendpoint-execute_query MCP ツール	主要：Fabric SQL Endpoint に対して T-SQL クエリを実行します。CSV 形式の結果を返します。認証は MCP プロトコルによって処理されます。	インストール不要 — サーバー側で処理されます。MCP サーバーの登録が必要です（下記参照）。
az CLI	認証（az login）、ワークスペース／アイテムの検出用 Fabric REST。	ほとんどの開発環境にプリインストールされています
jq	az rest からの JSON の解析	プリインストール済み、または簡単にインストールできます

重要 — MCP と sqlcmd の違い： このスキルでは、すべての T-SQL 実行に fabric-sqlendpoint-execute_query MCP ツールを使用します。クエリの実行に COMMON-CLI の SQL/TDS/sqlcmd セクションを使用しないでください。これらの記述は、az rest のコントロールプレーンパターンにのみ適用されます。

エージェントによる事前確認 — 最初の SQL 操作の前に確認してください：

1. ツール一覧で fabric-sqlendpoint-execute_query ツールが使用可能であることを確認します。このツールは fabric-sqlendpoint MCP サーバーによって提供されます。エンドユーザー向けの方法である Fabric skills プラグインをインストールするか、このリポジトリの .mcp.json を使用して登録できます。他の MCP クライアントでは、それぞれ独自の設定を通じて登録できます。
2. 一致するツールが見つからない場合、ユーザーは Fabric SQL Endpoint MCP サーバーを登録する必要があります。登録手順については mcp-setup/ を参照してください。
   • グローバル URL：https://api.fabric.microsoft.com/v1/mcp/dataPlane/sqlEndpoint
   • アイテムスコープ URL：https://api.fabric.microsoft.com/v1/mcp/dataPlane/workspaces/{workspaceId}/items/{itemId}/sqlEndpoint

MCP ツールのシグネチャ

fabric-sqlendpoint-execute_query(workspaceId, itemId, query)

ツール名は異なる場合があります： execute_query は論理操作名です。サーバーの登録方法によっては、ツール一覧に表示される実際のツール名にプレフィックスが付く場合があります（例： fabric-sqlendpoint-execute_query または sqlendpoint-global-execute_query）。ツール一覧に表示された実際の名前を呼び出し、必ず workspaceId、itemId、query を渡してください。

パラメーター	型	説明
workspaceId	string (UUID)	対象アイテムを含むワークスペースの GUID
itemId	string (UUID)	クエリ対象となる Fabric アイテムの GUID。Warehouse または Mirrored Database の場合は、アイテム ID を使用します。Lakehouse の場合は、その SQL analytics endpoint ID（properties.sqlEndpointProperties.id）を使用します。Lakehouse のアイテム IDは使用しないでください。
query	string	T-SQL クエリテキスト（単一のバッチ — GO 区切り文字や sqlcmd メタコマンドは使用できません）

戻り値： 表形式の結果とメタデータテキスト（「Query returned N rows.」）を含む CSV リソース（RFC 4180）。

バッチに関するガイダンス： GO 区切り文字がなければ、SET NOCOUNT ON; SELECT ... のように、1 回の呼び出しで複数のステートメントを実行できます。返されるのは最後の結果セットのみです。独立した読み取りクエリの場合は、エラー処理を明確にするため、fabric-sqlendpoint-execute_query を個別に呼び出すことを推奨します。

MCP の制限

制限	値	備考
最大行数	10,000	この値を超える結果は切り捨てられます。TOP、フィルター、または集計を使用してください。
クエリのタイムアウト	300 秒	実行時間の長いクエリはタイムアウトエラーで失敗します。
レート制限	ID ごとに 1 分あたり 20 リクエスト	上限を超えると HTTP 429 が返されます。バックオフ後に再試行してください。

これらの値は確認された既定値であり、文書化された仕様ではありません。MCP サービスによって変更される可能性があります。正確な数値を前提とせず、実際に返される 429、タイムアウト、切り捨ての応答（または公開されている場合は Microsoft Learn）から、現在の動作を確認するための参考値として扱ってください。

サポートされているアイテムの種類

アイテムの種類	itemId の取得元	読み取りクエリ	DML（INSERT/UPDATE/DELETE）
Warehouse	GET /v1/workspaces/{wId}/warehouses → アイテムの id	✅	✅
Lakehouse SQL Endpoint	GET /v1/workspaces/{wId}/lakehouses → properties.sqlEndpointProperties.id（Lakehouse の id ではありません）	✅	❌（読み取り専用）
Mirrored Database	GET /v1/workspaces/{wId}/mirroredDatabases → アイテムの id	✅	❌（読み取り専用）

---

接続

workspaceId と itemId を確認する

fabric-sqlendpoint-execute_query を呼び出すには、ワークスペース GUID とアイテム GUID が必要です。Fabric REST API を使って確認してください。

# 1. Find workspace ID by name (capture into WS_ID for the next calls)
WS_ID=$(az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces" \
  --query "value[?displayName=='MyWorkspace'].id" --output tsv)
echo "Workspace ID: $WS_ID"

# 2. Find warehouse item ID by name
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/warehouses" \
  --query "value[?displayName=='MyWarehouse'].id" --output tsv
# For a Lakehouse, pass its SQL analytics endpoint id — NOT the lakehouse item id
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/lakehouses" \
  --query "value[?displayName=='MyLakehouse'].properties.sqlEndpointProperties.id" --output tsv

クエリを実行する

workspaceId と itemId を取得したら、MCP ツールを呼び出します。

fabric-sqlendpoint-execute_query(
  workspaceId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  itemId: "11111111-2222-3333-4444-555555555555",
  query: "SELECT TOP 10 * FROM dbo.FactSales"
)

追加の接続設定は不要です — 認証は MCP プロトコルによって透過的に処理されます。

---

エージェントによる探索（「データとチャット」）

スキーマの確認手順

エンドポイントの内容を把握するため、以下を順番に実行してください。拡張版の確認用クエリについては、references/discovery-queries.md を参照してください。

# 1. List schemas
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT schema_name FROM INFORMATION_SCHEMA.SCHEMATA ORDER BY schema_name")

# 2. List tables and views
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT table_schema, table_name, table_type FROM INFORMATION_SCHEMA.TABLES ORDER BY table_schema, table_name")

# 3. Columns for a table
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT column_name, data_type, character_maximum_length, is_nullable FROM INFORMATION_SCHEMA.COLUMNS WHERE table_schema='dbo' AND table_name='FactSales' ORDER BY ordinal_position")

# 4. Preview rows
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT TOP 5 * FROM dbo.FactSales")

# 5. Row counts
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT s.name AS [schema], t.name AS [table], SUM(p.rows) AS row_count FROM sys.tables t JOIN sys.schemas s ON t.schema_id=s.schema_id JOIN sys.partitions p ON t.object_id=p.object_id AND p.index_id IN (0,1) GROUP BY s.name, t.name ORDER BY row_count DESC")

# 6. Programmability objects (views, functions, procedures)
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT name, type_desc FROM sys.objects WHERE type IN ('V','FN','IF','P','TF') ORDER BY type_desc, name")

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

1. 確認 → ステップ 1～3 を実行して、利用可能なテーブルと列を把握します。
2. サンプル抽出 → 関連するテーブルで SELECT TOP 5 を実行します。
3. 作成 → SQLDW-CONSUMPTION-CORE.md のサポート対象 T-SQL 機能を使って T-SQL を記述します。
4. 実行 → fabric-sqlendpoint-execute_query(workspaceId, itemId, query) を呼び出します。
5. 反復 → 結果に基づいて調整します。
6. 提示 → 結果を表示するか、後続のクエリを生成します。

---

注意点、ルール、トラブルシューティング

T-SQL／プラットフォームに関する注意点の全容については、SQLDW-CONSUMPTION-CORE.md の「注意点とトラブルシューティングのリファレンス」を参照してください。

必ず行うこと

• fabric-sqlendpoint-execute_query MCP ツールが利用可能であることを確認する — 初回操作の前にツール一覧を確認してください。利用できない場合は、ユーザーに MCP サーバーの登録を案内してください。
• 必ず TOP または WHERE フィルターを使う — MCP ツールが返す行数の上限は 10,000 行です。ちょうど 10,000 行が返された場合、結果が途中で切り詰められている可能性があります。
• 大きなテーブルでは最初に COUNT(*) を使う — 上限のない SELECT を実行する前に、行数を確認してください。
• 複数文のクエリでは先頭に SET NOCOUNT ON; を指定する — 行数メッセージを抑制します。
• クエリに OPTION (LABEL = 'AGENTCLI_...') を付けてラベルを設定する — Query Insights によるトレースに使います。
• 有効な T-SQL のみを送信する — GO バッチ区切り、:setvar、sqlcmd のメタコマンドは使用しないでください。各 fabric-sqlendpoint-execute_query 呼び出しは単一の T-SQL バッチです。
• 複数バッチの操作では複数回ツールを呼び出す — GO 区切りが必要な場合は、別々の fabric-sqlendpoint-execute_query 呼び出しに分割してください。

避けること

• sqlcmd — 代わりに fabric-sqlendpoint-execute_query MCP ツールを使ってください。クエリの実行に sqlcmd をシェルから呼び出さないでください。
• 上限のない SELECT * — 10,000 行の上限に達します。必ず TOP N または WHERE フィルターを使ってください。
• 短時間に連続してクエリを実行すること — レート制限は ID ごとに 20 リクエスト／分です。呼び出しの間隔を空けるか、JOIN や UNION ALL でまとめてください。
• Lakehouse／Mirrored DB での DML — これらは読み取り専用です。DML が使えるのは Warehouse アイテムのみです。
• クエリテキスト内の GO 区切り — サポートされていません。バッチごとに別々のツール呼び出しを使ってください。
• MARS — サポートされていません。クエリはそれぞれ独立して実行されます。
• アイテム ID のハードコーディング — REST API で確認してください（「接続」セクション）。

推奨事項

• T-SQL の実行には、CLI ツールより fabric-sqlendpoint-execute_query MCP ツールを優先する。
• 探索クエリには TOP N を使い、行数制限への到達を避ける。
• レート制限への負荷を減らすため、関連するクエリを JOIN 付きの単一の SELECT にまとめる。
• Fabric REST API の操作（ワークスペース／アイテムの確認、容量管理）には az rest を使う。
• テーブル全体のスキャンより 集計クエリ（COUNT、SUM、AVG、GROUP BY）を優先する。
• 結果を確定的にするため、TOP と ORDER BY を組み合わせる。

トラブルシューティング

症状	原因	対処方法
MCP ツールを利用できない	MCP サーバーが登録されていない	MCP クライアントの設定に https://api.fabric.microsoft.com/v1/mcp/dataPlane/sqlEndpoint を登録します
HTTP 401 / Unauthorized	認証トークンの有効期限が切れているか、無効です	再認証します（MCP クライアントによって異なります。az login での更新が必要な場合があります）
HTTP 403 / Forbidden	ワークスペース／アイテムの権限が不足しています	ユーザーにワークスペース／アイテムの Viewer 以上のロールがあることを確認します
HTTP 404 / Not Found	workspaceId/itemId が間違っているか、機能が有効になっていません	REST API で ID を確認し、テナントで MCP 機能が有効になっているか確認します
HTTP 429 / Too Many Requests	レート制限を超過しています（20 req/min）	しばらく待ってからバックオフ付きで再試行します。クエリをまとめます
クエリがタイムアウトする（300s）	クエリが複雑すぎるか、データ量が多すぎます	クエリを簡素化し、フィルターを追加して、TOP を使用します
返される行数がちょうど 10,000 行	結果が切り詰められています	TOP N または WHERE フィルターを追加します。合計を確認するには COUNT(*) を使用します
"Invalid workspaceId/itemId"	UUID の形式が正しくありません	UUID が正しい形式（8-4-4-4-12 桁の 16 進数）であることを確認します
レスポンスに SQL エラーがある	T-SQL 構文エラーまたは無効なオブジェクト	T-SQL を修正し、スキーマの確認でテーブル名／列名を確認します
データが存在するのに行が返されない	RLS によるフィルタリング	USER_NAME() を確認し、RLS ポリシーを確認します
Invalid object name 'queryinsights...'	作成から 2 分未満の新しいウェアハウス	約 2 分待ちます