power-bi-dax

Power BI DAX 技能

针对已连接的 Power BI 模型执行并验证 DAX 查询。

前提条件

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

执行查询

# Inline query
pbi dax execute "EVALUATE TOPN(10, Sales)"

# From file
pbi dax execute --file query.dax

# From stdin (piping)
cat query.dax | pbi dax execute -
echo "EVALUATE Sales" | pbi dax execute -

# With options
pbi dax execute "EVALUATE Sales" --max-rows 100
pbi dax execute "EVALUATE Sales" --timeout 300       # Custom timeout (seconds)

# JSON output for scripting
pbi --json dax execute "EVALUATE Sales"

CLI 中的 DAX 表达式限制

将 DAX 作为 -e 参数传递时，Shell 会把换行符压缩成一行。像 SUM(Sales[Amount]) 这样的简单表达式可以正常运行，但使用 VAR/RETURN 的多行 DAX 会出错，因为 DAX 解析器需要这些关键字之间的换行符。

为何这很重要： 像 VAR x = [Total Sales] VAR y = [Sales PY] RETURN DIVIDE(x - y, y) 这样的度量值会因语法错误而失败，因为引擎会将其视为一行连续文本，没有语句分隔符。

解决方法（任选其一）：

# Option 1: Pipe from stdin (recommended for measures)
echo 'VAR TotalSales = SUM(Sales[Amount])
VAR TotalCost = SUM(Sales[Cost])
RETURN TotalSales - TotalCost' | pbi measure create "Profit" -e - -t Sales

# Option 2: Write to a .dax file and use --file (for queries)
echo 'EVALUATE
ROW("Result",
    VAR x = SUM(Sales[Amount])
    RETURN x
)' > query.dax
pbi dax execute --file query.dax

单行替代写法（条件允许时优先使用）：

对于简单的比率／增长度量值，使用内联模式替代 VAR/RETURN：

# Instead of: VAR x = SUM(...) / VAR y = SUM(...) / RETURN DIVIDE(x, y)
# Use inline DIVIDE -- it handles division-by-zero gracefully (returns BLANK):
pbi measure create "Margin %" \
  -e "DIVIDE(SUM(Sales[Amount]) - SUM(Sales[Cost]), SUM(Sales[Amount]))" \
  -t Sales --format-string "0.0%"

# Instead of: VAR current = [Total Sales] / VAR prev = [Sales PY] / RETURN DIVIDE(...)
# Reference measures directly in DIVIDE:
pbi measure create "YoY %" \
  -e "DIVIDE([Total Sales] - [PY Sales], [PY Sales])" \
  -t Sales --format-string "0.0%"

验证查询

pbi dax validate "EVALUATE Sales"
pbi dax validate --file query.dax

缓存管理

pbi dax clear-cache    # Clear the formula engine cache

使用 DAX 创建度量值

# Simple aggregation
pbi measure create "Total Sales" -e "SUM(Sales[Amount])" -t Sales

# Time intelligence
pbi measure create "YTD Sales" -e "TOTALYTD(SUM(Sales[Amount]), Calendar[Date])" -t Sales

# Previous year comparison
pbi measure create "PY Sales" -e "CALCULATE([Total Sales], SAMEPERIODLASTYEAR(Calendar[Date]))" -t Sales

# Year-over-year change
pbi measure create "YoY %" -e "DIVIDE([Total Sales] - [PY Sales], [PY Sales])" -t Sales --format-string "0.0%"

常见 DAX 模式

探索模型数据

# List all tables
pbi dax execute "EVALUATE INFO.TABLES()"

# List columns in a table
pbi dax execute "EVALUATE INFO.COLUMNS()"

# Preview table data
pbi dax execute "EVALUATE TOPN(10, Sales)"

# Count rows
pbi dax execute "EVALUATE ROW(\"Count\", COUNTROWS(Sales))"

聚合

# Basic sum
pbi dax execute "EVALUATE ROW(\"Total\", SUM(Sales[Amount]))"

# Group by with aggregation
pbi dax execute "EVALUATE SUMMARIZECOLUMNS(Products[Category], \"Total\", SUM(Sales[Amount]))"

# Multiple aggregations
pbi dax execute "
EVALUATE
SUMMARIZECOLUMNS(
    Products[Category],
    \"Total Sales\", SUM(Sales[Amount]),
    \"Avg Price\", AVERAGE(Sales[UnitPrice]),
    \"Count\", COUNTROWS(Sales)
)
"

筛选

# CALCULATE with filter
pbi dax execute "
EVALUATE
ROW(\"Online Sales\", CALCULATE(SUM(Sales[Amount]), Sales[Channel] = \"Online\"))
"

# FILTER with complex condition
pbi dax execute "
EVALUATE
FILTER(
    SUMMARIZECOLUMNS(Products[Name], \"Total\", SUM(Sales[Amount])),
    [Total] > 1000
)
"

时间智能

# Year-to-date
pbi dax execute "
EVALUATE
ROW(\"YTD\", TOTALYTD(SUM(Sales[Amount]), Calendar[Date]))
"

# Rolling 12 months
pbi dax execute "
EVALUATE
ROW(\"R12\", CALCULATE(
    SUM(Sales[Amount]),
    DATESINPERIOD(Calendar[Date], MAX(Calendar[Date]), -12, MONTH)
))
"

排名

# Top products by sales
pbi dax execute "
EVALUATE
TOPN(
    10,
    ADDCOLUMNS(
        VALUES(Products[Name]),
        \"Total\", CALCULATE(SUM(Sales[Amount]))
    ),
    [Total], DESC
)
"

性能提示

• 开发期间使用 --max-rows 限制结果集
• 基准测试前运行 pbi dax clear-cache
• 分组时优先使用 SUMMARIZECOLUMNS，而非 SUMMARIZE
• 使用带简单筛选条件的 CALCULATE，而非嵌套的 FILTER
• 聚合足以满足需求时，避免在大型表上使用迭代器（SUMX、FILTER）

---

注意事项

• -e 中的 VAR/RETURN 换行符会失效： Shell 会将换行符压缩为空格，而 DAX 解析器需要它们作为语句分隔符。将 VAR x = ... VAR y = ... RETURN ... 写在一行会导致“语法错误”，且不会指出有用的位置。请通过 stdin 管道传入，或使用 --file。
• CALCULATE(SUM(x), ALL(table))、ALLEXCEPT 与 ALLSELECTED： 三者都能返回看似合理的数字，但只有一种是正确的。ALL 会清除该表上的所有筛选；ALLEXCEPT 只保留列出的列；ALLSELECTED 会遵循外部筛选。选错会导致总计悄然出错。
• SUMMARIZECOLUMNS 会丢弃所有度量值均为 BLANK 的行： 输出中“缺失的类别”通常是由此筛选造成的，并非数据缺失。如果必须显示该行，可用 COALESCE(measure, 0) 包装度量值。
• DIVIDE([a], [b]) 在除以零时返回 BLANK，而非 0： 空白值会在后续图表中显示为空隙，而非零值。需要将结果设为零时，请明确传入第三个参数：DIVIDE([a], [b], 0)。
• pbi dax clear-cache 只会清除公式引擎缓存： 存储引擎缓存仍会保留。要进行真实的冷查询基准测试，还需重启 Desktop 或重新连接；否则重复运行会显得快得不切实际。
• INFO.TABLES() 也会返回隐藏表： 计算组、自动日期层次结构和翻译表会与用户表一同显示。筛选 [IsHidden] = FALSE，即可只查看报表作者能看到的内容。