sqldw-authoring-cli

テレメトリ — 必須です。 すべての api.fabric.microsoft.com 呼び出しには、 x-ms-fabric-skill: sqldw-authoring-cli（az rest: --headers "x-ms-fabric-skill=sqldw-authoring-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 Authoring — CLI スキル

⚠️ SQL 実行の例外規定： SQL データプレーンの実行については、このスキルが COMMON-CLI の SQL/TDS に関するガイダンスに優先します。特にレガシー CLI フォールバックを使用する場合を除き、MCP fabric-sqlendpoint-execute_query を使用してください（Tool Stack を参照）。

目次

タスク	参照	注記
Fabric のワークスペースとアイテムを検索する	COMMON-CLI.md § Fabric のワークスペースとアイテムを検索する	必須 — 最初にリンクを読む [名前からワークスペース ID を、または名前、アイテムの種類、ワークスペース ID からアイテム ID を検索するために必要です]
Fabric のトポロジと主要な概念	COMMON-CORE.md § Fabric のトポロジと主要な概念
環境 URL	COMMON-CORE.md § 環境 URL
認証とトークンの取得	COMMON-CORE.md § 認証とトークンの取得	対象ユーザーが誤っていると 401 が発生します。認証の問題が発生した場合は、まずお読みください
コアのコントロールプレーン REST API	COMMON-CORE.md § コアのコントロールプレーン REST API	ページネーション、LRO のポーリング、レート制限のパターンを含みます
OneLake データアクセス	COMMON-CORE.md § OneLake データアクセス	Fabric トークンではなく、storage.azure.com トークンが必要です
定義エンベロープ	ITEM-DEFINITIONS-CORE.md § 定義エンベロープ	定義ペイロードの構造
アイテムの種類ごとの定義	ITEM-DEFINITIONS-CORE.md § アイテムの種類ごとの定義	サポートマトリックス、デコードされたコンテンツ、パートのパス — REST の仕様、CLI のレシピ
ジョブの実行	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 を使用してください（トークンの対象ユーザーが異なります）
SQL / TDS データプレーンアクセス	COMMON-CLI.md § SQL / TDS データプレーンアクセス	従来の sqlcmd のリファレンスです（MCP が主な手段です。「ツールスタック」を参照）
ジョブの実行（CLI）	COMMON-CLI.md § ジョブの実行
OneLake ショートカット	COMMON-CLI.md § OneLake ショートカット
容量の管理（CLI）	COMMON-CLI.md § 容量の管理（CLI）
複合レシピ	COMMON-CLI.md § 複合レシピ
注意事項とトラブルシューティング（CLI 固有）	COMMON-CLI.md § 注意事項とトラブルシューティング（CLI 固有）	az rest の対象ユーザー、シェルのエスケープ、トークンの有効期限
クイックリファレンス	COMMON-CLI.md § クイックリファレンス	az rest のテンプレートと、トークンの対象ユーザー／ツールのマトリックス
アイテムの種類別機能マトリックス	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 § 一時テーブル
データベース間クエリ	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 § クイックリファレンス：データ利用機能
オーサリング機能マトリックス	SQLDW-AUTHORING-CORE.md § オーサリング機能マトリックス	最初にお読みください — DW と SQLEP のオーサリング範囲
テーブル DDL（DW のみ）	SQLDW-AUTHORING-CORE.md § テーブル DDL（DW のみ）	CREATE、CTAS、ALTER、sp_rename、DROP、制約、スキーマの進化、IDENTITY
DML 操作（DW のみ）	SQLDW-AUTHORING-CORE.md § DML 操作（DW のみ）	INSERT...SELECT、UPDATE、DELETE、TRUNCATE、MERGE
データ取り込み（DW のみ）	SQLDW-AUTHORING-CORE.md § データ取り込み（DW のみ）	COPY INTO、OPENROWSET、方式の比較
トランザクション（DW のみ）	SQLDW-AUTHORING-CORE.md § トランザクション（DW のみ）	スナップショット分離のみ。書き込み競合のルール
ストアドプロシージャ（オーサリングパターン）	SQLDW-AUTHORING-CORE.md § ストアドプロシージャ（オーサリングパターン）	ETL プロシージャ、アップサート、CTAS による入れ替え、カーソルの置き換え
タイムトラベルとウェアハウスのスナップショット	SQLDW-AUTHORING-CORE.md § タイムトラベルとウェアハウスのスナップショット（DW のみ）	FOR TIMESTAMP AS OF、30 日間の保持期間、スナップショットは GA
ソース管理と CI/CD	SQLDW-AUTHORING-CORE.md § ソース管理と CI/CD（DW のみ — プレビュー）	Git 統合、SQL DB プロジェクト、デプロイ パイプライン
オーサリングのアクセス許可モデル	SQLDW-AUTHORING-CORE.md § オーサリングのアクセス許可モデル	DDL／DML には最低でも Contributor、GRANT には Admin が必要です
オーサリングに関する注意事項とトラブルシューティング	SQLDW-AUTHORING-CORE.md § オーサリングに関する注意事項とトラブルシューティング	問題／原因／解決策をまとめた 17 行の表
一般的なオーサリングパターン	SQLDW-AUTHORING-CORE.md § 一般的なオーサリングパターン	増分読み込み、SCD Type 1、SQLEP ビューレイヤー
クイックリファレンス：オーサリングの判断ガイド	SQLDW-AUTHORING-CORE.md § クイックリファレンス：オーサリングの判断ガイド	シナリオから推奨される方法を検索
MCP によるコアオーサリング	authoring-cli-quickref.md § MCP によるコアオーサリング	execute_query によるテーブル DDL、DML、データ取り込み
MCP による高度なオーサリングパターン	authoring-cli-quickref.md § MCP による高度なオーサリングパターン	トランザクション、スキーマの進化、ストアドプロシージャ、タイムトラベル
MCP ワークフローテンプレート	authoring-script-templates.md § MCP ワークフローテンプレート	COPY INTO、ELT パイプライン、リトライ付きアップサート、スキーマ移行、タイムトラベルによる復旧
ツールスタック	SKILL.md § ツールスタック	fabric-sqlendpoint-execute_query MCP ツールと az CLI。最初の操作の前に確認してください
接続	SKILL.md § 接続	workspaceId/itemId の検出、実行例
クエリの実行	authoring-cli-quickref.md § クエリの実行	MCP ツール呼び出し形式、バッチに関する考慮事項
エージェントワークフロー	SKILL.md § エージェントワークフロー	ここから始めてください — 書き込みを行う前にスキーマを検出します
オーサリング操作の監視	authoring-cli-quickref.md § オーサリング操作の監視	実行中の DML／DDL、最近の ETL、失敗した書き込み
注意事項、ルール、トラブルシューティング	SKILL.md § 注意事項、ルール、トラブルシューティング	必ず実施／回避／優先のチェックリスト
エージェント統合に関する注意事項	authoring-cli-quickref.md § エージェント統合に関する注意事項	プラットフォーム固有のヒント（Copilot CLI、Claude Code）

