sqldw-operations-cli

遥测 — 强制要求。 每个 api.fabric.microsoft.com 调用都必须携带 x-ms-fabric-skill: sqldw-operations-cli（az rest：--headers "x-ms-fabric-skill=sqldw-operations-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 DW 性能与诊断 — CLI 技能

此技能通过 fabric-sqlendpoint-execute_query MCP 工具和内置的 queryinsights 视图，为 Microsoft Fabric Data Warehouse 提供性能分析、深入诊断和优化指导。所有查询均为只读。

前提条件

有关通过 az rest 发现工作区/项的信息，请参阅 COMMON-CLI.md § Fabric Control-Plane API via az rest。有关旧版 sqlcmd 参考（仅作后备方案），请参阅 COMMON-CLI.md § SQL / TDS Data-Plane Access。

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

监控专属要求：

• 工作区角色：目标工作区中的管理员或成员（使用 queryinsights 视图所必需）
• 必须存在数据仓库，且近期有查询活动（queryinsights 视图保留 30 天数据；数据最多延迟 15 分钟显示）

目录

任务	参考	备注
在 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 轮询和速率限制模式
容量管理	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 辅助工具
SQL / TDS 数据平面访问	COMMON-CLI.md § SQL / TDS 数据平面访问	旧版 sqlcmd 参考（MCP 为首选 — 参见工具栈）
注意事项和故障排除（CLI 专属）	COMMON-CLI.md § 注意事项和故障排除（CLI 专属）	az rest 受众、Shell 转义、令牌过期
快速参考	COMMON-CLI.md § 快速参考	az rest 模板 + 令牌受众/工具矩阵
连接基础知识	SQLDW-CONSUMPTION-CORE.md § 连接基础知识	TDS、端口 1433、仅限 Entra、不支持 MARS
监控和诊断	SQLDW-CONSUMPTION-CORE.md § 监控和诊断	查询标签；DMV（实时）+ queryinsights.*（30 天历史记录）
性能：最佳实践和故障排除	SQLDW-CONSUMPTION-CORE.md § 性能：最佳实践和故障排除	统计信息、缓存、聚簇、查询提示
注意事项和故障排除（消耗）	SQLDW-CONSUMPTION-CORE.md § 注意事项和故障排除参考	18 个编号问题，包含原因和解决方法
数据引入（仅限 DW）	SQLDW-AUTHORING-CORE.md § 数据引入（仅限 DW）	COPY INTO、OPENROWSET、方法比较
查询参考	query-reference.md	所有分析对应的 T-SQL 查询、参数和示例输出
组合方案	COMMON-CLI.md § 组合方案
项目类型功能矩阵	SQLDW-CONSUMPTION-CORE.md § 项目类型功能矩阵	仅限仓库 — SQLEP 不支持 queryinsights
先决条件	SKILL.md § 先决条件	工具、身份验证、工作区角色
工具栈	SKILL.md § 工具栈
连接	SKILL.md § 连接
性能分析	SKILL.md § 性能分析	长时间运行的查询、资源消耗者、用户洞察、基线
深度诊断	SKILL.md § 深度诊断	压力时段、缓存预热、群集键
Fabric DW 约束	SKILL.md § Fabric DW 约束	绝不推荐不受支持的功能
最佳实践	SKILL.md § 最佳实践	监控专项指南
Agent 工作流	SKILL.md § Agent 工作流	常见调查模式
注意事项、规则和故障排除	SKILL.md § 注意事项、规则和故障排除	必须执行 / 避免 / 优先选择检查清单
示例	SKILL.md § 示例	提示词/响应对

---

工具栈

安装和设置请参阅先决条件。

工具	角色
fabric-sqlendpoint-execute_query MCP 工具	主要工具：对 Fabric SQL 端点执行监控 T-SQL 查询。身份验证由 MCP 协议处理。
az CLI	获取令牌，通过 Fabric REST 发现工作区和项
jq	解析来自 az rest 的 JSON

重要——MCP 与 sqlcmd： 此技能使用 fabric-sqlendpoint-execute_query MCP 工具执行所有 T-SQL。执行查询时，请勿使用 COMMON-CLI SQL/TDS/sqlcmd 章节。

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

1. 确认工具列表中有 fabric-sqlendpoint-execute_query 工具。此工具由 fabric-sqlendpoint MCP 服务提供，可通过安装 Fabric skills 插件（面向最终用户的方式）或使用此仓库的 .mcp.json 进行注册；其他 MCP 客户端也可以通过自己的配置注册此工具。
2. 如果找不到匹配的工具，用户必须注册 Fabric SQL Endpoint MCP 服务。
   • 全局 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)	包含目标 Warehouse 的工作区 GUID
