power-bi-partitions

Power BI 分区与表达式技能

管理表分区、命名表达式（M 查询）和日历表。

前提条件

pipx install pbi-cli-tool
pbi-cli skills install
pbi connect

分区

分区定义数据如何加载到表中。每个表至少有一个分区。

# List partitions in a table
pbi partition list --table Sales
pbi --json partition list --table Sales

# Create a partition with an M expression
pbi partition create "Sales_2024" --table Sales \
  --expression "let Source = Sql.Database(\"server\", \"db\"), Sales = Source{[Schema=\"dbo\",Item=\"Sales\"]}[Data], Filtered = Table.SelectRows(Sales, each [Year] = 2024) in Filtered" \
  --mode Import

# Create a partition with DirectQuery mode
pbi partition create "Sales_Live" --table Sales --mode DirectQuery

# Delete a partition
pbi partition delete "Sales_Old" --table Sales

# Refresh a specific partition
pbi partition refresh "Sales_2024" --table Sales

命名表达式

命名表达式是共享的 M/Power Query 定义，可用作数据源或可重复使用的查询逻辑。

# List all named expressions
pbi expression list
pbi --json expression list

# Get a specific expression
pbi expression get "ServerURL"
pbi --json expression get "ServerURL"

# Create a named expression (M query)
pbi expression create "ServerURL" \
  --expression '"https://api.example.com/data"' \
  --description "API endpoint for data refresh"

# Create a parameterized data source
pbi expression create "DatabaseServer" \
  --expression '"sqlserver.company.com"' \
  --description "Production database server name"

# Delete a named expression
pbi expression delete "OldSource"

日历表

日历/日期表可在 DAX 中启用时间智能功能。将表标记为日期表，即可使用 TOTALYTD、SAMEPERIODLASTYEAR 等函数。

# List all calendar/date tables
pbi calendar list
pbi --json calendar list

# Mark a table as a calendar table
pbi calendar mark Calendar --date-column Date

# Alternative: use the table command
pbi table mark-date Calendar --date-column Date

工作流：设置分区表

# 1. Create a table
pbi table create Sales --mode Import

# 2. Create partitions for different date ranges
pbi partition create "Sales_2023" --table Sales \
  --expression "let Source = ... in Filtered2023" \
  --mode Import

pbi partition create "Sales_2024" --table Sales \
  --expression "let Source = ... in Filtered2024" \
  --mode Import

# 3. Refresh specific partitions
pbi partition refresh "Sales_2024" --table Sales

# 4. Verify partitions
pbi --json partition list --table Sales

工作流：管理数据源

# 1. List current data source expressions
pbi --json expression list

# 2. Create shared connection parameters
pbi expression create "ServerName" \
  --expression '"prod-sql-01.company.com"' \
  --description "Production SQL Server"

pbi expression create "DatabaseName" \
  --expression '"SalesDB"' \
  --description "Production database"

# 3. Verify
pbi --json expression list

最佳实践

• 对大型表使用分区，以启用增量刷新
• 仅刷新包含新数据的分区（pbi partition refresh）
• 使用命名表达式共享连接参数（服务器名称、URL）
• 务必使用 pbi calendar mark 标记日历表，以启用时间智能功能
• 在脚本化分区管理时使用 --json 输出
• 将模型导出为 TMDL，以便对分区定义进行版本控制：pbi database export-tmdl ./model/

---

注意事项

• 增量刷新需要使用特定名称和 DateTime 类型的 RangeStart/RangeEnd 参数： 如果参数名称错误、类型设为 Date 而非 DateTime，或缺少策略绑定，PBI 服务会悄然退回到完全刷新。模型仍能正常加载，只有刷新指标会暴露这个问题，通常要等到数周后存储成本飙升时才会发现。
• partition refresh 只刷新指定分区，但下游计算列会在表级别重建： 如果分区事实表的计算列源自另一个分区，那么在执行 --type Calculate 之前，你会看到不一致的值。
• 用作数据源的命名表达式必须通过名称引用，不能内联： 将连接字符串内联到多个分区中，会在 PBI Service 中创建单独的数据源记录——首次刷新时，每条记录都会单独提示输入凭据。
• 在 Power BI 中，同一张表不能同时包含 DirectQuery 和 Import 分区： CLI 在某些版本中可能接受混合模式分区的创建，但模型刷新时会失败，并显示含糊的“复合模型”错误。复合模型要求在表上显式配置双重存储模式，而不是按分区配置。
• pbi expression create 使用单个带引号的字符串值时，会悄然丢失外层引号： --expression '"https://x.com"' 是正确的（M 需要引号），但 --expression "https://x.com" 会创建一个引用未定义标识符的无效表达式。
• 使用 pbi calendar mark 标记的日历表无法通过 CLI 取消标记： 标记后，只能直接编辑 TMDL 中的 dataCategory 或使用 Desktop 的 UI 来恢复。若需要将日历表改为普通维度，请留意这一点。