sqldb-cli

遥测 — 必须执行。 每次调用 api.fabric.microsoft.com 都必须携带 x-ms-fabric-skill: sqldb-cli（az rest：--headers "x-ms-fabric-skill=sqldb-cli"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项，但仍须添加。

重要说明

1. 要通过工作区名称查找工作区详细信息（包括其 ID）：先列出所有工作区，然后使用 JMESPath 进行筛选
2. 要通过工作区 ID、项类型和项名称查找项的详细信息（包括其 ID）：先列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选
3. 技能消歧：仅对 Fabric SQL 数据库项（OLTP、SQL Server 引擎）使用 sqldb-cli。Warehouse、Lakehouse SQL endpoint 或 Mirrored Database 应使用 sqldw-cli；笔记本单元格应使用 spark-cli。

Fabric SQL 数据库（OLTP）—— CLI 技能

此技能负责 Fabric SQL 数据库：T-SQL 架构编写、只读查询和 OLTP 性能诊断。

这是一个模式分派器，不包含任何操作步骤。请从下表中选择与请求匹配的模式，然后在执行任何命令之前，使用文件读取工具从头到尾阅读对应的 references/<mode>.md 文件。该文件包含端点、负载格式、模板和注意事项；不先阅读就执行操作会导致负载和结果错误。

模式选择

模式	适用请求	示例触发词	先阅读此文件
authoring	在现有数据库中创建或更改架构和数据：表、约束、索引、向量列、存储过程、dacpac 部署、INSERT/UPDATE/DELETE/MERGE；仅当请求要求创建一个新数据库时，才创建 SQL 数据库项本身	创建 sqldb 表、sqldb 外键、dacpac 部署、修改 sqldb 架构、在 fabric 中创建 sql 数据库	references/authoring.md
consumption	通过 sqlcmd 执行只读 T-SQL：SELECT、目录探索、向量相似度搜索、时态查询	sqldb sys.tables、sqldb 向量相似度、时态 sqldb、查询 sql 数据库	references/consumption.md
operations	诊断 OLTP 性能：Query Store、被阻塞的会话、性能退化的执行计划、等待统计信息	sqldb query store、sql 数据库被阻塞的会话、sqldb 性能退化的执行计划、sqldb 慢查询	references/operations.md

模式边界规则

consumption 仅执行只读 T-SQL。任何 DDL 或 DML 都属于 authoring 模式；任何性能调查都属于 operations 模式。请告知模式切换，阅读对应参考文件，然后再执行操作。

在 authoring 模式中，除非请求要求创建数据库，否则请求中提到的数据库均已存在：解析该数据库并直接执行 T-SQL。不要将创建 SQL 数据库项作为架构或数据操作的前置条件。

如果请求确实涉及多个模式，请逐一处理，并在开始每个部分之前阅读对应的参考文件。如果阅读此表后仍无法确定模式，请提出一个简短的澄清问题，不要猜测。

终端写入——绝不能跳过的步骤

阅读参考文档并规划更改，并不代表任务已完成。每种修改模式都以一次更改状态的调用结束。如果你没有发出该调用，任何内容都没有持久化——请明确说明这一点，不要声称任务已成功。

模式	终端写入
authoring	使用 sqlcmd -Q/-i 对数据库执行 T-SQL——必须实际运行 CREATE TABLE、ALTER、INSERT INTO、UPDATE、DELETE 或 MERGE INTO 语句。编写 DDL 或 DML 并展示给用户，不会产生任何更改。只有在请求新建数据库时，终端写入才改为 POST /v1/workspaces/{ws}/sqlDatabases，并轮询直至完成。
consumption	无——此模式严格只读
operations	诊断性读取本身无需写入。参考文档所述的唯一例外是：调查间歇性阻塞时，可以创建扩展事件会话（CREATE EVENT SESSION ... ON DATABASE，使用 ring_buffer 目标），然后终端步骤必须将其删除——绝不能让会话继续运行。

报告任务完成前，请确认终端调用已成功返回；如果参考文档要求读取回查，请读取产物以证明更改已生效。

通用要点（所有模式）

先解析工作区和项；每种模式都依赖它们。

任务	参考文档	备注
在 Fabric 中查找工作区和项	COMMON-CLI.md	必读——解析任何工作区或项 ID 前必须先阅读
Fabric 拓扑和关键概念	COMMON-CORE.md	项类型、工作区、容量
环境 URL	COMMON-CORE.md	主权云／非公共云主机
身份验证和令牌获取	COMMON-CORE.md	受众错误会导致 401；遇到任何身份验证问题前请先阅读
身份验证操作指南	COMMON-CLI.md	az login 流程和令牌获取
核心控制平面 REST API	COMMON-CORE.md	分页、LRO 轮询、速率限制
常见问题和故障排除	COMMON-CLI.md	az rest 受众、Shell 转义、令牌过期

规则

必须

• 在执行任何操作前，先从上表中准确选择一种模式。
• 在该模式的第一个命令之前，将 references/<mode>.md 作为第一个工具调用从头到尾阅读一遍。只读一次，且一次性完整读取：不要重新打开，不要再次 grep，也不要分段浏览。你已经拥有该文件。
• 对加载的所有其他文件也遵循只读一次的要求，包括嵌套的 references/<mode>/*.md 子参考文件和共享的 common/*.md 文件：只打开实际需要的文件，每个文件从头到尾读取一次，绝不 grep 或重新打开已加载的文件。
• 通过列出并筛选来解析工作区和项 ID，绝不能猜 GUID。
• 如果请求跨越模式边界，必须明确宣布切换模式。
• 将参考文档视为操作指南，而非交付成果。阅读后，针对实时工作区运行其中记载的命令，并报告真实结果。只引用参考文档内容而不执行命令，不能算作答复请求。

优先

• 选择能满足请求的最精简模式。
• 只阅读一种模式的参考文档。只有在请求确实跨越多个模式时才加载第二份，并在此之前说明原因。
• 在首次回复中说明所选模式，以便用户纠正。

避免

• 仅凭此调度器采取行动——它有意省略了操作细节。
• 用参考资料的摘要作答，而不是执行其中的操作。
• 重新读取或重新搜索已加载的参考资料；这会耗费轮次和令牌。
• 修改 consumption 或 operations 中的架构或数据——两者都只执行读取。它们唯一可以执行的写入操作，是 operations 在调查间歇性阻塞时创建并随后删除 Extended Events 会话。
• 为此类工作加载其他技能（参见 CRITICAL NOTES 3）。

示例

用户请求	模式	要读取的参考资料
“在 Fabric SQL 数据库中创建一个带有指向 Customers 外键的 Orders 表。”	authoring	references/authoring.md
“在此工作区中创建一个名为 sales_oltp 的新 SQL 数据库。”	authoring	references/authoring.md
“在 SQL 数据库中查找与此向量最近的 5 个嵌入。”	consumption	references/consumption.md
“根据 Query Store，过去一天有哪些查询出现了性能退化？”	operations	references/operations.md