power-bi-docs

Power BI 文档技能

为 Power BI 语义模型生成全面的文档。

前提条件

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

模型概览

pbi --json model get       # Model metadata
pbi --json model stats     # Table/measure/column counts

编目所有对象

# Tables and their structure
pbi --json table list
pbi --json table get Sales
pbi --json table schema Sales

# All measures
pbi --json measure list

# Individual measure details
pbi --json measure get "Total Revenue" --table Sales

# Columns per table
pbi --json column list --table Sales
pbi --json column list --table Products

# Relationships
pbi --json relationship list

# Security roles
pbi --json security-role list

# Hierarchies
pbi --json hierarchy list --table Date

# Calculation groups
pbi --json calc-group list

# Perspectives
pbi --json perspective list

# Named expressions (M queries)
pbi --json expression list

# Partitions
pbi --json partition list --table Sales

# Calendar/date tables
pbi --json calendar list

将完整模型导出为 TMDL

pbi database export-tmdl ./model-docs/

这会创建整个模型的易读文本表示。

工作流：生成模型文档

运行以下命令，收集文档所需的全部信息：

# Step 1: Model overview
pbi --json model get > model-meta.json
pbi --json model stats > model-stats.json

# Step 2: All tables
pbi --json table list > tables.json

# Step 3: All measures
pbi --json measure list > measures.json

# Step 4: All relationships
pbi --json relationship list > relationships.json

# Step 5: Security roles
pbi --json security-role list > security-roles.json

# Step 6: Column details per table (loop through tables)
pbi --json column list --table Sales > columns-sales.json
pbi --json column list --table Products > columns-products.json

# Step 7: Full TMDL export
pbi database export-tmdl ./tmdl-export/

然后将这些 JSON 文件整理成 Markdown 或 HTML 文档。

工作流：数据字典

对于每个表，提取列及其类型：

# Get schema for key tables
pbi --json table schema Sales
pbi --json table schema Products
pbi --json table schema Calendar

工作流：度量值目录

创建完整的度量值清单：

# List all measures with expressions
pbi --json measure list

# Export full model as TMDL (includes all measure definitions)
pbi database export-tmdl ./tmdl-export/

区域设置管理

适用于多语言模型：

# List cultures (locales)
pbi --json advanced culture list

# Create a culture for localization
pbi advanced culture create "fr-FR"

# Delete a culture
pbi advanced culture delete "fr-FR"

最佳实践

• 始终使用 --json 标志，以获取机器可读的输出
• 除 JSON 外，还要导出 TMDL，以生成完整文档
• 将文档生成纳入 CI/CD 工作流
• 将文档与 TMDL 导出文件一同纳入版本控制
• 添加关系图（通过 pbi --json relationship list 生成）
• 记录度量值的业务逻辑，而不只是 DAX 表达式
• 使用显示文件夹按业务领域标记度量值

---

注意事项

• measure list 会返回 DAX 表达式，但不包含显示格式： 格式字符串、显示文件夹和说明位于单独的属性中。若要获取完整的度量值清单，务必将 --json measure list 与 TMDL 导出配合使用——仅查看 JSON 会遗漏作者关心的元数据。
• table schema 在架构层面会忽略计算列： 计算列会显示在 column list 中，但 table schema 只会报告存储引擎架构。仅依据 schema 编写模型文档，会导致计算列不可见。
• relationship list 不会说明非活动关系的用途： 输出中会显示 isActive: false，但原因（使用了 USERELATIONSHIP，或使用了角色扮演维度）记录在引用这些关系的度量值中。可在 TMDL 导出文件中搜索 USERELATIONSHIP，找到引用处。
• 将 --json 输出快照保存到文件会记录连接时的状态： 如果有人在命令执行期间编辑模型，生成的“文档”就会混合编辑前后的状态。请将多个目录命令放在单个 pbi transaction begin 中运行，或者针对已知模型执行 pbi disconnect / connect 后再运行这些命令。
• advanced culture list 显示的是区域设置，而不是哪些字符串已翻译： 列表中的某个区域设置，并不意味着所有标签都有对应的翻译。对比 TMDL 导出文件中各区域设置的字符串表，以查找缺失项。
• expression list 同时包含共享参数和完整的 M 查询： 两者在输出中都会显示为命名表达式。参数只是单行字面表达式——生成文档的“数据源”部分时，很容易将其误分类。