sqldw-cli

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

重要な注意事項

1. ワークスペース名からワークスペースの詳細（IDを含む）を特定するには、すべてのワークスペースを一覧表示し、その後、JMESPath でフィルターしてください。
2. ワークスペース ID、アイテムの種類、アイテム名からアイテムの詳細（IDを含む）を特定するには、そのワークスペース内の該当する種類のアイテムをすべて一覧表示し、その後、JMESPath でフィルターしてください。
3. スキルの判別：Warehouse、Lakehouse SQL 分析エンドポイント、または Mirrored Database に送信する T-SQL には、プレーンな Lakehouse テーブルの SELECT、行数カウント、フィルター、集計のリクエストも含めて、sqldw-cli を使用してください。Azure Synapse または Dedicated SQL Pool のエンドツーエンドの移行中に実行する対象 Warehouse の SQL は synapse-migration に該当します。移行の前後に行う単独の Warehouse 作業には、sqldw-cli を使用してください。ノートブックセルまたは PySpark DataFrame の作業は spark-cli、Fabric SQL database（OLTP）は sqldb-cli に該当します。

Fabric Warehouse と SQL エンドポイント — CLI スキル

このスキルは、Fabric Warehouse、Lakehouse SQL 分析エンドポイント、Mirrored Database を対象とし、T-SQL の作成と取り込み、読み取り専用クエリ、Warehouse のパフォーマンス診断を担当します。

これはモードディスパッチャーであり、手順は含まれていません。以下の表からリクエストに一致するモードを選び、コマンドを1つでも実行する前に、ファイル読み取りツールを使って該当する references/<mode>.md ファイルを最初から最後まで読んでください。そのファイルには、T-SQL の適用範囲、DDL の制約、クエリテンプレート、注意点が記載されています。読まずに作業すると、無効な T-SQL が生成され、誤った結果につながります。

モードの選択

モード	リクエストの内容	トリガーの例	最初に読むファイル
authoring	Warehouse の状態を変更する：テーブル DDL、DML、取り込み、トランザクション、プロシージャ、スキーマの進化、タイムトラベル	Warehouse テーブルの作成、COPY INTO、OPENROWSET、INSERT/UPDATE/DELETE、Warehouse の MERGE、CTAS、sp_rename、T-SQL プロシージャの作成、Warehouse のタイムトラベル	references/authoring.md
consumption	データまたはメタデータを読み取る：SELECT、行数カウント、フィルター、集計、スキーマ／オブジェクトの検出、CSV エクスポート	Warehouse のクエリ、Lakehouse の行数カウント、Lakehouse の SELECT、テーブルの表示、Warehouse スキーマの説明、SQL データのエクスポート	references/consumption.md
operations	queryinsights とサポートされているエンドポイント診断を通じて、パフォーマンス、失敗、容量消費、SQL プールの使用状況、または正常性を診断する	失敗またはキャンセルされた Warehouse クエリ、CU の急増、Capacity Metrics アプリ、コストの高い SQL ユーザー、カスタム SQL プールの推奨事項、queryinsights の CPU、負荷イベント、キャッシュのウォーム状態、対処が必要な Lakehouse テーブル	references/operations.md

運用リファレンスの索引

運用に関するリクエストでは、まず references/operations.md を読み、次にこの索引から該当するリーフを直接開いてください。リーフ内のリンクをたどらないでください。複合的なリクエストでは、scenarios.md に従い、この索引から直接リンクされている追加のリーフのみを参照してください。

リクエスト	参照するリーフ
データウェアハウスが遅い理由、パフォーマンス低下、最適化、または実行中の処理などの複合的な運用シナリオ	references/operations/scenarios.md
遅いクエリの概要、上位ユーザー、最近のクエリ、パターン検索、実行時プロファイル、クラスターキー候補	references/operations/query-reference.md
失敗またはキャンセルされたリクエスト、エラーコード、繰り返し発生する非成功クエリの形式	references/operations/failure-analysis.md
SQL プールの負荷が高い時間帯と重複するリクエスト	references/operations/pool-pressure.md
CPU 使用率の集中、性能低下、繰り返し発生する高コストのクエリ、キャッシュの解釈	references/operations/resource-consumers.md
Lakehouse の Delta ファイルの健全性とメンテナンスが必要なテーブル	references/operations/lakehouse-health.md
Capacity Metrics の CU スパイク、高コストのアイテム、SQL クエリとユーザーの相関	references/operations/capacity-metrics-correlation.md — セクション 1 から開始
特定済みの SQL エンドポイント向けのカスタム SQL プールの推奨事項	references/operations/capacity-metrics-correlation.md — FabricIQ をスキップしてセクション 6 から開始

モードの境界ルール

エンドポイントではなく、意図に基づいて分類してください。3 つのモードすべてで同じ execute_query 呼び出しを使用します。

