mcpField
P
powerbi-core

powerbi-core

github.com/josiahsiegel数据与数据库5994 次安装19 周前更新
代码仓库

关于 powerbi-core

powerbi-core 是面向 Power BI 开发者的数据建模与架构参考技能,涵盖存储模式、关系、数据源和常见问题。它以实用规则帮助规划语义模型和刷新配置。

主要功能

  1. 01星型架构建模指南
  2. 02存储模式选择参考
  3. 03关系与筛选规则
  4. 04增量刷新和网关配置
  5. 05身份验证与常见陷阱

适用场景

  1. 01规划 Power BI 语义模型
  2. 02为实时或大型数据选择存储模式
  3. 03配置增量刷新与数据网关

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill powerbi-core

安装后在 Claude Code 中输入/powerbi-core确认已加载。

附带文件references/data-sources-detail.mdreferences/gotchas-deep-dive.md

详细介绍

Power BI 核心概念和数据建模

概述

Power BI 核心知识,涵盖数据建模最佳实践、连接模式、源类型、关系和常见陷阱。本技能提供每位 Power BI 开发者都需要掌握的基础架构指导。

数据模型设计 - 星型架构

始终使用星型架构拓扑设计数据模型:

组件用途示例
事实表数值事件/交易Sales、Orders、WebVisits
维度表描述性属性Date、Product、Customer、Geography
桥接表解决多对多关系StudentCourse、OrderProduct

强制规则:

  • 中心放置一个事实表,维度表从中心向外辐射
  • 关系从维度(单侧)流向事实(多侧)
  • 使用整数代理键,而非自然键/业务键
  • 保持事实表精简(仅包含键和度量值)
  • 对维度进行反规范化(将雪花架构扁平化为星型架构)
  • 创建专用日期维度表(禁用自动日期/时间)
  • 除非绝对必要且范围受控,否则不要使用双向交叉筛选

存储模式

模式数据位置刷新性能适用情况
Import内存中的 VertiPaq计划/按需查询速度最快默认选择,压缩后数据小于 1GB
DirectQuery源数据库实时取决于源需要实时数据,数据量过大而无法导入
Dual两者计划 + 实时两者兼优复合模型中的维度表
Direct LakeOneLake Delta 表框架刷新(秒级)接近导入模式的速度Fabric 湖仓/数据仓库场景

Import 模式注意事项:

  • PBIX 文件大小上限为 1GB(服务中的 Premium/PPU 上限为 10GB)
  • 数据是刷新时的快照;不是实时数据
  • 计划刷新上限:每天 8 次(Pro),每天 48 次(Premium/PPU)

DirectQuery 限制:

  • 查询时不会应用 Power Query 转换
  • 每个模型只能使用一个源(复合模型除外)
  • 性能完全取决于源查询速度
  • 许多 DAX 函数不可用或性能下降
  • DirectQuery 表不支持计算列
  • 每个视觉对象查询的行数上限为 100 万

Direct Lake 关键注意事项(2025-2026 正式发布):

  • 有两个变体:OneLake 上的 Direct Lake(DL/OL)和 SQL 终结点上的 Direct Lake(DL/SQL)
  • DL/OL 不会回退到 DirectQuery——如果无法提供数据,查询将失败
  • DL/SQL 可以通过 SQL 分析终结点回退到 DirectQuery
  • 防护限制因容量而异:F32 每个表最多允许 1,000 个文件/行组;F64/P1 最多允许 5,000 个
  • 最大内存是用于分页的软限制,而非硬性防护限制——过多分页会降低性能
  • 磁盘/OneLake 上的最大模型大小是硬性防护限制——超出后会回退到 DQ(DL/SQL)或导致失败(DL/OL)
  • 完整支持 DAX,包括计算列
  • 框架刷新(仅刷新元数据)可在几秒内完成
  • 使用 Direct Lake 模式的 Power BI Embedded 自 2025 年 3 月起正式发布

选择存储模式的决策树:

  1. 数据位于 Fabric OneLake Delta 表中?使用 Direct Lake
  2. 需要实时数据,且源速度快?使用 DirectQuery
  3. 数据小于 1GB,且可接受刷新延迟?使用 Import(性能最佳)
  4. 数据量大且需要快速查询?使用复合模型(导入维度 + DQ 事实 + 聚合表)

关系

属性选项默认值
基数一对多、多对一、一对一、多对多一对多
交叉筛选方向单向、双向单向
活动状态是/否是(每条路径仅有一个活动关系)

关系规则:

  • 任意两个表之间只能有一个活动关系
  • 在 DAX 中使用 USERELATIONSHIP() 激活非活动关系
  • 避免双向筛选——它会导致筛选路径不明确、性能下降和意外结果
  • 多对多关系需要桥接表,或使用复合模型的多对多基数
  • 引用完整性:设置“假设引用完整性”以提升 DirectQuery 性能

数据源速查