itemId	string (UUID)	Warehouse 项的 GUID
query	string	T-SQL 查询文本（单个批次，不含 GO 分隔符）

**返回值：**CSV 资源（RFC 4180），包含表格结果和元数据文本。

**限制：**最多 10,000 行 | 超时 300s | 速率限制为 20 req/min (观测到的默认值，并非有文档记录的约定——服务可能会调整；请根据实时 429、超时或截断响应进行确认)

---

连接

查找 workspaceId 和 itemId

调用 fabric-sqlendpoint-execute_query 需要工作区 GUID 和 Warehouse 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

执行监控查询

fabric-sqlendpoint-execute_query(
  workspaceId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  itemId: "11111111-2222-3333-4444-555555555555",
  query: "SELECT TOP 5 * FROM queryinsights.long_running_queries ORDER BY last_run_total_elapsed_time_ms DESC"
)

无需额外设置连接——身份验证由 MCP 协议透明处理。

---

性能分析

所有 SQL 查询、参数、返回字段和响应格式均列于 query-reference.md。

长时间运行查询摘要

从 queryinsights.long_running_queries 中查找最慢的查询。SQL 和格式说明请参阅 query-reference.md § 长时间运行查询摘要。

主要资源消耗者

从 queryinsights.exec_requests_history 中查找 CPU 和存储消耗较大的查询。SQL、阈值和格式说明请参阅 query-reference.md § 主要资源消耗者。

建议阈值：

• 远程扫描 > 1,000 MB → 检查数据布局，并考虑使用聚簇
• CPU > 5,000,000 ms → 检查查询逻辑
• 耗时 > 300,000 ms → 检查联接、筛选器和统计信息
• 参考：性能指南

主要用户洞察

分析用户活动和查询模式。SQL 和分类逻辑请参阅 query-reference.md § 主要用户洞察。

比较近期数据与基线

通过将近期时间窗口与历史基线进行比较，检测性能回退。SQL 和格式说明请参阅 query-reference.md § 比较近期数据与基线。

最近的查询

检索最近执行的查询。SQL 见 query-reference.md § 最近的查询。

搜索查询模式

按表名、列或关键词搜索历史查询模式。SQL 见 query-reference.md § 搜索查询模式。

---

深入诊断

所有诊断 SQL 查询都在 query-reference.md 中。

分析长时间运行的查询计划

SQL 见 query-reference.md § 长时间运行查询分析。

分析指南 — 检查慢查询时，请关注：

• data_scanned_remote_storage_mb 较高 → 数据布局问题（运行 OPTIMIZE，考虑聚类）
• allocated_cpu_time_ms 相对于运行时间较高 → 受 CPU 限制（简化联接，减少列数）
• 运行时间较长但 CPU 使用率较低 → 正在等待资源（检查是否处于资源压力时段）

分析压力时段查询

使用 queryinsights.sql_pool_insights 识别 SQL 池压力事件，并找出这些时段内运行的最繁重查询。两步 SQL 见 query-reference.md § 压力时段分析。

用法： 第 1 步会返回包含 window_start 和 window_end 时间戳的压力时段。将这些实际时间戳值替换到第 2 步的 WHERE 子句中，以查找时间重叠的查询。

全局建议 — 基于汇总压力分析：

• 如果 SELECT 池压力较大 → 工作负载以读取为主，建议使用缓存并精简列
• 如果 NONSELECT 池压力较大 → 工作负载以写入为主，建议分批处理并使用 COPY INTO
• 如果总压力超过 60 分钟 → 建议扩展容量或错开工作负载

分析查询缓存热度

SQL 见 query-reference.md § 缓存热度分析。

分类逻辑 — 对每次执行，计算 total_mb = remote + memory + disk：

• result_cache_hit = 1 → 已缓存
• remote_mb / total_mb > 0.8 → 冷（超过 80% 来自远程存储）
• (memory_mb + disk_mb) / total_mb > 0.8 → 热（超过 80% 来自缓存）

建议：

• 冷运行超过 50% → 启用结果集缓存：ALTER DATABASE SET RESULT_SET_CACHING ON;
• 始终为冷的模式 → 检查是否使用了 GETDATE()/GETUTCDATE() 或会使缓存键失效的易变函数

推荐聚类键

SQL 见 query-reference.md § 聚类键建议。

关键规则：