• CREATE TABLE の計画に使用するスキーマ検出用の SELECT は、読み取りのみですが authoring に該当します。
• ユーザーの質問に答える SELECT は consumption です。
• queryinsights.* に対するクエリ、または Lakehouse の sys.sp_get_table_health_metrics などのサポート対象の診断は operations です。ユーザーテーブルに対する SELECT は、どれだけ遅くても該当しません。

consumption と operations は読み取り専用です。リクエストが複数のモードにまたがる場合は、各処理を個別に行い、その部分を始める前に各リファレンスを読んでください。この表を読んでもモードが曖昧な場合は、推測するのではなく、短い確認の質問を 1 つしてください。

最終書き込み — 省略してはならない手順

リファレンスを読み、T-SQL を作成しただけではタスクは完了していません。ステートメントを送信していない場合、何も変更されていません。成功したと報告するのではなく、そのことを明示してください。

モード	最終書き込み
authoring	DDL/DML 自体を execute_query で送信します。続けて 2 回目の呼び出しで読み戻しを行い（CREATE の後は SELECT ... FROM INFORMATION_SCHEMA.TABLES、DML の後は SELECT COUNT(*)）、ユーザーが指定した名前で、作成または変更したオブジェクトを報告してください。テーブルの DDL/DML を受け付けるのは Warehouse のみです。Lakehouse SQL エンドポイントと Mirrored Database で許可される操作については、モードのリファレンスを参照してください。
consumption	なし — このモードは読み取り専用です
operations	なし — 読み取り専用ですが、診断ステートメントは必ず実行してください。数値はすべて、報告するターン内で実行した SELECT または文書化された読み取り専用の診断プロシージャから取得し、出典のビューまたはプロシージャを本文中に明記してください。以前のターンの数値を引き継いではいけません。診断で許可される EXEC は、Lakehouse SQL analytics エンドポイントでの sys.sp_get_table_health_metrics のみです。診断結果が確実であっても、自分で ALTER、CREATE、DROP を実行してはいけません。

consumption および operations のレポート

どちらの読み取り専用モードもターミナルへの書き込みを行わないため、成果物は回答そのものです。ライブエンドポイントにクエリを実行し、実際の行を報告してください。リファレンスの要約では、依頼への回答になりません。

operations では、各数値のすぐそばに、その数値の取得元であるビュー、カタログ、またはプロシージャを記載してください（例：2,140 ms (queryinsights.long_running_queries)、268 files (sys.sp_get_table_health_metrics)）。該当する行がゼロ件の場合も同様です。 報告するターン内で診断を再実行し、以前のターンの出力を繰り返さないでください。診断の数値を捏造、仮定、推測してはいけません。

共通の基本事項（すべてのモード）

すべてのモードで、データプレーンには同じ方法でアクセスします。最初にワークスペースとアイテムを解決し、その後、MCP ツールを通じて T-SQL を送信します。

実行インターフェイス — fabric-sqlendpoint-execute_query

すべての T-SQL は、fabric-sqlendpoint-execute_query MCP ツールを通じて実行します。SQL データプレーンの実行では、このスキルが COMMON-CLI の SQL/TDS に関するガイダンスに優先します。ドキュメントに記載された Legacy CLI Fallback の経路を明示的に使用する場合（モードリファレンスを参照）を除き、sqlcmd ではなく MCP ツールを使用してください。コントロールプレーンの検出には、引き続き az rest が適切なツールです。

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

• 事前確認： どのモードでも最初の操作を行う前に、ツール一覧に名前が execute_query で終わるツールがあることを確認してください。このツールは、Fabric スキルの plugin またはこのリポジトリの .mcp.json によって登録された fabric-sqlendpoint MCP サーバーから提供されます。実際の名前にはプレフィックスが付く場合があります（fabric-sqlendpoint-execute_query、sqlendpoint-global-execute_query）。実際に表示されている名前を呼び出してください。該当するツールがない場合は、その旨を伝えてから、モードリファレンスに記載された Legacy CLI Fallback（TDS クライアント）を使用してください。主要な経路を利用できるよう、ユーザーがサーバーを登録できることも伝えてください。詳しくは mcp-setup/ を参照してください。例外： Capacity Metrics の相関ワークフローは、既存の FabricIQ と SQL Endpoint MCP のインターフェイスに限定されています。SQL Endpoint MCP を利用できない場合は、そのフェーズがブロックされていると報告し、レガシーのフォールバックは使用しないでください。
• itemId は GUID です。FQDN や -d <DatabaseName> は使用できません。 Warehouse または Mirrored Database ではアイテム ID を使用します。Lakehouse では、Lakehouse のアイテム ID ではなく、properties.sqlEndpointProperties.id を使用してください。
• 1 回の呼び出しにつき T-SQL バッチは 1 つです。 GO 区切り文字や sqlcmd のメタコマンド（:setvar、:r、-i）は使用できません。複数のバッチに分ける作業は、別々の呼び出しに分割してください。返されるのは最後の結果セットだけです。
• 結果は最大 10,000 行で、クエリは 300 秒でタイムアウトし、レート制限は 20 リクエスト/分です。 TOP N、WHERE、または集計を使用してください。結果がちょうど 10,000 行の場合、切り捨てられています。これらは観測されたデフォルト値であり、文書化された保証ではありません。

