power-bi-modeling

Power BI 建模技能

使用 pbi-cli 管理语义模型结构。需要安装 pipx install pbi-cli-tool、运行 pbi-cli skills install 和 pbi connect。

先决条件

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

表

pbi table list                                    # List all tables
pbi table get Sales                               # Get table details
pbi table create Sales --mode Import              # Create table
pbi table delete OldTable                         # Delete table
pbi table rename OldName NewName                  # Rename table
pbi table refresh Sales --type Full               # Refresh table data
pbi table schema Sales                            # Get table schema
pbi table mark-date Calendar --date-column Date   # Mark as date table

列

pbi column list --table Sales                                       # List columns
pbi column get Amount --table Sales                                 # Get column details
pbi column create Revenue --table Sales --data-type double --source-column Revenue  # Data column
pbi column create Profit --table Sales --expression "[Revenue]-[Cost]"              # Calculated
pbi column delete OldCol --table Sales                              # Delete column
pbi column rename OldName NewName --table Sales                     # Rename column

度量值

pbi measure list                                                    # List all measures
pbi measure list --table Sales                                      # Filter by table
pbi measure get "Total Revenue" --table Sales                       # Get details
pbi measure create "Total Revenue" -e "SUM(Sales[Revenue])" -t Sales                        # Basic
pbi measure create "Revenue $" -e "SUM(Sales[Revenue])" -t Sales --format-string "\$#,##0"  # Formatted
pbi measure create "KPI" -e "..." -t Sales --folder "Key Measures" --description "Main KPI" # With metadata
pbi measure update "Total Revenue" -t Sales -e "SUMX(Sales, Sales[Qty]*Sales[Price])"       # Update expression
pbi measure delete "Old Measure" -t Sales                           # Delete
pbi measure rename "Old" "New" -t Sales                             # Rename
pbi measure move "Revenue" -t Sales --to-table Finance              # Move to another table

度量值表达式中的多行 DAX： -e 标志会将 DAX 作为 shell 参数传递，因此会合并换行符。对于 SUM(Sales[Amount]) 或 DIVIDE([A] - [B], [B]) 这类简单表达式，这样做没问题。对于使用 VAR/RETURN 的复杂表达式，请改用标准输入进行管道传输：

echo 'VAR TotalSales = SUM(Sales[Amount])
VAR TotalCost = SUM(Sales[Cost])
RETURN TotalSales - TotalCost' | pbi measure create "Profit" -e - -t Sales

完整说明和更多变通方法，请参阅 power-bi-dax 技能。

关系

pbi relationship list                              # List all relationships
pbi relationship get RelName                       # Get details
pbi relationship create \
  --from-table Sales --from-column ProductKey \
  --to-table Products --to-column ProductKey       # Create relationship
pbi relationship delete RelName                    # Delete
pbi relationship find --table Sales                # Find relationships for a table
pbi relationship activate RelName                  # Activate
pbi relationship deactivate RelName                # Deactivate

层次结构

pbi hierarchy list --table Date                    # List hierarchies
pbi hierarchy get "Calendar" --table Date          # Get details
pbi hierarchy create "Calendar" --table Date       # Create
pbi hierarchy delete "Calendar" --table Date       # Delete

计算组

pbi calc-group list                                # List calculation groups
pbi calc-group create "Time Intelligence" --description "Time calcs"  # Create group
pbi calc-group items "Time Intelligence"           # List items
pbi calc-group create-item "YTD" \
  --group "Time Intelligence" \
  --expression "CALCULATE(SELECTEDMEASURE(), DATESYTD(Calendar[Date]))"  # Add item
pbi calc-group delete "Time Intelligence"          # Delete group

创建日期/日历表

日期表对于时间智能函数（TOTALYTD、SAMEPERIODLASTYEAR、DATEADD 等）至关重要。

# Create a calculated date table with DAX (covers full calendar years)
pbi table create Calendar \
  --dax-expression "ADDCOLUMNS(CALENDAR(DATE(2023,1,1), DATE(2024,12,31)), \"Year\", YEAR([Date]), \"MonthNumber\", MONTH([Date]), \"MonthName\", FORMAT([Date], \"MMMM\"), \"Quarter\", \"Q\" & FORMAT([Date], \"Q\"))"

# Mark it as a date table (required for time intelligence)
pbi table mark-date Calendar --date-column Date

# Verify it's recognized as a date table
pbi calendar list

工作流：创建星型架构

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

# 2. Create dimension tables
pbi table create Products --mode Import
pbi table create Calendar --mode Import

# 3. Create relationships
pbi relationship create --from-table Sales --from-column ProductKey --to-table Products --to-column ProductKey
pbi relationship create --from-table Sales --from-column DateKey --to-table Calendar --to-column DateKey

# 4. Mark date table
pbi table mark-date Calendar --date-column Date

# 5. Add measures
pbi measure create "Total Revenue" -e "SUM(Sales[Revenue])" -t Sales --format-string "\$#,##0"
pbi measure create "Total Qty" -e "SUM(Sales[Quantity])" -t Sales --format-string "#,##0"
pbi measure create "Avg Price" -e "AVERAGE(Sales[UnitPrice])" -t Sales --format-string "\$#,##0.00"

# 6. Verify
pbi table list
pbi measure list
pbi relationship list

最佳实践

• 为货币（$#,##0）、百分比（0.0%）和整数（#,##0）度量值使用格式字符串
• 按业务领域将度量值整理到显示文件夹中
• 始终使用 mark-date 标记日历表，以支持时间智能
• 编写脚本时使用 --json 标志：pbi --json measure list
• 导出 TMDL 以进行版本控制：pbi database export-tmdl ./model/

---

注意事项

• mark-date 需要连续且无缺口的日期列： 日历表如果缺少某一天（闰年、手动筛选），执行 mark-date 不会报错，但时间智能函数（如 SAMEPERIODLASTYEAR）会静默失效——它们会返回 BLANK，且不会提供诊断信息。
• 在某些 pbi-cli 版本中，relationship create 默认使用双向关系： 创建后请立即使用 pbi --json relationship get RelName 检查。事实表与小型维度表之间的双向联接会静默破坏无关度量值中的筛选上下文传播。
• 通过 --dax-expression 创建的计算表不会在数据刷新时刷新： 它们只会在进程重新计算时重新求值。底层表的编辑内容不会生效，直到执行 Full 或 Calculate 刷新——在部分刷新管道中很容易忽略这一点。
• measure move --to-table 会更新所属表，但不会更新 DAX 中的引用： 现有引用 Sales[Margin] 的度量值仍可正常工作，因为度量值的作用域是整个模型；但可视化文件 report.json 可能仍保留旧表引用，并在之后重命名源表时出错。
• format-string 中的字面量 $ 需要进行 shell 转义： --format-string "$#,##0" 经 shell 变量展开后会变成 #,##0。请使用 --format-string "\$#,##0" 或用单引号括起来——生成的度量值会显示“错误”，但不会报错。
• 计算组的创建顺序会影响排序： 首先创建的项序号为 0，并作为默认项。请先添加“No Time Calc”占位项，否则未选择任何项时，度量值会静默应用 YTD。