refresh-semantic-model

刷新语义模型

通过 Power BI 增强型刷新 REST API 和 Fabric CLI 触发、监控、验证和排查语义模型刷新问题。

核心概念

语义模型刷新会从上游数据源重新加载数据，和/或重新计算依赖对象（计算列、计算表、度量值）。刷新范围可以是整个模型、特定表或单个分区。

REST API 提供六种刷新类型；第七种（add）仅支持 TMSL：

类型	重新加载数据	重新计算	主要用例	API
full	是	是	从头开始完整重新加载	REST
automatic	视情况而定	视情况而定	智能刷新；仅在需要时处理	REST
dataOnly	是	否*	重新加载数据；清除依赖项	REST
calculate	否	是	不重新加载数据，仅重新计算	REST
clearValues	否	否	清空对象中的数据	REST
defragment	否	否	清理列字典	REST
add	追加	是	向分区追加行	TMSL

*dataOnly 会清除依赖对象（计算列、计算表），但不会重新计算它们。之后请执行 calculate 刷新以恢复它们。

有关详细说明、增量刷新策略下的行为、提交模式和并行选项，请参阅 references/refresh-types.md。

刷新工作流

步骤 1：解析 ID

提取 API 调用所需的工作区和模型 GUID：

WS_ID=$(fab get "WorkspaceName.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "WorkspaceName.Workspace/ModelName.SemanticModel" -q "id" | tr -d '"')

步骤 2：查询基线数据（刷新前验证）

触发刷新前，先获取基线快照，以便之后验证数据是否确实发生变化。对模型执行 DAX 查询，获取当前行数或最大日期：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/executeQueries" \
  -X post -i '{
    "queries": [{"query": "EVALUATE ROW(\"RowCount\", COUNTROWS(FactSales), \"MaxDate\", MAX('FactSales'[OrderDate]))"}],
    "serializerSettings": {"includeNulls": true}
  }'

记录输出。刷新后将此基线与新数据进行比较，以确认数据已更新。

步骤 3：触发刷新

刷新整个模型（最简单）：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full"}'

刷新特定表：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{
    "type": "full",
    "objects": [{"table": "FactSales"}, {"table": "DimProduct"}]
  }'

刷新特定分区：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{
    "type": "full",
    "objects": [
      {"table": "FactSales", "partition": "FactSales_2024"},
      {"table": "FactSales", "partition": "FactSales_2023"}
    ]
  }'

仅刷新数据（跳过重新计算）：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"dataOnly","objects":[{"table":"FactSales"}]}'

仅计算（不重新加载数据）：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"calculate"}'

清除表中的值：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"clearValues","objects":[{"table":"StagingTable"}]}'

如需使用基于脚本并通过 CLI 参数操作的方法，请使用 scripts/refresh_model.py。

步骤 4：监控状态

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

状态值：Unknown、InProgress、Completed、Failed、Disabled、Cancelled

步骤 5：刷新后验证

刷新完成后，重新运行步骤 2 中的同一 DAX 查询并进行比较：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/executeQueries" \
  -X post -i '{
    "queries": [{"query": "EVALUATE ROW(\"RowCount\", COUNTROWS(FactSales), \"MaxDate\", MAX('FactSales'[OrderDate]))"}],
    "serializerSettings": {"includeNulls": true}
  }'

如果刷新成功但数据没有变化：

• 上游数据源尚未更新
• ETL 管道（Fabric 管道、笔记本、Data Factory 或其他编排工具）需要先运行
• 检查 lakehouse/warehouse/SQL 数据库，确认是否存在最新数据
• 对于 Fabric lakehouse：运行 fab run "Workspace.Workspace/Pipeline.DataPipeline" 或触发笔记本
• 刷新只会拉取数据源提供的内容；如果源数据已过期，刷新仍会成功，但不会显示新数据

步骤 6：取消（如有需要）

若要取消正在进行的增强型刷新，请先从刷新历史记录中获取 requestId：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

响应中包含 requestId 字段。使用该字段取消刷新：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes/<requestId>" \
  -X delete

仅适用于通过增强型 API 触发的刷新（不包括计划刷新或门户刷新）。

使用刷新脚本

scripts/refresh_model.py 脚本通过 CLI 参数封装了增强型刷新 API：

# Full refresh
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID

# Refresh specific tables
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --tables Sales,Calendar

# Refresh specific partitions
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --partitions Sales:Sales_2024

# Data-only then calculate (two-phase)
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID -t dataOnly --tables FactSales
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID -t calculate

# Partial batch with parallelism
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --commit partialBatch --parallelism 4

# Skip incremental refresh policy
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --no-policy

# Check status only
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --status-only

# Poll until complete
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --poll

增强刷新选项

增强刷新 API（需要 Premium/Fabric 容量）在标准刷新基础上扩展了以下功能：

参数	默认值	用途
type	automatic	刷新类型（full、automatic、dataOnly、calculate 等）
commitMode	transactional	原子提交或按对象进行部分批处理
maxParallelism	10	并行处理线程数
retryCount	0	失败时自动重试
objects	整个模型	表/分区目标数组
applyRefreshPolicy	true	应用或跳过增量刷新策略
effectiveDate	当前日期	覆盖增量策略窗口的日期
timeout	05:00:00	每次尝试的超时时间（含重试时总计最长 24h）

