power-bi-filters

Power BI 筛选器技能

在 PBIR 报表页面和视觉对象上添加和管理筛选器。筛选器存储在 page.json（页面级）或 visual.json（视觉对象级）的 filterConfig 部分中。无需连接 Power BI Desktop。

列出筛选器

# List all filters on a page
pbi filters list --page page_abc123

# List filters on a specific visual
pbi filters list --page page_abc123 --visual visual_def456

返回每个筛选器的名称、类型、字段和作用范围（页面或视觉对象）。

分类筛选器

从列中包含或排除特定值：

# Include only East and West regions
pbi filters add-categorical --page page1 \
    --table Sales --column Region \
    --values "East" "West"

筛选器会显示在页面的 filterConfig.filters 数组中。Power BI 会将其作为针对指定列的 IN 列表进行评估。

TopN 筛选器

仅显示按度量值排名的前（或后）N 个项目：

# Top 10 products by revenue
pbi filters add-topn --page page1 \
    --table Product --column Name \
    --n 10 \
    --order-by-table Sales --order-by-column Revenue

# Bottom 5 by quantity (ascending)
pbi filters add-topn --page page1 \
    --table Product --column Name \
    --n 5 \
    --order-by-table Sales --order-by-column Quantity \
    --direction Bottom

--table 和 --column 定义要筛选的维度（即要保留的行）。--order-by-table 和 --order-by-column 定义用于排名的度量值。它们可以属于不同的表，例如，按销售收入筛选产品名称。

方向默认为 Top（降序，即最高的 N 个）。使用 --direction Bottom 表示升序（即最低的 N 个）。

相对日期筛选器

按相对于今天的滚动时间范围进行筛选：

# Last 30 days
pbi filters add-relative-date --page page1 \
    --table Calendar --column Date \
    --period days --count 30 --direction last

# Next 7 days
pbi filters add-relative-date --page page1 \
    --table Calendar --column Date \
    --period days --count 7 --direction next

周期选项：days、weeks、months、quarters、years。 方向：last（过去）或 next（未来）。

视觉对象级筛选器

通过添加 --visual，将筛选器添加到特定视觉对象，而不是整个页面：

pbi filters add-categorical --page page1 --visual vis_abc \
    --table Sales --column Channel \
    --values "Online"

移除筛选器

# Remove a specific filter by name
pbi filters remove --page page1 --name filter_abc123

# Clear ALL filters from a page
pbi filters clear --page page1

筛选器名称是自动生成的唯一 ID。使用 pbi filters list 查找要移除的筛选器名称。

工作流：设置仪表板筛选器

# 1. Add a date filter to the overview page
pbi filters add-relative-date --page overview \
    --table Calendar --column Date \
    --period months --count 12 --direction last

# 2. Add a TopN filter to show only top customers
pbi filters add-topn --page overview \
    --table Customer --column Name \
    --n 20 \
    --order-by-table Sales --order-by-column Revenue

# 3. Verify
pbi filters list --page overview

禁止自动同步（--no-sync）

默认情况下，每个写入命令都会自动同步 Power BI Desktop。依次将筛选器应用到多个页面或视觉对象时，Desktop 会在每条命令后重新加载。

使用 filters 命令组中的 --no-sync 批量应用所有筛选器更改，然后在最后调用一次 pbi report reload：

# Suppress sync while applying filters
pbi filters --no-sync add-categorical --page overview --table "Calendar Lookup" --column "Year" --values "2024"
pbi filters --no-sync add-categorical --page details --table "Product Lookup" --column "Category" --values "Bikes"

# Single reload when all filters are done
pbi report reload

JSON 输出

pbi --json filters list --page page1

---

注意事项

• TopN 筛选器中的 --table/--column 指定的是要保留的内容，--order-by-* 指定的是排名依据： 交换两者也能成功编译，但会对错误的维度进行排名——你会看到“前 10 个日期”，而不是“前 10 个产品”。CLI 无法发现这种不匹配，因为两组参数都是有效的 Table[Column] 引用。
• 相对日期筛选器以用户在 Service 中的本地时间为基准，而非模型时区： “最近 7 天”筛选器会在每位查看者当地时间的午夜发生偏移。对于审计报表，不同时区的用户会看到不同的总计——请改用绝对日期范围。
• filters clear 会移除所有内容，包括先前书签设置的页面级筛选器： 基于清除前状态创建的书签仍会引用已不存在的筛选器 ID，激活时会静默地按“未应用筛选器”处理。
• 每次重新导出 TMDL/PBIR 时，自动生成的筛选器名称都会包含不同的 GUID： 针对导出快照执行 filters remove --name filter_abc123 脚本并不可靠。请务必在脚本中移除筛选器前重新列出，或在 CLI 支持时按 --table/--column 筛选。
• 视觉对象级筛选器会静默覆盖页面级筛选器： 页面筛选器设为 Region = East，而视觉对象筛选器设为 Region = West 时，视觉对象将显示为空，而不会出现“冲突”警告。视觉对象无数据显示时，请使用 pbi filters list --page X --visual Y 检查这两个作用范围。
• 使用 --no-sync 后若省略最后的 pbi report reload，Desktop 会显示过时状态： 磁盘上的 PBIR 文件是正确的，但 Desktop 内存中的模型已过时——之后在 Desktop 中进行的手动编辑可能会覆盖筛选器更改。