共通リファレンス

タスク	リファレンス	備考
Fabric のワークスペースとアイテムを見つける	COMMON-CLI.md	必須 — ワークスペースまたはアイテムの ID を解決する前にお読みください
Fabric のトポロジと主要な概念	COMMON-CORE.md	アイテムの種類、ワークスペース、容量
環境 URL	COMMON-CORE.md	ソブリンクラウド／パブリッククラウド以外のホスト
認証とトークンの取得	COMMON-CORE.md	対象が間違っていると 401 が発生します。認証の問題がある場合は、まずお読みください
認証の手順	COMMON-CLI.md	az login のフローとトークンの取得
az rest による Fabric コントロールプレーン API	COMMON-CLI.md	必ず --resource を指定してください。ページネーションと LRO ヘルパー
コアコントロールプレーン REST API	COMMON-CORE.md	ページネーション、LRO ポーリング、レート制限
注意事項とトラブルシューティング	COMMON-CLI.md	az rest の対象、シェルのエスケープ、トークンの有効期限

ルール

必須

• 何かを行う前に、上の表からモードをちょうど 1 つ選択してください。
• そのモードの最初のコマンドを実行する前に、最初のツール呼び出しとして references/<mode>.md を最初から最後までお読みください。一度だけ、一回の通読でお読みください。再度開いたり、再び grep したり、分割して読み進めたりしないでください。内容はすでに確認済みです。
• 特定の操作に関するリクエストでは、references/operations.md の後に、対応するリーフを 1 つお読みください。複合的なリクエストでは、references/operations/scenarios.md を読み、そのシナリオで指定されている特定のリーフをそれぞれお読みください。各ファイルは一度ずつ、全体をお読みください。
• ワークスペース ID とアイテム ID は、一覧表示して絞り込むことで解決してください。GUID を推測してはいけません。
• fabric-sqlendpoint-execute_query ツールが利用可能な場合は、必ず T-SQL の実行に使用してください。利用できない場合に限り、モードのリファレンスに記載されている Legacy CLI Fallback に切り替えてください。
• リクエストが境界をまたいでモードを切り替える場合は、明示的にその旨を伝えてください。
• リファレンスは指示として扱い、成果物として扱わないでください。読んだ後、記載されたステートメントをライブエンドポイントに対して実行し、実際の結果を報告してください。リファレンスの内容を実行せずに引用しても、リクエストへの回答にはなりません。
• ユーザーが求めた成果物はすべて、指定された名前で作成してください。「該当なし」「0 行」「該当しない」という結果であっても、見出しは残してください。

推奨

• リクエストを満たす最も限定的なモードを選択してください。
• 選択した特定のシナリオまたは複合シナリオで必要となる、モードのリファレンス 1 つと、直接参照されている最小限の操作リーフのみをお読みください。
• ユーザーが訂正できるよう、最初の応答で選択したモードを伝えてください。
• クエリの実行を Query Insights で追跡できるよう、OPTION (LABEL = '...') でラベルを付けてください。
• 関連するステートメントをまとめて呼び出し回数を減らしてください。レート制限はクエリ単位ではなく、ID 単位です。

避けること

• このディスパッチャーだけを根拠に作業すること。この内容では、T-SQL の実行範囲、DDL の制約、診断クエリの形式を意図的に省略しています。
• リファレンスを実行する代わりに、その要約で回答すること。
• すでに読み込んだリファレンスを再読したり、再び grep したりすること。ターンとトークンを浪費します。
• 読み取り専用モード（consumption、operations）で何かを変更すること。
• 上限のない SELECT *。10,000 行で暗黙的に切り捨てられます。
• このスキルが担当する作業に、別のスキルを読み込むこと（CRITICAL NOTES 3 を参照）。

例

ユーザーのリクエスト	モード	参照するファイル
"SkillsTestWarehouse の nyctlc テーブルには何行ありますか？"	consumption	references/consumption.md
"ウェアハウスに OrderId、CustomerId、OrderDate を含む dbo.Orders を作成してください。"	authoring	references/authoring.md
"COPY INTO を使って、OneLake の Files/nyctlc_sample.csv をウェアハウスに読み込んでください。"	authoring	references/authoring.md
"最も遅いクエリと、クラスター化すべきテーブルを教えてください。"	operations	references/operations.md
"レイクハウスの SQL エンドポイントから、ベンダーごとの平均移動距離を表示してください。"	consumption	references/consumption.md