• 只有 WHERE 谓词能从聚类中受益 — 等值 JOIN ON 条件不能
• 优先选择基数中等偏高的列（不同值较多）
• 最多使用 4 个聚类列
• 使用 WITH (CLUSTER BY (...)) 的 CTAS — 不支持 ALTER TABLE

应用聚类 — 关于 CTAS 创建、sp_rename 表交换和验证 SQL，请参阅 query-reference.md § 聚类键建议。

注意： Fabric 不支持 ALTER TABLE SET DATA_CLUSTERING_KEY 或 RENAME OBJECT。表交换时，请始终使用带有 WITH (CLUSTER BY (...)) 的 CTAS 和 sp_rename。

---

Fabric DW 限制

绝不要推荐 Fabric Data Warehouse 不支持的功能。 提出优化建议前，务必先查阅此列表。

不要推荐	原因	改为推荐
非聚集索引	不支持	V-Order、列裁剪、谓词下推
实体化视图	不支持	标准视图或结果集缓存
索引提示（FORCESEEK/FORCESCAN）	不支持	简化查询结构
多列统计信息	不支持	对键列创建单列统计信息
ALTER TABLE SET DATA_CLUSTERING_KEY	不支持	使用 WITH (CLUSTER BY (...)) 创建 CTAS
RENAME OBJECT	不支持	EXEC sp_rename 'schema.old', 'new'
更改隔离级别	仅支持快照隔离	Fabric 仅使用快照隔离
CREATE USER	不支持	通过 Fabric 工作区管理用户
触发器	不支持	应用程序逻辑或 Fabric 管道
递归 CTE	不支持	采用迭代方法
“启用 Query Insights”设置	Query Insights 始终处于开启状态——没有此设置	如果访问被拒绝，用户需要工作区管理员或成员角色

---

Agent 工作流

工作流 1：“为什么我的仓库运行缓慢？”

1. 检查压力事件 → 运行压力时间窗口分析查询（最近 24h）
2. 查找资源消耗最大的查询 → 运行资源消耗排名查询（最近 1h）
3. 分析慢速查询 → 运行长时间运行的查询分析
4. 检查缓存行为 → 运行缓存热度分析（最近 24h）
5. 建议聚类 → 运行聚类键建议查询

工作流 2：“性能是否下降了？”

1. 与基线进行比较 → 运行近期与基线对比（1h 与 7 天）
2. 识别新出现的慢速查询 → 运行长时间运行的查询摘要（前 5 项）
3. 检查用户模式 → 运行用户洞察排名查询（最近 24h）

工作流 3：“优化我的仓库”

1. 查看最佳实践 → 参阅 SQLDW-CONSUMPTION-CORE.md § 性能：最佳实践和故障排除
2. 查找优化目标 → 运行资源消耗排名查询（最近 24h）
3. 建议聚类 → 运行聚类键建议查询
4. 分析冷启动查询 → 运行缓存热度分析

工作流 4：“大家都在运行什么？”

1. 近期活动 → 运行近期查询（前 10 项）
2. 用户模式 → 运行用户洞察排名查询（最近 24h）
3. 搜索特定模式 → 使用搜索词运行查询模式搜索

---

最佳实践

如需全面了解 Fabric DW 最佳实践，请参阅 SQLDW-CONSUMPTION-CORE.md § 性能：最佳实践和故障排除 和 Fabric 指南。

监控专属最佳实践：

• 先全面查看，再深入排查 — 先查看长时间运行的查询摘要和基线比较，再进行深入诊断
• 使用压力时间窗口分析进行根本原因分析，而不是猜测瓶颈所在
• 使用 OPTION (LABEL = 'AGENTCLI_MONITOR_...') 标记所有 Agent 查询，以便在 Query Insights 中追踪
• 聚类键优先选择中高基数列——低基数列对跳过文件的帮助有限
• 使用 WHERE 谓词识别聚类键候选列——相等条件 JOIN ON 不会受益于聚类
• 使用 CTAS 后，务必查询 sys.index_columns.data_clustering_ordinal 验证聚类情况
• 得出查询本身运行缓慢的结论前，先检查冷缓存与热缓存的差异——首次执行可能是冷启动
• 调整时间窗口（DATEADD 参数），以符合用户的调查范围——不要默认使用任意时间窗口

---

注意事项、规则与故障排除

有关通用 CLI 注意事项（连接、身份验证、Shell 转义）：请参阅 COMMON-CLI.md § 注意事项与故障排除。 有关 T-SQL/平台注意事项：请参阅 SQLDW-CONSUMPTION-CORE.md § 注意事项与故障排除参考。