---

ツールスタック

ツール	役割	インストール
fabric-sqlendpoint-execute_query MCP tool	主要：Fabric SQL エンドポイントに対して DDL／DML の 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 セクションを使用しないでください。

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

1. ツール一覧で fabric-sqlendpoint-execute_query ツールが利用可能であることを確認します。このツールは fabric-sqlendpoint MCP サーバーによって提供されます。このサーバーは Fabric スキルのプラグインをインストールする方法（エンドユーザー向け）か、このリポジトリの .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 の場合は、アイテム ID を使用します。Lakehouse の場合は、SQL 分析エンドポイントの ID（properties.sqlEndpointProperties.id）を使用します。Lakehouse アイテム IDは使用しないでください。
query	string	T-SQL クエリテキスト（単一バッチ — GO 区切り文字や sqlcmd のメタコマンドは使用できません）

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

バッチに関するガイダンス： GO を使わない複数のステートメントを 1 回の呼び出しで実行できます（例：CREATE TABLE ...; INSERT INTO ...）。ただし、返されるのは最後の結果セットのみで、いずれかのステートメントでエラーが発生するとバッチ全体が失敗します。独立した DDL／DML 操作には、fabric-sqlendpoint-execute_query を個別に呼び出すことを推奨します。エラーメッセージが分かりやすくなり、次に進む前に各手順の成功を確認できます。

