semantic-model-consumption

检查更新 — 每个会话仅执行一次（必须） 首次在一个会话中使用此技能时，请先运行 check-updates 技能，再继续。

• GitHub Copilot CLI / VS Code：调用 check-updates 技能。
• Claude Code / Cowork / Cursor / Windsurf / Codex：比较本地与远程 package.json 的版本。
• 如果本会话之前已执行过检查，则跳过。

重要说明

1. 要根据工作区名称查找工作区详情（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 要根据工作区 ID、项目类型和项目名称查找项目详情（包括其 ID）：列出该工作区中此类型的所有项目，然后使用 JMESPath 进行筛选

Power BI 语义模型使用

目录

任务	参考	说明
在 Fabric 中查找工作区和项目	COMMON-CLI.md § 在 Fabric 中查找工作区和项目	必读 — 请先阅读链接内容 [用于按名称查找工作区 ID，或按名称、项目类型和工作区 ID 查找项目 ID]
Fabric 拓扑和关键概念	COMMON-CORE.md § Fabric 拓扑和关键概念	层级结构；在 Fabric 中查找内容
环境 URL	COMMON-CORE.md § 环境 URL	生产环境（公有云）
身份验证和令牌获取	COMMON-CORE.md § 身份验证和令牌获取	受众错误会导致 401；涵盖令牌受众、委托权限与应用权限、OAuth 流程、身份类型和 Entra 应用注册
核心控制平面 REST API	COMMON-CORE.md § 核心控制平面 REST API	包括工作区/项目 CRUD、按名称解析、分页、LRO 轮询和速率限制模式
OneLake 数据访问	COMMON-CORE.md § OneLake 数据访问	需要 storage.azure.com 令牌，而非 Fabric 令牌；涵盖 URL 结构、与 ADLS Gen2 的一致性以及快捷方式
作业执行	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 数据平面访问	COMMON-CLI.md § SQL / TDS 数据平面访问	使用 sqlcmd (Go) 连接、查询、导出 CSV、服务主体身份验证以及发现连接参数
作业执行（CLI）	COMMON-CLI.md § 作业执行（CLI）	运行笔记本/管道、刷新语义模型、检查/取消作业
OneLake 快捷方式	COMMON-CLI.md § OneLake 快捷方式	创建快捷方式；列出快捷方式；删除快捷方式
容量管理（CLI）	COMMON-CLI.md § 容量管理（CLI）	列出容量；将工作区分配给容量
组合操作指南	COMMON-CLI.md § 组合操作指南	端到端的工作区→湖屋→文件、SQL 终结点→查询和笔记本执行操作指南
注意事项和故障排除（CLI 专用）	COMMON-CLI.md § 注意事项和故障排除（CLI 专用）
快速参考	COMMON-CLI.md § 快速参考	az rest 模板；令牌受众 ↔ CLI 工具矩阵
先决条件	SKILL.md § 先决条件
必须/优先/避免	SKILL.md § 必须/优先/避免	只读语义模型用法的防护规则。必须执行；优先采用；避免
元数据发现	SKILL.md § 元数据发现	INFO.VIEW.* 和 INFO.* 函数。
推荐的发现顺序	SKILL.md § 推荐的发现顺序	元数据探索的首选顺序
常用 INFO 函数	SKILL.md § 常用 INFO 函数	用于初步发现的高频函数列表
完整 INFO 函数目录（动态）	discovery-queries.md § 完整 INFO 函数目录（动态）
元数据对象 → INFO 函数映射	SKILL.md § 元数据对象 → INFO 函数映射	内嵌的映射，用于以对象为中心的发现
查询执行	SKILL.md § 查询执行	ExecuteQuery 的用法形式
故障排除	SKILL.md § 故障排除	解决常见的执行和元数据问题
示例	SKILL.md § 示例	元数据查询示例；数据查询示例
范围估算查询	discovery-queries.md § 范围估算查询
INFO 输出列	discovery-queries.md § INFO 输出列	INFO.VIEW.（初步元数据发现首选）；关键 INFO.（深层元数据/诊断）
缩小结果范围（投影 + 筛选）	discovery-queries.md § 缩小结果范围（投影 + 筛选）
深层元数据查询	discovery-queries.md § 深层元数据查询
依赖项发现	discovery-queries.md § 依赖项发现	DAX 查询的依赖项行集；限定到度量值的依赖项行；反向依赖项（引用某度量值的内容）

前提条件

• COMMON-CORE.md — Fabric 概念、身份验证和控制平面 API 背景。
• COMMON-CLI.md — 面向 CLI 的发现方式以及令牌和受众模式。

必须做 / 优先做 / 避免做

必须做

