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 和重试。代码片段中省略了此项，但仍须添加。

更新检查 — 每个会话检查一次（必须） 在会话中首次使用此技能时，必须先运行 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 消耗 — CLI 技能

⚠️ SQL 执行覆盖规则： 对于 SQL 数据平面执行，此技能优先于 COMMON-CLI SQL/TDS 指南。请使用 MCP fabric-sqlendpoint-execute_query（参见工具栈），除非明确使用旧版 CLI 回退方案。

目录

任务	参考	说明
在 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 数据访问	需要 storage.azure.com 令牌，而不是 Fabric 令牌
作业执行	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 数据	使用 curl，而不是 az rest（令牌受众不同）
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 受众、Shell 转义、令牌过期
快速参考	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 § 临时表	使用 DISTRIBUTION = ROUND_ROBIN 以支持 INSERT INTO SELECT
跨数据库查询	SQLDW-CONSUMPTION-CORE.md § 跨数据库查询	三段式命名、同一工作区
使用场景的安全性	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 § 连接
Agent 式探索（“与我的数据对话”）	SKILL.md § Agent 式探索	数据探索请从这里开始
脚本生成	consumption-cli-quickref.md § 脚本生成	何时输出独立的 bash/PowerShell 脚本；az rest 发现 + 旧版 CLI 回退方案
监控和性能	consumption-cli-quickref.md § 监控和性能	活动查询 DMV（只读；不包括终止会话）
注意事项、规则和故障排除	SKILL.md § 注意事项、规则和故障排除	必须执行 / 避免 / 优先选择检查清单
Agent 集成说明	consumption-cli-quickref.md § Agent 集成说明	各 Agent 的 CLI 提示

---

工具栈

工具	角色	安装
fabric-sqlendpoint-execute_query MCP 工具	主要工具：对 Fabric SQL Endpoint 执行 T-SQL 查询。返回 CSV 结果。身份验证由 MCP 协议处理。	无需安装 — 由服务端提供。需要注册 MCP 服务（见下文）。
az CLI	身份验证（az login），通过 Fabric REST API 发现工作区/项目。	大多数开发环境中已预装
jq	解析来自 az rest 的 JSON	已预装或安装非常简单

重要 — MCP 与 sqlcmd： 此技能使用 fabric-sqlendpoint-execute_query MCP 工具执行所有 T-SQL。执行查询时，请勿使用 COMMON-CLI SQL/TDS/sqlcmd 章节。这些参考内容仅适用于 az rest 控制平面模式。

Agent 预检 — 首次执行 SQL 操作前请确认：

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 或 Mirrored Database，请使用项目 ID。对于 Lakehouse，请使用其 SQL analytics endpoint ID（properties.sqlEndpointProperties.id）——而不是 Lakehouse 项目 ID。
query	string	T-SQL 查询文本（单个批次 — 不含 GO 分隔符或 sqlcmd 元命令）

返回值： CSV 资源（RFC 4180），包含表格结果和元数据文本（“查询返回 N 行。”）。

批次说明： 单次调用中可以包含多个语句（例如 SET NOCOUNT ON; SELECT ...），但不能包含 GO 分隔符。只返回最后一个结果集。对于相互独立的读取查询，建议分别调用 fabric-sqlendpoint-execute_query，以便更清晰地处理错误。

MCP 限制

限制	值	说明
最大行数	10,000	超出此数量的结果会被截断。请使用 TOP、筛选条件或聚合。
查询超时	300 秒	长时间运行的查询会因超时错误而失败。
速率限制	每个身份每分钟 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

你需要工作区 GUID 和项 GUID 才能调用 fabric-sqlendpoint-execute_query。通过 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 协议透明处理。

---

Agent 式探索（“与我的数据对话”）

架构发现顺序

按顺序运行以下步骤，了解终结点中的内容。有关扩展的发现查询，请参阅 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")

Agent 工作流

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 工具。不要通过 shell 调用 sqlcmd 来执行查询。
• 不受限制的 SELECT *——会触及 10,000 行上限。始终使用 TOP N 或 WHERE 筛选条件。
• 连续快速执行查询——每个身份的速率限制为 20 req/min。请间隔调用，或使用 JOIN/UNION ALL 合并查询。
• 对 Lakehouse/Mirrored DB 执行 DML——这些对象为只读。DML 仅适用于 Warehouse 项。
• 在查询文本中使用 GO 分隔符——不受支持。每个批次请单独调用工具。
• MARS——不受支持。每个查询都独立运行。
• 硬编码项 ID——通过 REST API 发现（见“连接”部分）。

优先选择

• 使用 fabric-sqlendpoint-execute_query MCP 工具，而不是任何 CLI 工具来执行 T-SQL。
• 在探索查询中使用 TOP N——避免触及行数限制。
• 将相关查询合并为带 JOIN 的单个 SELECT，以降低速率限制带来的影响。
• 使用 az rest 执行 Fabric REST API 操作——例如发现工作区/项、管理容量。
• 优先使用聚合查询（COUNT、SUM、AVG、GROUP BY），而不是扫描整个表。
• 搭配 TOP 使用 ORDER BY，以获得确定性结果。

故障排查

症状	原因	解决方法
MCP 工具不可用	尚未注册 MCP 服务	在 MCP 客户端配置中注册 https://api.fabric.microsoft.com/v1/mcp/dataPlane/sqlEndpoint
HTTP 401 / 未授权	身份验证令牌已过期或无效	重新进行身份验证（取决于 MCP 客户端，可能需要刷新 az login）
HTTP 403 / 禁止访问	工作区/项的权限不足	确认用户在工作区/项中至少拥有查看者角色
HTTP 404 / 未找到	workspaceId/itemId 错误，或未启用该功能	通过 REST API 确认 ID；检查是否已为租户启用 MCP 功能
HTTP 429 / 请求过多	超出速率限制（20 次请求/分钟）	等待后重试，并采用退避策略；合并查询
查询超时（300s）	查询过于复杂或数据量过大	简化查询、添加筛选条件、使用 TOP
返回的行数恰好为 10,000	结果被截断	添加 TOP N 或 WHERE 筛选条件；使用 COUNT(*) 检查总数
“Invalid workspaceId/itemId”	UUID 格式错误	确认 UUID 格式正确（8-4-4-4-12 位十六进制数字）
响应中出现 SQL 错误	T-SQL 语法错误或对象无效	修正 T-SQL；通过架构发现确认表名/列名
没有返回行，但数据存在	RLS 筛选	检查 USER_NAME()，确认 RLS 策略
Invalid object name 'queryinsights...'	新建的数据仓库尚未满 2 分钟	等待约 2 分钟