MCP の制限

制限	値	備考
返される最大行数	10,000	DDL／DML の場合、行数のメタデータに影響を受けた行数が示されます
クエリのタイムアウト	300 秒	実行時間の長い操作はタイムアウトする場合があります
レート制限	ID ごとに 20 リクエスト／分	上限を超えると HTTP 429 が返されます

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

アイテムの種類ごとの作成範囲

機能	Warehouse (DW)	Lakehouse／Mirrored DB SQLEP
テーブル DDL（CREATE／ALTER／DROP）	✅	❌
DML（INSERT／UPDATE／DELETE／MERGE）	✅	❌
COPY INTO、OPENROWSET（取り込み）	✅	OPENROWSET は読み取り専用
トランザクション	✅	❌
タイムトラベル、スナップショット	✅	❌
CREATE VIEW／FUNCTION／PROCEDURE	✅	✅
CREATE SCHEMA	✅	✅

Fabric DW DDL の制約

これらの制約は必須要件です。違反するとエラーが発生します。

制約	詳細
CREATE TABLE で DEFAULT を使用しない	デフォルト値はサポートされていません。デフォルト値はアプリケーションまたは INSERT のロジックで設定してください。
CREATE TABLE 内で PRIMARY KEY を使用しない	ALTER TABLE ... ADD CONSTRAINT ... PRIMARY KEY NONCLUSTERED (col) NOT ENFORCED で追加する必要があります
DATETIME2 には精度が必要	必ず DATETIME2(6) を使用し、精度を指定しない DATETIME2 は使用しないでください
サポートされていないデータ型	NCHAR、NVARCHAR、TEXT、IMAGE、MONEY、SMALLMONEY、DATETIME は使用できません。代わりに VARCHAR、DECIMAL、DATETIME2(6) を使用してください
WITH DISTRIBUTION を使用しない	Fabric では分散が自動で行われます
制約には NOT ENFORCED を指定する	PRIMARY KEY NONCLUSTERED NOT ENFORCED、UNIQUE NONCLUSTERED NOT ENFORCED、FOREIGN KEY NOT ENFORCED
PK 列は NOT NULL にする	PK 制約を追加する前に、CREATE TABLE で PK 列を NOT NULL として宣言してください
ALTER TABLE の対象範囲	NULL 許容列の追加・削除（NULL の指定が必要）と制約の追加・削除（NOT ENFORCED のみ）は GA です。ALTER COLUMN による型の変更はプレビュー段階です（下記の注記を参照）

MERGE と ALTER COLUMN はハードエラーではありません。T-SQL の対応範囲によると、MERGE は一般提供されている Warehouse 機能であり、ALTER TABLE ... ALTER COLUMN はプレビュー段階です。スナップショット間の競合の分離が重要な場合は、明示的な DELETE と INSERT を優先してください。本番環境で重要な列の型を変更する場合は、構文がブロックされているからではなく、堅牢性を高める方法として CTAS と sp_rename を使用してください。

CREATE TABLE の正しいパターン：

CREATE TABLE dbo.Orders (
    OrderID INT NOT NULL,
    CustomerName VARCHAR(100) NULL,
    Amount DECIMAL(19,4) NULL,
    CreatedAt DATETIME2(6) NULL
)

ALTER TABLE dbo.Orders ADD CONSTRAINT PK_Orders PRIMARY KEY NONCLUSTERED (OrderID) NOT ENFORCED

その他のサポートされているパターン：

• CREATE TABLE [dbo].[clone] AS CLONE OF [dbo].[source] — テーブルの構造とデータを複製します
• COPY INTO — 外部ストレージからの取り込みで最高のスループットを実現します

---

接続

workspaceId と itemId を確認する

fabric-sqlendpoint-execute_query を呼び出すには、ワークスペースの GUID とアイテムの GUID が必要です。

# 1. Find workspace ID by name (capture into WS_ID for the next call)
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 SQL endpoint, 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

クエリを実行する