常见模式

两阶段刷新（大型模型）

将数据加载和重新计算拆分，以便更好地控制流程并隔离故障：

1. 使用 dataOnly 和 partialBatch 重新加载所有表（每个表独立提交）
2. 使用 calculate 和 transactional 原子地重新计算所有内容

选择性分区刷新

对于采用增量刷新的表，仅刷新特定时间范围的分区，而非整个表。若要发现分区名称，可使用 Tabular Editor、SSMS 通过 XMLA 终结点查询模型的 TMSL 元数据，或使用 Fabric CLI 导出：

fab export "Workspace.Workspace/Model.SemanticModel" -o /tmp/model -f

检查导出的 TMDL 表文件；每个 partition 块都会列出分区名称。在刷新请求的 objects 数组中指定目标分区。

ETL 后刷新

编排数据管道时：

1. 运行上游 ETL（Fabric 管道、笔记本、ADF 或自定义流程）
2. 确认源中有最新数据（lakehouse、warehouse、SQL）
3. 触发语义模型刷新
4. 使用 DAX 查询验证行数或最大日期是否发生变化
5. 如果没有变化，请检查 ETL 输出；语义模型刷新已成功，但源数据已过时

故障排查

常见故障速查。完整的故障排查指南包含调试工作流和详细错误表，请阅读 references/troubleshooting.md。

症状	可能原因	解决方法
因凭据错误而失败	凭据已过期、缺失，或复制后未随之转移	在数据集设置中更新；使用 fab cp 时仅共享云连接会转移
表上的类型不匹配	源列类型与模型列类型不一致	检查模型定义中的列数据类型与源架构；在分区表达式中添加 Table.TransformColumnTypes
列不存在	源列已重命名、移除或大小写不同	检查源架构；在分区表达式中添加 Table.RenameColumns
超时（共享容量 2h / Premium 5h）	模型过大，无法在单个刷新时段内完成	实施增量刷新；通过 XMLA 使用分区级刷新；缩小模型
计算表为空	dataOnly 刷新会清除内容，但不会重建	使用增强刷新 API 执行 calculate 刷新，以重建计算表和计算组
Premium 上受到限制	并发刷新过多	错开刷新计划；在非高峰时段刷新

调试单表失败

完整刷新失败时，可通过 Enhanced Refresh API 单独刷新各个表，以确定失败的表：

# Refresh dimensions first
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full","objects":[{"table":"Customers"}]}'

# Then facts
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full","objects":[{"table":"Invoices"}]}'

# Then recalculate
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"calculate"}'

检查失败表的分区表达式，并通过 fab export 或 fab table schema 对比源架构与模型预期的列名和类型。

大模型策略

对于超过 1 GB 或刷新时间超过一小时的模型，采用有针对性的方法会更有效：

• 分区级刷新：通过增强型 REST API 或 XMLA 端点刷新单个表分区，而不是刷新整个模型。需要 Premium/Fabric 容量。
• 增量刷新：按日期自动对大型表进行分区；每个周期只刷新近期数据。在 Power Query 中配置 RangeStart/RangeEnd 参数。还支持检测数据更改，以完全跳过未更改的分区。
• 聚合：将大型事实表按更粗粒度预聚合到导入模式的聚合表中。明细查询会回退到 DirectQuery。可缩短刷新时间并减少内存占用。
• 混合表：历史分区采用导入模式；近期数据使用实时 DirectQuery 分区。相关表必须采用 Dual 存储模式。
• 扩展容量：在 Premium 容量上启用语义模型扩展，将刷新与查询工作负载隔离。主副本刷新时，由只读副本处理查询。

容量限制

容量类型	每日最大刷新次数	默认超时	增强功能
Pro	8	2 小时	否
Premium Per User	48	5 小时	是
Premium / Fabric	48	5 小时	是

Pro 容量仅支持对整个模型进行标准刷新。增强刷新功能（定向刷新表/分区、提交模式、并行处理、取消、覆盖超时）需要 Premium 或 Fabric 容量。

要求

• 工作区贡献者或更高权限
• 已通过 fab CLI 进行身份验证：fab auth login

更多资源

参考文件

• references/refresh-types.md -- 7 种刷新类型、提交模式、并行处理、增量策略交互、状态值、XMLA/TMSL 详情以及两阶段刷新模式的完整参考
• references/troubleshooting.md -- 全面的故障排除指南：凭据错误、类型/架构不匹配、超时、容量限制、增量刷新问题、调试工作流和大模型策略

脚本

• scripts/refresh_model.py -- 用于触发和监控刷新的 CLI 工具，支持所有增强选项

相关技能

• semantic-model -- 模型设计、构建以及质量/性能审查
• lineage-analysis -- 下游报表发现和影响分析
• organize-semantic-model -- 组织结构和命名整改
• fabric-cli（fabric-cli 插件）-- 通过 fab CLI 管理工作区和项目