sqldw-cli

遥测——强制要求。 每次 api.fabric.microsoft.com 调用都必须携带 x-ms-fabric-skill: sqldw-cli（az rest：--headers "x-ms-fabric-skill=sqldw-cli"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项，但仍须添加。 这适用于所有三种模式；各模式参考文件均继承此要求。

重要注意事项

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 数据库（OLTP）属于 sqldb-cli。

Fabric Warehouse 和 SQL 终结点——CLI 技能

此技能涵盖 Fabric Warehouse、Lakehouse SQL 分析终结点和 Mirrored Database：T-SQL 编写与数据摄取、只读查询以及 Warehouse 性能诊断。

这是一个模式分派器，不包含任何操作步骤。根据请求从下表中选择对应模式，然后在执行任何命令之前，使用文件读取工具从头到尾阅读对应的 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 行数、SELECT lakehouse、显示表、描述 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 节开始

模式边界规则

按意图而非终结点分类——这三种模式都调用同一个 execute_query。

• 为规划 CREATE TABLE 而运行的模式发现 SELECT 属于 authoring，即使它只读取数据。
• 用于回答用户问题的 SELECT 属于 consumption。
• 对 queryinsights.* 或受支持的诊断项（例如 Lakehouse sys.sp_get_table_health_metrics）执行查询属于 operations；对用户表执行 SELECT 则不属于此模式，无论查询有多慢。

consumption 和 operations 均为只读。如果请求确实跨越多种模式，请逐一处理，并在开始每部分之前阅读相应参考。如果阅读此表后仍无法确定模式，请简短询问一个澄清问题，不要猜测。

最终写入 — 不可跳过的步骤

阅读参考并起草 T-SQL 并不代表任务已完成。如果你没有发送语句，就没有发生任何更改——请明确说明这一点，而不是报告成功。

模式	最终写入
authoring	通过 execute_query 发送 DDL/DML 本身。随后在第二次调用中进行回读（CREATE 后执行 SELECT ... FROM INFORMATION_SCHEMA.TABLES，DML 后执行 SELECT COUNT(*)），并使用用户指定的名称报告你创建或更改的对象。只有 Warehouse 接受表 DDL/DML——Lakehouse SQL 终结点和 Mirrored Database 允许执行的操作，请参阅模式参考。
consumption	无 — 此模式为只读
operations	无 — 只读，但仍必须运行诊断语句：所有数据都必须来自你报告该数据的本轮中执行的 SELECT 或有文档记录的只读诊断过程，并在文中注明其来源视图或过程，不能沿用先前轮次的数据。唯一允许的诊断 EXEC 是在 Lakehouse SQL 分析终结点上调用 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 指引 — 请使用 MCP 工具，而不是 sqlcmd，除非你明确采用模式参考中记载的 Legacy CLI Fallback 路径。az rest 仍是进行控制平面发现的正确工具。

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

• 前置检查：在任何模式的首次操作之前，确认工具列表中有名称以 execute_query 结尾的工具。该工具来自 fabric-sqlendpoint MCP 服务，由 Fabric 技能插件或此仓库的 .mcp.json 注册。具体名称可能带前缀（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，请使用 properties.sqlEndpointProperties.id，不要使用 Lakehouse 项 ID。
• **每次调用只执行一个 T-SQL 批次。**不要使用 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 受众、Shell 转义、令牌过期

规则

必须

• 开始任何操作前，先从上表中准确选择一种模式。
• 在执行该模式的第一条命令之前，先从头到尾阅读 references/<mode>.md，并将其作为你的第一次工具调用。完整阅读一次即可：不要重新打开、再次 grep 或逐页浏览。你已经拥有该文件。
• 对于范围明确的操作请求，在阅读 references/operations.md 后，阅读与之匹配的一个叶级文件。对于复合请求，先阅读 references/operations/scenarios.md，然后阅读该场景指定的每个范围明确的叶级文件；每个文件都要完整阅读一次。
• 通过列出并筛选来解析工作区和项目 ID，绝不要猜测 GUID。
• 只要 fabric-sqlendpoint-execute_query 工具可用，就通过它执行 T-SQL；只有该工具不可用时，才使用模式参考中记录的旧版 CLI 后备方案。
• 请求跨越边界时，明确宣布切换模式。
• 将参考内容视为操作说明，而不是交付成果。阅读后，针对实时端点运行文档中的语句，并报告实际结果。只引用参考中的内容而不执行，不能算作回答了请求。
• 以用户指定的名称生成用户要求的每一项成果；即使结果为“无”“零行”或“不适用”，也要保留其标题。

优先

• 选择满足请求的最精简模式。
• 仅阅读一种模式参考，以及所选范围明确或复合场景直接索引的必要操作叶级文件。
• 在首次回复中说明你选择的模式，以便用户纠正。
• 使用 OPTION (LABEL = '...') 标记查询，便于在 Query Insights 中追踪运行记录。
• 将相关语句合并为更少的调用 — 速率限制按身份计算，而不是按查询计算。

避免

• 仅依据此分派器采取行动 — 它有意省略了 T-SQL 范围、DDL 限制和诊断查询形式。
• 用参考内容摘要代替实际执行。
• 重新阅读或重新 grep 已加载的参考；这会浪费轮次和令牌。
• 在只读模式（consumption、operations）下执行任何更改。
• 使用无边界的 SELECT * — 它会静默截断到 10,000 行。
• 为此技能已负责的工作加载其他技能（参见 CRITICAL NOTES 3）。

示例

用户请求	模式	要阅读的参考文档
"SkillsTestWarehouse 中的 nyctlc 表有多少行？"	consumption	references/consumption.md
"在仓库中创建 dbo.Orders，包含 OrderId、CustomerId 和 OrderDate。"	authoring	references/authoring.md
"使用 COPY INTO 将 OneLake 中的 Files/nyctlc_sample.csv 加载到仓库。"	authoring	references/authoring.md
"哪些查询最慢，哪些表应该进行聚簇？"	operations	references/operations.md
"显示 lakehouse SQL 终结点中每个供应商的平均行程距离。"	consumption	references/consumption.md