必须执行

• 在推荐优化方案前，务必先查看 Fabric DW 限制
• 推荐聚簇时，指导用户使用 WITH (CLUSTER BY (...)) 执行 CTAS，而不是使用 ALTER TABLE
• 报告实际查询输出，不要捏造或假设结果
• 使用 OPTION (LABEL = 'AGENTCLI_MONITOR_...') 为查询添加标签，以便追踪 Query Insights
• 首次操作前，确认 fabric-sqlendpoint-execute_query MCP 工具可用

优先做法

• 先运行高级别查询（长时间运行摘要、基线对比），再深入诊断
• 使用压力时段分析进行根因分析，而不是猜测瓶颈
• 组合使用 Agentic 工作流 中的多个查询，进行全面调查
• 根据用户的要求调整时间窗口（DATEADD 参数）
• 合并相关诊断查询，减少调用次数以遵守速率限制

避免

• 推荐 Fabric 不支持的功能（非聚簇索引、物化视图、索引提示、触发器）
• 建议“启用”或“打开” Query Insights——queryinsights 视图始终可用；权限错误表示工作区角色权限不足（需要 Admin 或 Member）
• 未确认 workspaceId 和 itemId 就运行监控查询
• 未运行诊断查询就猜测性能问题的根因
• 在监控查询中使用 SELECT *——始终选择具体列
• 在查询中使用 GO 分隔符或 sqlcmd 元命令（MCP 工具仅接受单个批次）
• 运行没有 TOP N 的无界查询——行数上限为 10,000

故障排除（监控专项）

有关通用连接/身份验证故障排除，请参阅 COMMON-CLI.md § 注意事项与故障排除。

症状	原因	解决方法
Invalid object name 'queryinsights...'	新建仓库不足 2 min	等待约 2 分钟
queryinsights.* 权限错误	工作区角色权限不足	需要 Admin 或 Member 角色
queryinsights 视图中没有数据	最近没有查询活动，或存在 < 15 min 的延迟	查询完成后等待 15 min
没有行，但数据存在	RLS 筛选	检查 USER_NAME()，验证 RLS 策略
fabric-sqlendpoint-execute_query 工具不可用	MCP 服务未注册	用户必须添加 Fabric SQL Endpoint MCP 服务
HTTP 429 速率限制	1 min 内调用次数过多	等待 60s；合并查询
查询超时（300s）	诊断过于复杂	使用更短的 DATEADD 时间范围缩小查询窗口

---

示例

查找慢查询

用户：“我的仓库中哪些查询最慢？”

**Agent：**通过 fabric-sqlendpoint-execute_query 运行长时间运行查询摘要：

fabric-sqlendpoint-execute_query(workspaceId, itemId,
  "SELECT TOP 5
      left(last_run_command, 80) AS query_preview,
      number_of_runs,
      last_run_total_elapsed_time_ms,
      median_total_elapsed_time_ms
   FROM queryinsights.long_running_queries
   ORDER BY median_total_elapsed_time_ms DESC")

最慢的 5 个查询是：

1. SELECT * FROM FactSales JOIN DimCustomer... — 运行了 12 次，最近一次耗时 45,200 ms（中位数为 38,500 ms）
2. SELECT region, SUM(amount)... — 运行了 8 次，最近一次耗时 32,100 ms（中位数为 29,000 ms） ...

诊断性能下降

用户：“我的仓库是不是比上周慢了？”

**Agent：**运行基线对比查询并展示：

性能对比（最近 1h 与 7-day 基线）：

• 耗时：平均 2,450 ms → 平均 4,100 ms（+67.3%）
• CPU 消耗：1,200 ms → 2,800 ms（+133.3%）
• 扫描数据量：450 MB → 480 MB（+6.7%）

检测到显著性能退化。接下来我会检查压力事件并分析资源消耗最高的查询……

然后继续运行压力时段和资源使用者查询。

获取聚簇建议

用户：“应该对哪些表进行聚簇，以及使用哪些列？”

**Agent：**运行聚簇键推荐查询并展示：

推荐的聚簇键：

表	推荐列	行数	扫描总量（MB）
dbo.FactSales	SaleDate、Region	50M	12,500 MB
dbo.FactInventory	ProductID、WarehouseID	12M	3,200 MB

要应用聚簇，请使用 CTAS：

CREATE TABLE dbo.FactSales_clustered
WITH (CLUSTER BY (SaleDate, Region))
AS SELECT * FROM dbo.FactSales;