• 调用 MCP 工具进行发现和执行 — 使用 DiscoverArtifacts 查找语义模型 GUID，并使用 ExecuteQuery 执行 DAX 查询。这些是 MCP 工具调用，不是 shell 命令。不要使用 az rest、Get-Command 或 PowerShell 脚本来发现或调用这些工具。
• 保持此技能为只读：仅进行元数据发现和分析型 DAX 查询。
• 将 DAX 数据查询和 INFO.VIEW.* 视为所有具有语义模型读取权限的用户都可使用；假设其他 INFO.* 函数可能需要更高权限。
• 动态解析工作区和语义模型项的身份；不要对 ID 进行硬编码。
• 编写数据查询前，使用 DAX INFO.VIEW.* / INFO.* 发现元数据。

优先做

• 尽早验证语义模型范围（artifactId），再迭代优化查询。
• 逐步发现语义模型架构：使用经过筛选和投影的 INFO.VIEW.* / INFO.* 调用（例如，SELECTCOLUMNS + FILTER），仅获取与当前任务直接相关的信息，而不是一开始就检索完整架构。请参阅 discovery-queries.md § 缩小结果范围（投影 + 筛选）。
• 保持指导内容与提供方无关，以降低工具端点迁移的风险。

避免做

• 在此技能中执行模型更改操作。

推荐的发现顺序

1. 运行 discovery-queries.md § 范围估算查询，在深入发现前估算元数据范围（表、列、度量值和关系的数量）。
2. 从 INFO.VIEW.TABLES() 开始，快速盘点表。
3. 扩展到 INFO.VIEW.COLUMNS() 和 INFO.VIEW.MEASURES()，了解语义细节。
4. 使用 INFO.VIEW.RELATIONSHIPS() 验证联接和筛选行为。
5. 使用 discovery-queries.md 中的完整查询目录了解更深入的模式。

常用 INFO 函数

• INFO.VIEW.TABLES
• INFO.VIEW.MEASURES
• INFO.VIEW.COLUMNS
• INFO.VIEW.RELATIONSHIPS
• INFO.PARTITIONS
• INFO.MODEL
• INFO.STORAGETABLECOLUMNSEGMENTS
• INFO.DEPENDENCIES
• INFO.EXPRESSIONS
• INFO.ROLES
• INFO.STORAGETABLECOLUMNS
• INFO.CALCULATIONGROUPS
• INFO.CALCULATIONITEMS
• INFO.CULTURES
• INFO.OBJECTTRANSLATIONS
• INFO.USERDEFINEDFUNCTIONS
• INFO.REFRESHPOLICIES
• INFO.ATTRIBUTEHIERARCHYSTORAGES
• INFO.COLUMNPARTITIONSTORAGES
• INFO.COLUMNSTORAGES
• INFO.DICTIONARYSTORAGES
• INFO.HIERARCHYSTORAGES
• INFO.PARTITIONSTORAGES
• INFO.RELATIONSHIPINDEXSTORAGES
• INFO.RELATIONSHIPSTORAGES
• INFO.SEGMENTMAPSTORAGES
• INFO.SEGMENTSTORAGES
• INFO.STORAGEFOLDERS
• INFO.STORAGEFILES
• INFO.TABLESTORAGES
• INFO.GENERALSEGMENTMAPSEGMENTMETADATASTORAGES
• INFO.DELTATABLEMETADATASTORAGES
• INFO.PARQUETFILESTORAGES
• INFO.STORAGETABLES

元数据对象 → INFO 函数映射

