用途
为仪表盘获取可信的数据查询结果：查询 Microsoft Fabric 和 Power BI 语义模型（DAX），或查询 Fabric SQL 端点、仓库、湖仓（T-SQL）。重点在于找到正确的度量值并合理切片，避免自行重写 DAX 公式。
主要能力
- 模型发现：通过 list_models、find_items（语义模型类型）、resolve_item 定位模型，并在多个相似副本（如开发、测试、生产）中与用户确认。
- 架构读取：用 get_model_schema 读取度量值、列、关系，以及描述、显示文件夹、格式字符串和表达式。
- 度量值复用：直接引用模型度量值 [Measure]，优先使用模型中已有的变体；无变体时用 CALCULATE 等对现有度量值做偏移或过滤。避免对原始列重新聚合、用 DEFINE MEASURE 重写业务逻辑、在仪表盘端计算比率或对率值做平均/求和。
- 需要选择的度量值处理：识别依赖 HASONEVALUE/SELECTEDVALUE 的度量值及无关系的选择表，通过 TREATAS 等以筛选参数传入选择，并在仪表盘中显示该选择。
- KPI 约定：每个 KPI 提供值、目标（含差异）与趋势；目标优先取自模型的预算、计划、目标、预测或 SLA 度量值，无目标时询问用户或退化为上期对比并标注，不得编造目标。
- 交叉筛选：维护全仪表盘统一的选中状态，以模型列作为键，通过查询参数传入，未选中时为无操作筛选；比率、去重计数等非可加度量值应重新查询而非前端过滤。
- DAX 查询规范：列使用带引号表名的完全限定形式，度量值不加限定；EVALUATE 接收表表达式，标量用 ROW 包装；单一 DEFINE 块；SUMMARIZECOLUMNS 按分组列、筛选表、名称与度量值对的顺序书写；多行结果使用 ORDER BY；不在 DAX 中写 SQL 关键字；不添加 +0 或 DIVIDE(...,0) 以保留 BLANK 语义；当前期间从数据或日期标志推导，不硬编码年份；返回原始数值，格式化交由仪表盘处理。
- 湖仓与仓库：数据仅在仓库、湖仓 SQL 端点或 SQL 数据库时，用 get_sql_schema 与 run_sql_query（单条只读 SELECT，参数以 @name 传入）；优先复用数据所有者发布的视图和列，并先确认是否已有语义模型覆盖该问题。
- 测试与核对：每个查询先用 run_dax_query 运行，检查列名、类型、行数与取值；用交叉筛选参数分别设置和清空后重跑；将 KPI 与无筛选的同一度量值或用户已信任的报告数字比对。
- 查询结果受 maxRows 限制（默认 1000），部分连接器还会按响应大小截断，均以 truncated: true 标记；查询以登录用户身份运行，行级安全性生效。
- 故障排查：模型未找到时用名称片段 list_models 并配合 workspace/model 消歧；KPI 为空白或结果为空通常因缺少切片器选择或筛选列无匹配值；数字与报告不一致时检查是否重新聚合原始列或遗漏报告筛选；返回所有组合通常因度量值从不返回 BLANK；时间智能错误常因缺少日期上下文或日期表未标记；VAR 附近语法错误多因 VAR 间使用逗号或出现第二个 DEFINE。
使用方式
按工作流执行：先确定模型，再读取架构，然后回答一个业务问题，按每个视觉对象的粒度编写一条查询，测试后再接入交叉筛选，最后与已知总数核对。参考资料包括 dax-query-patterns.md、dax-core-reference.md、dax-time-intelligence.md、kpi-design.md、crossfiltering.md。
适用场景
构建或维护基于 Power BI 语义模型、Microsoft Fabric 数据的仪表盘；需要与既有报告口径一致、支持点击联动的分析型仪表盘。
限制
当用户无权读取表达式时，get_model_schema 返回空表达式，只能依赖名称、描述、显示文件夹与格式字符串，并在已知粒度上测试。仪表盘视觉对象所需行数通常不多，应通过 DAX 聚合到目标粒度或使用 TOPN，而非提高行数上限。