关于 sqldw-authoring-cli
sqldw-authoring-cli 是用于 Microsoft Fabric SQL Endpoint 编写操作的命令行技能，涵盖 T-SQL 操作和 Fabric 专用设置。它指导用户先发现架构，并以 `fabric-sqlendpoint-execute_query` MCP 工具作为主要查询接口。
主要功能
- 01创建和修改表及架构
- 02执行 DDL 和 DML 操作
- 03使用 COPY INTO 或 OPENROWSET 加载数据
- 04管理存储过程和事务
- 05发现工作区、项目和架构
适用场景
- 01创建或修改 Warehouse 表
- 02向 Fabric Warehouse 加载数据
- 03构建 ETL 存储过程
- 04检查 SQL Endpoint 元数据
MCP 相关
该技能将 `fabric-sqlendpoint` MCP 服务提供的 `fabric-sqlendpoint-execute_query` 工具作为 T-SQL 执行的主要接口。工具接收工作区 ID、项目 ID 和查询，并返回 CSV 结果。
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/sqldw-authoring-cli确认已加载。
附带文件references/authoring-cli-quickref.mdreferences/authoring-script-templates.md
详细介绍
遥测 — 必须。 每次
api.fabric.microsoft.com调用都必须携带x-ms-fabric-skill: sqldw-authoring-cli（az rest：--headers "x-ms-fabric-skill=sqldw-authoring-cli"）， 包括每次 LRO 轮询、fabric_lro和重试。代码片段中省略了此项，但仍需添加。
更新检查 — 每个会话一次（必须） 在会话中首次使用此技能时，必须先运行 check-updates 技能，然后再继续。
- GitHub Copilot CLI / VS Code：调用
check-updates技能。- Claude Code / Cowork / Cursor / Windsurf / Codex：比较本地与远程 package.json 版本。
- 如果本会话前面已经执行过检查，则跳过。
重要说明
- 要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 筛选
- 要根据工作区 ID、项目类型和项目名称查找项目详细信息（包括其 ID）：列出该工作区中该类型的所有项目，然后使用 JMESPath 筛选
SQL Endpoint 编写 — CLI 技能
⚠️ SQL 执行覆盖规则： 对于 SQL 数据平面执行，此技能优先于 COMMON-CLI SQL/TDS 指南。除非明确使用 Legacy CLI Fallback，否则请使用 MCP
fabric-sqlendpoint-execute_query（请参阅工具栈）。
目录
工具栈
| 工具 | 作用 | 安装 |
|---|---|---|
fabric-sqlendpoint-execute_query MCP 工具 | 主要工具：对 Fabric SQL 终结点执行 DDL/DML T-SQL 查询。返回 CSV 结果。身份验证由 MCP 协议处理。 | 无需安装 — 由服务端提供。需要注册 MCP 服务。 |
az CLI | 身份验证（az login）、用于工作区/项发现和快照管理的 Fabric REST。 | 大多数开发环境中已预装 |
jq | 解析来自 az rest 的 JSON | 已预装或可轻松安装 |
重要说明 — MCP 与 sqlcmd： 此技能使用
fabric-sqlendpoint-execute_queryMCP 工具执行所有 T-SQL。执行查询时，请勿使用 COMMON-CLI SQL/TDS/sqlcmd 相关章节。
Agent 预检 — 首次操作前请确认：
- 确认工具列表中有
fabric-sqlendpoint-execute_query工具。此工具由fabric-sqlendpointMCP 服务提供，可通过安装 Fabric 技能 插件（面向最终用户的方式）或使用此仓库的.mcp.json进行注册；其他 MCP 客户端也可以通过各自的配置注册此工具。- 如果找不到匹配的工具，用户必须注册 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 analytics endpoint ID（properties.sqlEndpointProperties.id），而非 Lakehouse 项 ID。 |
query | string | T-SQL 查询文本（单个批次 — 不含 GO 分隔符或 sqlcmd 元命令） |
返回内容： CSV 资源（RFC 4180），包含表格结果和元数据文本。
批次使用建议： 一次调用中可以包含多条不带
GO的语句（例如，CREATE TABLE ...; INSERT INTO ...）。但是，只会返回最后一个结果集，并且任何语句出错都会导致整个批次失败。对于相互独立的 DDL/DML 操作，建议分别调用fabric-sqlendpoint-execute_query— 这样可以获得更清晰的错误消息，并在继续操作前确认每个步骤均已成功。
MCP 限制
| 限制 | 值 | 说明 |
|---|---|---|
| 返回的最大行数 | 10,000 | 对于 DDL/DML，行数元数据会显示受影响的行数 |
| 查询超时 | 300 秒 | 长时间运行的操作可能会超时 |
| 速率限制 | 每个身份每分钟 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）和添加/删除约束（仅限 NOT ENFORCED）已正式发布；ALTER COLUMN 类型变更仍处于预览阶段（见下方说明） |
MERGE和ALTER COLUMN不会导致硬性错误。 根据 T-SQL surface area，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")
Agent 工作流
编写前发现架构
执行任何写入操作前，请先发现目标架构：
# 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")
Agent 工作流
- 发现 → 执行步骤 1–4，了解可用的表和列。
- 抽样 → 对相关表执行
SELECT TOP 5。 - 拟定 → 从 SQLDW-AUTHORING-CORE.md 中选择模式（从表 DDL 到常见编写模式）。
- 执行 → 调用
fabric-sqlendpoint-execute_query(workspaceId, itemId, query)。对于多批次操作（例如，包含 BEGIN/END 的 CREATE PROCEDURE），请在单个批次中执行，不要使用GO。 - 验证 → 查询受影响的表（
SELECT COUNT(*)、SELECT TOP 5）。 - 可选的后续操作 → 执行其他查询，确认架构变更。
注意事项、规则与故障排除
完整的编写注意事项请参阅：SQLDW-AUTHORING-CORE.md 中的“编写注意事项与故障排除”。 CLI 特定问题请参阅：COMMON-CLI.md 中的“注意事项与故障排除（CLI 特定）”。
必须执行
- 创建仓库前，确认工作区容量充足——调用
GET /v1/workspaces/{id}并检查capacityId。 - 确认
fabric-sqlendpoint-execute_queryMCP 工具可用——首次操作前检查工具列表。如果不可用，请告知用户注册 MCP 服务。 - 先发现
workspaceId和itemId——通过az rest确定目标 Warehouse；该工具需要 GUID，而不是 FQDN 或-d <DatabaseName>。 - 先执行
az login（用于发现）——查询工作区和 Warehouse 的az rest操作需要 Azure CLI 会话。fabric-sqlendpointMCP 服务本身不附带请求标头，而是通过 MCP 客户端的原生 Fabric 会话进行身份验证，不存在已登录的会话 → 两种路径都会发生身份验证失败。 - 在脚本中使用
SET NOCOUNT ON;——禁止输出会破坏结果的行数消息。 - 每次调用只发送一个 T-SQL 批次——不要使用
GO分隔符或-i file.sql；将多批次工作（CREATE PROCEDURE、多步骤事务）拆分为多个fabric-sqlendpoint-execute_query调用。 - 使用
OPTION (LABEL = 'ETL_description')标记编写的查询。 - 在 CTAS 中使用 显式
CAST()控制输出类型。 - 保持事务简短——长事务会扩大冲突窗口。
避免
GO分隔符——MCP 工具只接受单个 T-SQL 批次。将相关 DDL 合并到一条语句中，或多次调用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——该功能已正式发布，但表级快照冲突检测可能导致并发写入失败。需要隔离时，优先使用 DELETE + INSERT。
- 在生产环境中使用 ALTER COLUMN——该功能仍处于预览阶段；对于生产关键型列类型更改（架构演进），优先使用 CTAS +
sp_rename。 - 在 CTAS 中使用变量——不允许。请将其封装在动态 SQL 中：
EXEC sp_executesql N'CREATE TABLE ...'。 - 对 Lakehouse/Mirrored DB SQLEP 执行 DML——表数据为只读。只能编写视图/函数/存储过程。
- 对同一张表并发执行 UPDATE/DELETE——快照隔离会在表级别产生冲突。请串行执行写入。
- 快速连续发起 MCP 调用——速率限制为 20 req/min。尽可能将多条语句合并到一个批次中。
- MARS——不支持。请从连接字符串中移除
MultipleActiveResultSets。
优先使用
- 优先使用 CTAS，而不是
CREATE TABLE+INSERT——并行执行，单次操作。 - 优先使用
INSERT ... SELECT，而不是单行 INSERT。 - 外部文件导入优先使用
COPY INTO——吞吐量最高。 - 在生产环境中进行 upsert 时，优先使用 DELETE + INSERT，而不是 MERGE。
- 无 WHERE 子句时，优先使用
TRUNCATE TABLE，而不是DELETE FROM——速度更快，并保留历史记录。 - 无需在语句之间使用
GO时，优先将相关 DDL 合并到一次fabric-sqlendpoint-execute_query调用中。 - 大规模转换时，优先使用 CTAS + sp_rename，而不是 UPDATE。
- 所有 T-SQL 操作都优先使用
fabric-sqlendpoint-execute_queryMCP 工具，而不是 sqlcmd。 - 使用
SET NOCOUNT ON;前缀——减少结果中的元数据噪声。 - 使用
TOP N或WHERE子句——确保不超过 10K 行的上限。
故障排除
| 症状 | 解决方法 |
|---|---|
| 错误 24556/24706，快照冲突 | 对同一张表的写入操作进行串行化；使用退避策略重试 |
COPY INTO 身份验证错误 | 在 ADLS 上授予 Storage Blob Data Reader 权限；或在 CREDENTIAL 中使用 SAS |
COPY INTO 从 OneLake 加载失败 | 配置工作区身份；检查防火墙规则 |
| CTAS 产生意外类型 | 在 SELECT 中使用显式 CAST() |
| 单条 INSERT 性能不佳 | 解决方法：使用 CTAS + drop + rename 来合并 Parquet |
fabric-sqlendpoint-execute_query 工具不可用 | MCP 服务未注册——用户必须添加 Fabric SQL Endpoint MCP 服务 |
| HTTP 429，超过速率限制 | 等待 60 秒后重试；将查询合并为更少的调用 |
| 查询超时（300 秒） | 拆分为更小的操作；对于 COPY INTO，检查源文件大小 |
| SQLEP 上的 sp_rename 失败 | 仅适用于 Warehouse，不适用于 Lakehouse/Mirrored DB |
| 部署删除并重新创建表 | 避免在 DB project 中使用 ALTER TABLE；手动应用 |
| 仅返回最后一个结果集 | MCP 仅返回最后一个 SELECT。将多个 SELECT 的批次拆分为多个调用。 |
| 二进制列不可读 | 带有 [base64] 后缀的列采用 base64 编码。需要时进行解码。 |
评论
支持 Markdown