fabric-sqlendpoint-execute_query(
  workspaceId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  itemId: "11111111-2222-3333-4444-555555555555",
  query: "CREATE TABLE dbo.FactSales (SaleID bigint NOT NULL, Amount decimal(19,4) NOT NULL)"
)

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

DDL/DML の結果を検証する

DDL（CREATE/ALTER/DROP）の場合、ツールはメタデータとともに成功を返します。必ず次の手順で検証してください。

# After CREATE TABLE, verify it exists
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT table_schema, table_name FROM INFORMATION_SCHEMA.TABLES WHERE table_name = 'FactSales'")

# After DML, check row count
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT COUNT(*) AS row_count FROM dbo.FactSales")

---

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

作成前のスキーマ確認

書き込み操作を行う前に、対象のスキーマを確認してください。

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

# 2. Check columns
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT column_name, data_type, is_nullable FROM INFORMATION_SCHEMA.COLUMNS WHERE table_name='FactSales' ORDER BY ordinal_position")

# 3. Sample data
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT TOP 5 * FROM dbo.FactSales")

# 4. Check constraints
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT constraint_name, constraint_type FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS WHERE table_name='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
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～4 を実行し、利用可能なテーブルと列を把握します。
2. サンプル取得 → 関連するテーブルに対して SELECT TOP 5 を実行します。
3. パターンの選択 → SQLDW-AUTHORING-CORE.md（Table DDL から Common Authoring Patterns まで）からパターンを選択します。
4. 実行 → fabric-sqlendpoint-execute_query(workspaceId, itemId, query) を呼び出します。複数バッチの操作（例：BEGIN/END を含む CREATE PROCEDURE）では、GO を使わずに単一のバッチを使用してください。
5. 検証 → 影響を受けたテーブルをクエリします（SELECT COUNT(*)、SELECT TOP 5）。
6. 必要に応じて追加確認 → スキーマの変更を確認するため、追加のクエリを実行します。

---

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

作成時の注意点の全容については、SQLDW-AUTHORING-CORE.md の「Authoring Gotchas and Troubleshooting」を参照してください。 CLI 固有の問題については、COMMON-CLI.md の「Gotchas & Troubleshooting (CLI-Specific)」を参照してください。

必ず行うこと

• Warehouse を作成する前に、ワークスペースに容量があることを確認してください — GET /v1/workspaces/{id} を呼び出し、capacityId を確認します。
• fabric-sqlendpoint-execute_query MCP ツールが利用可能であることを確認してください — 最初の操作の前にツール一覧を確認します。利用できない場合は、MCP サーバーを登録するようユーザーに案内してください。
• 最初に workspaceId と itemId を特定してください — az rest で対象の Warehouse を解決します。このツールが受け取るのは GUID であり、FQDN や -d <DatabaseName> ではありません。
• （特定前に）まず az login を実行してください — az rest によるワークスペース／Warehouse の検索には、Azure CLI のセッションが必要です。fabric-sqlendpoint MCP サーバー自体はヘッダーを付与せずに提供され、Azure CLI トークンではなく MCP クライアントのネイティブな Fabric セッションで認証します。サインイン済みのセッションがない場合、どちらの経路でも認証に失敗します。
• スクリプトでは SET NOCOUNT ON; を使用してください — 出力を破損させる行数メッセージを抑制します。
• 1 回の呼び出しにつき、単一の T-SQL バッチを送信してください — GO 区切りや -i file.sql は使用しません。複数バッチにまたがる作業（CREATE PROCEDURE、複数ステップのトランザクションなど）は、複数の fabric-sqlendpoint-execute_query 呼び出しに分割します。
• 作成クエリには OPTION (LABEL = 'ETL_description') でラベルを付けてください。
• CTAS では明示的な CAST() を使用して、出力の型を制御してください。
• トランザクションは短く保ってください — 長いトランザクションは競合が発生する可能性のある期間を長くします。

避けること