类别数据源
Microsoft SQLSQL Server、Azure SQL、Azure Synapse、SQL Server Analysis Services
AzureCosmos DB、Data Explorer (Kusto)、Blob Storage、Data Lake、Fabric Lakehouse/Warehouse
云数据库Snowflake、Databricks、Google BigQuery、Amazon Redshift、Amazon Athena
文件Excel、CSV/TSV、JSON、XML、Parquet、PDF
服务SharePoint、Dynamics 365、Salesforce、Google Analytics、Azure DevOps
协议OData、REST API、ODBC、OLEDB
流式处理Azure Stream Analytics、PubNub、REST API 推送

增量刷新

为大型导入表配置增量刷新,避免完整刷新:

  1. 在 Power Query 中创建 RangeStart 和 RangeEnd 参数(类型为 DateTime)
  2. 使用这些参数筛选日期列
  3. 配置刷新策略:存档期限(例如 3 年)、增量期限(例如 30 天)
  4. 可选:启用“检测数据更改”,并指定上次修改时间列
  5. 可选:通过 DirectQuery 为最新分区启用实时数据

**要求:**要使用超出基本增量刷新的功能,需具备 Premium、PPU 或 Fabric 容量。Pro 工作区支持增量刷新,但存在限制。

2025-2026 年改进:

  • 现在可直接在 Power BI Service 中编辑采用增量刷新的语义模型(更改计算列、重命名表、调整层次结构),无需重新打开 Desktop
  • 增强的刷新 API 支持选择性分区刷新,可实现更精细的控制
  • 通过更快的分区处理,提升 TB 级数据集的性能

网关配置

本地数据网关将本地数据源连接到 Power BI Service:

网关类型使用场景
标准(企业)由多名用户共享,集中管理
个人单个用户使用,仅用于开发/测试
虚拟网络 (VNet)连接到 Azure VNet 的数据源,无需本地硬件

VNet 数据网关(2025-2026 年):

  • 无需本地硬件,即可连接 VNet 内的 Azure 数据源
  • 由 Fabric/Power BI Service 管理,无需维护网关计算机
  • 支持 Azure SQL、Synapse、Azure Data Explorer 及其他绑定到 VNet 的服务
  • 在 Fabric 管理门户的网关管理中启用

网关版本发布(2025-2026 年):

  • 2025-2026 年期间每月发布新版本,增强缓存和查询折叠功能
  • 通过优化连接池提升查询性能
  • 自 2025 年 9 月起,Power BI Desktop for Report Server 仅支持 64 位版本

常见网关故障:

  • 凭据过期——在网关设置中更新
  • 无法访问数据源——检查防火墙、VPN 和 DNS
  • 内存耗尽——监控网关计算机资源
  • Mashup 引擎崩溃——检查 Power Query 的复杂性

数据源身份验证

方法使用场景最适合
OAuth2云数据源(Azure SQL、Snowflake、Databricks)交互式使用、SSO
Service Principal自动刷新、CI/CD 管道无人值守操作
Workspace IdentityFabric 工作区(无需管理机密)Fabric 原生模型
Managed IdentityDataflows Gen2 连接 Azure 数据源无机密的 PaaS 访问
Username/Password旧版本地数据源绑定网关的数据源

Workspace Identity(2025-2026):

  • 与 Fabric 工作区绑定,类似 Azure Managed Identity
  • 永不过期,无需管理机密或密码
  • 在工作区设置中配置,并分配给语义模型数据源
  • 在 Fabric 原生场景中优先于 service principal

OAuth2 令牌限制: 通过 REST API(而非 UI)设置时,OAuth2 凭据不包含刷新令牌,并会在 1 小时后过期。对于长时间运行的自动化,请使用 service principal。

连接池最佳实践:

  • 网关会在可能的情况下复用连接——尽量减少不同的凭据集
  • 在数据源设置中设置查询超时(默认 5 分钟,复杂查询可调高)
  • 在 Power Query 中使用 try/otherwise,为临时数据源故障实现重试逻辑

常见问题与反模式

问题影响修复方法
启用了自动日期/时间隐藏日期表会使模型膨胀(每个日期列对应一个日期表)在 Options > Data Load 中禁用
隐式度量值(将数值拖到可视化对象中)无法控制聚合方式,也无法复用创建显式 DAX 度量值
双向交叉筛选产生歧义、降低性能、导致结果错误使用单向筛选,并在 DAX 中处理
事实表中的列过多模型膨胀、刷新缓慢、浪费内存保持事实表精简:仅保留键和数值
混淆 BLANK、0 和 nullDAX 对 BLANK 和 0 的处理不同;可视化对象会隐藏 BLANK 行使用 IF/COALESCE 显式处理
循环依赖错误通常由相互引用的计算列或双向筛选器导致重构模型,打破循环
1GB PBIX 限制无法在本地保存文件删除未使用的列,优化基数
Power BI Service 与 Desktop 的差异某些功能仅在其中一个版本中提供设计前查看功能矩阵
计算列与度量值计算列会占用内存,并按行存储优先使用度量值(在查询时计算)
事实表中的字符串列高基数字符串会破坏 VertiPaq 压缩移至维度表,并使用键引用

其他资源

参考文件
  • references/data-sources-detail.md -- 所有源类型的详细连接器配置
  • references/gotchas-deep-dive.md -- 包含示例和解决模式的扩展问题分析

评论

支持 Markdown