元数据对象	主要 INFO 函数
模型	INFO.MODEL
表	INFO.VIEW.TABLES
列	INFO.VIEW.COLUMNS、INFO.GROUPBYCOLUMNS、INFO.RELATEDCOLUMNDETAILS
度量值	INFO.VIEW.MEASURES、INFO.FORMATSTRINGDEFINITIONS、INFO.DETAILROWSDEFINITIONS
关系	INFO.VIEW.RELATIONSHIPS
分区	INFO.PARTITIONS、INFO.EXPRESSIONS、INFO.QUERYGROUPS、INFO.REFRESHPOLICIES、INFO.DATACOVERAGEDEFINITIONS
安全角色和权限	INFO.ROLES、INFO.TABLEPERMISSIONS、INFO.COLUMNPERMISSIONS
层次结构	INFO.HIERARCHIES、INFO.LEVELS、INFO.ATTRIBUTEHIERARCHIES、INFO.VARIATIONS
计算组/项	INFO.CALCULATIONGROUPS、INFO.CALCULATIONITEMS、INFO.CALCULATIONEXPRESSIONS
透视	INFO.PERSPECTIVES、INFO.PERSPECTIVETABLES、INFO.PERSPECTIVECOLUMNS、INFO.PERSPECTIVEHIERARCHIES、INFO.PERSPECTIVEMEASURES
日历	INFO.CALENDARS、INFO.CALENDARCOLUMNGROUPS、INFO.CALENDARCOLUMNREFERENCES
区域性	INFO.CULTURES
对象翻译	INFO.OBJECTTRANSLATIONS
函数	INFO.USERDEFINEDFUNCTIONS
依赖项/沿袭	INFO.DEPENDENCIES、INFO.CHANGEDPROPERTIES、INFO.EXCLUDEDARTIFACTS
存储内部信息/大小	INFO.STORAGEFOLDERS、INFO.STORAGEFILES、INFO.TABLESTORAGES、INFO.COLUMNSTORAGES、INFO.PARTITIONSTORAGES、INFO.SEGMENTMAPSTORAGES、INFO.DICTIONARYSTORAGES、INFO.COLUMNPARTITIONSTORAGES、INFO.SEGMENTSTORAGES、INFO.RELATIONSHIPSTORAGES、INFO.RELATIONSHIPINDEXSTORAGES、INFO.ATTRIBUTEHIERARCHYSTORAGES、INFO.HIERARCHYSTORAGES、INFO.GENERALSEGMENTMAPSEGMENTMETADATASTORAGES、INFO.DELTATABLEMETADATASTORAGES、INFO.PARQUETFILESTORAGES、INFO.STORAGETABLES、INFO.STORAGETABLECOLUMNS、INFO.STORAGETABLECOLUMNSEGMENTS

查询执行

直接使用 FabricIQ MCP server 工具——以 MCP 工具调用的方式调用：

参数	描述
artifactId	目标语义模型的 GUID
daxQueries	包含 1–4 个 DAX 查询的数组（每个查询必须包含单个 EVALUATE 语句）
maxRows	可选。默认值为 250，每个查询最多 1,000 行

如何查找 artifact ID

1. 首选：调用 DiscoverArtifacts（MCP 工具），将 searchQuery 设为模型名称，并将 artifactTypes: ["SemanticModel"] 作为参数。
2. 仅在 MCP 发现功能不可用时使用备用方法：通过 Fabric REST（az rest）解析——列出工作区中类型为 SemanticModel 的项，并按 displayName 筛选。

执行查询

直接调用 ExecuteQuery MCP 工具：

ExecuteQuery(
  artifactId = "<SEMANTIC_MODEL_GUID>",
  daxQueries = ["EVALUATE SUMMARIZECOLUMNS(...)"]
)

先获取架构

在编写 DAX 之前，调用 GetSemanticModelSchema(artifactId = "<SEMANTIC_MODEL_GUID>") 获取表、列和度量值定义。

故障排查

• MCP 服务中没有 ExecuteQuery 功能
  • 问题： 活跃工具列表中没有 ExecuteQuery，因此无法开始执行查询。
  • 原因： FabricIQ MCP 服务尚未注册或加载，或者当前客户端会话中的工具元数据已过时。
  • 解决方法： 检查活跃 MCP 服务和工具清单，并确认其中提供了 ExecuteQuery。
• 高级 INFO 函数返回权限错误
  • 问题： 对 INFO.* 的查询因授权或权限相关错误而失败。
  • 原因： 许多 INFO.* 函数需要比标准读取权限更高的语义模型权限。
  • 解决方法： 从面向读取的发现函数 INFO.VIEW.* 入手。
• 元数据输出量过大，不利于聚焦分析
  • 问题： 返回完整的元数据行集会引入过多属性，并占用大量工作上下文。
  • 原因： 不加限制的 INFO.VIEW.* 和 INFO.* 查询会返回大量对象和属性信息，这些信息对于当前任务往往没有必要。
  • 解决方法： 使用 discovery-queries.md § 范围估算查询 中的范围估算查询来估算范围并检查输出架构，然后按照 discovery-queries.md § 缩小结果范围（投影 + 筛选） 中的示例，通过投影和筛选来缩小结果范围。
• 不要使用 INFO DAX 函数获取角色成员资格
  • 问题： INFO.ROLEMEMBERSHIPS() 返回空结果或不完整的结果。
  • 原因： 角色成员是在部署后于服务级别（Entra ID）分配的，而非在模型定义中设置，因此 DAX INFO 函数无法可靠地提供这些信息。
  • 解决方法： 请参阅管理角色成员资格文档，了解当前的角色成员资格管理指南。

示例

完整的查询目录（包括依赖模式）请参阅 discovery-queries.md。

元数据查询示例

EVALUATE
INFO.VIEW.TABLES()
ORDER BY [Name]

数据查询示例

DEFINE
MEASURE 'Sales'[Total Sales] = SUM('Sales'[Amount])
EVALUATE
SUMMARIZECOLUMNS(
    'Customer'[Customer Name],
    "Total Sales", [Total Sales]
)
ORDER BY [Total Sales] DESC