• GO 区切り — MCP ツールが受け付けるのは単一の T-SQL バッチのみです。関連する DDL は 1 つのステートメントにまとめるか、fabric-sqlendpoint-execute_query を複数回呼び出します。
• sqlcmd のメタコマンド（:setvar、:r、-i）— MCP ツールでは利用できません。SQL はすべて query パラメーターに直接記述します。
• 上限のない SELECT * — 取得できる行数は 10,000 行までです。結果セットを制限するため、必ず TOP N または WHERE を使用します。
• 大規模な単一行の INSERT ... VALUES — 小さな Parquet ファイルが大量に作成されます。INSERT...SELECT、CTAS、または COPY INTO を使用します。
• 更新時の DROP TABLE IF EXISTS と CREATE TABLE — タイムトラベルの履歴が失われます。TRUNCATE TABLE と INSERT INTO を使用します。
• 本番環境での MERGE — GA ですが、テーブルレベルのスナップショット競合検出により、同時書き込みが失敗しやすくなります。分離が重要な場合は、DELETE と INSERT を優先します。
• 本番環境での ALTER COLUMN — プレビュー段階です。本番環境で重要な列の型変更には、CTAS と sp_rename を優先します（スキーマの進化）。
• CTAS での変数 — 使用できません。動的 SQL で囲みます：EXEC sp_executesql N'CREATE TABLE ...'。
• Lakehouse／Mirrored DB の SQLEP での DML — テーブルデータは読み取り専用です。作成できるのはビュー／関数／プロシージャのみです。
• 同じテーブルに対する同時 UPDATE／DELETE — スナップショット分離ではテーブルレベルで競合します。書き込みを順番に実行します。
• MCP の短時間での連続呼び出し — レート制限は 20 リクエスト／分です。可能な場合は複数のステートメントを 1 つのバッチにまとめます。
• MARS — サポートされていません。接続文字列から MultipleActiveResultSets を削除します。

優先すること

• CREATE TABLE と INSERT の組み合わせより CTAS — 並列処理が可能で、単一の操作で完了します。
• 単一行の INSERT より INSERT ... SELECT。
• 外部ファイルの取り込みには COPY INTO — 最も高いスループットが得られます。
• 本番環境でのアップサートには MERGE より DELETE と INSERT。
• WHERE 句のない DELETE FROM より TRUNCATE TABLE — 高速で、履歴を保持します。
• ステートメント間に GO が不要な場合、関連する DDL を 1 回の fabric-sqlendpoint-execute_query 呼び出しにまとめます。
• 大規模な変換では、UPDATE の代わりに CTAS と sp_rename を使用します。
• すべての T-SQL 操作には、sqlcmd より fabric-sqlendpoint-execute_query MCP ツールを使用します。
• 先頭に SET NOCOUNT ON; を付けます — 結果のメタデータノイズを減らします。
• TOP N または WHERE 句を使用します — 10K 行の上限内に収めます。

トラブルシューティング

症状	対処方法
エラー 24556/24706：スナップショットの競合	同じテーブルへの書き込みを直列化し、バックオフを入れて再試行します
COPY INTO の認証エラー	ADLS で Storage Blob Data Reader を付与するか、CREDENTIAL に SAS を指定します
OneLake からの COPY INTO が失敗する	ワークスペース ID をプロビジョニングし、ファイアウォールのルールを確認します
CTAS で予期しない型になる	SELECT で明示的に CAST() を使用します
単一 INSERT のパフォーマンスが低い	CTAS + drop + rename で Parquet を統合します
fabric-sqlendpoint-execute_query ツールが利用できない	MCP サーバーが登録されていません。ユーザーが Fabric SQL Endpoint MCP サーバーを追加する必要があります
HTTP 429：レート制限を超過	60 秒待って再試行します。クエリをまとめて呼び出し回数を減らします
クエリがタイムアウトする（300s）	操作を小さく分割します。COPY INTO の場合は、ソースファイルのサイズを確認します
SQLEP で sp_rename が失敗する	Warehouse でのみ利用でき、Lakehouse/Mirrored DB では利用できません
デプロイでテーブルが削除され、再作成される	DB プロジェクトで ALTER TABLE を避け、手動で適用します
最後の結果セットしか返されない	MCP が返すのは最後の SELECT のみです。複数の SELECT を含むバッチは、個別の呼び出しに分割します
バイナリ列が読み取れない	[base64] サフィックスが付いた列は base64 エンコードされています。必要に応じてデコードします