Back to Details

metabase-representation-format

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Metabase Representation Format

Metabase表示格式

Metabase represents user-created content as a tree of YAML files. Each file is one entity (a collection, card, dashboard, etc.). The format is portable across Metabase instances: numeric database IDs are replaced with human-readable names and entity IDs.
The format is defined by a spec bundled alongside this file as 
spec.md
(upstream source: the 
@metabase/representations
npm package). The same package ships a CLI (
npx @metabase/representations validate-schema
) that validates a tree of YAML files against the format.
Metabase将用户创建的内容表示为YAML文件树。每个文件对应一个实体（集合、卡片、仪表盘等）。该格式在Metabase实例之间具有可移植性：数字数据库ID被替换为人类可读的名称和实体ID。
此格式由与本文件捆绑在一起的
spec.md
规范定义（上游来源：
@metabase/representations
npm包）。同一包还提供了一个CLI工具（
npx @metabase/representations validate-schema
），用于根据格式验证YAML文件树。

Entities

实体

The format defines 11 entity types.
EntitySerDes ModelDescription
Collection
Collection
Folder-like container for organizing content. Hierarchy via 
parent_id
. Namespaces: 
null
(main), 
"snippets"
, 
"transforms"
.
Card
Card
Question, model, or metric. Holds an MBQL or native 
dataset_query
. Display types: table, bar, line, pie, scalar, etc. Card types: 
"question"
, 
"model"
, 
"metric"
.
Dashboard
Dashboard
Grid layout (24 columns) of cards with filter parameters and optional tabs. Contains 
dashcards
array for card placement and 
parameters
array for filter controls.
Document
Document
Rich text page using ProseMirror AST. Can embed cards via 
cardEmbed
nodes and link to entities via 
smartLink
nodes.
Segment
Segment
Saved filter definition scoped to a table. Definition is a pMBQL query with a single stage containing only 
source-table
and 
filters
.
Measure
Measure
Saved aggregation definition scoped to a table. Definition is a pMBQL query with a single stage containing only 
source-table
and exactly one 
aggregation
.
Snippet
NativeQuerySnippet
Reusable SQL fragment referenced in native queries via 
{{snippet: Name}}
.
Transform
Transform
Materializes query or Python script results into a database table. Source is either MBQL/native query or Python script.
TransformTag
TransformTag
Label for categorizing transforms. Built-in types: 
"hourly"
, 
"daily"
, 
"weekly"
, 
"monthly"
, or 
null
for custom.
TransformJob
TransformJob
Scheduled job (cron) that executes transforms matching specific tags.
PythonLibrary
PythonLibrary
Shared Python source file available to Python-based transforms.
该格式定义了11种实体类型。
实体SerDes模型描述
Collection
Collection
用于组织内容的类文件夹容器。通过
parent_id
实现层级结构。命名空间：
null
（主命名空间）、
"snippets"
、
"transforms"
。
Card
Card
问题、模型或度量。包含MBQL或原生
dataset_query
。展示类型：表格、柱状图、折线图、饼图、标量等。卡片类型：
"question"
、
"model"
、
"metric"
。
Dashboard
Dashboard
包含筛选参数和可选标签页的卡片网格布局（24列）。包含用于卡片布局的
dashcards
数组和用于筛选控件的
parameters
数组。
Document
Document
使用ProseMirror AST的富文本页面。可通过
cardEmbed
节点嵌入卡片，并通过
smartLink
节点链接到实体。
Segment
Segment
作用于特定表的已保存筛选器定义。定义为单阶段pMBQL查询，仅包含
source-table
和
filters
。
Measure
Measure
作用于特定表的已保存聚合定义。定义为单阶段pMBQL查询，仅包含
source-table
和恰好一个
aggregation
。
Snippet
NativeQuerySnippet
可重用SQL片段，在原生查询中通过
{{snippet: Name}}
引用。
Transform
Transform
将查询或Python脚本结果物化到数据库表中。来源可以是MBQL/原生查询或Python脚本。
TransformTag
TransformTag
用于对转换进行分类的标签。内置类型：
"hourly"
、
"daily"
、
"weekly"
、
"monthly"
，或
null
表示自定义。
TransformJob
TransformJob
执行匹配特定标签的转换的定时任务（cron）。
PythonLibrary
PythonLibrary
可供基于Python的转换使用的共享Python源文件。

Ownership and hierarchy

所有权与层级结构

Critical — folder layout is decorative. Where an entity lands in Metabase is decided entirely by its fields, not by where its YAML file sits in the tree. Moving a file without updating the fields changes nothing. Updating the fields without moving the file still works correctly. Always treat the fields below as the source of truth.
The fields that actually determine placement:
  • collection_id
     (entity_id of a collection) — places the entity in that collection. 
    null
    or omitted → root collection.
  • parent_id
     on a collection — this, and only this, sets the collection's own parent. A collection's position in the folder tree is ignored on import; without 
    parent_id
    (or with 
    parent_id: null
    ) the collection becomes a root-level collection, no matter how deep its folder is nested. To nest one collection under another, set 
    parent_id
    to the parent collection's 
    entity_id
    .
  • dashboard_id
     / 
    document_id
     on a card — nests a card under a dashboard or document. Such a card must also set 
    collection_id
    to match the parent's 
    collection_id
    . A card never sets both.
On disk, cards nested under a dashboard or document live in a subfolder next to the parent YAML (e.g. 
my_dashboard/card.yaml
sitting next to 
my_dashboard.yaml
) — but again, this is purely for human navigation; the fields are what Metabase reads.
重要提示——文件夹布局仅用于展示。 实体在Metabase中的位置完全由其字段决定，而非其YAML文件在文件树中的位置。移动文件但不更新字段不会产生任何变化。更新字段但不移动文件仍能正常工作。始终将以下字段视为权威来源。
实际决定实体位置的字段：
  • collection_id
    （集合的entity_id）——将实体放置在该集合中。
    null
    或省略则放入根集合。
  • 集合的**
    parent_id
    **——只有此字段能设置集合的父级。导入时会忽略集合在文件夹树中的位置；如果没有
    parent_id
    （或
    parent_id: null
    ），无论文件夹嵌套多深，该集合都会成为根级集合。要将一个集合嵌套在另一个集合下，需将
    parent_id
    设置为父集合的
    entity_id
    。
  • 卡片的**
    dashboard_id
    ** / 
    document_id
    ——将卡片嵌套在仪表盘或文档下。此类卡片必须同时将
    collection_id
    设置为与父级的
    collection_id
    匹配。卡片不能同时设置这两个字段。
在磁盘上，嵌套在仪表盘或文档下的卡片位于父级YAML文件旁的子文件夹中（例如
my_dashboard/card.yaml
与
my_dashboard.yaml
同级）——但同样，这仅为方便人类导航；Metabase读取的是字段内容。

Import paths

导入路径

Metabase only imports YAML from these top-level directories; anything outside is ignored:
  • collections/
    — all user content (cards, dashboards, documents, snippets, transforms, etc.), partitioned by namespace: 
    main/
    , 
    snippets/
    , 
    transforms/
    .
  • databases/
    — only the 
    segments/
    and 
    measures/
    subdirectories under each table are imported.
  • python_libraries/
    (also accepted as 
    python-libraries/
    ).
  • transforms/
    — contains 
    transform_jobs/
    and 
    transform_tags/
    .
Metabase仅从以下顶级目录导入YAML文件；其他目录的内容会被忽略：
  • collections/
    ——所有用户内容（卡片、仪表盘、文档、代码片段、转换等），按命名空间划分：
    main/
    、
    snippets/
    、
    transforms/
    。
  • databases/
    ——仅导入每个表下的
    segments/
    和
    measures/
    子目录。
  • python_libraries/
    （也支持
    python-libraries/
    ）。
  • transforms/
    ——包含
    transform_jobs/
    和
    transform_tags/
    。

serdes/meta

serdes/meta

Every entity carries a top-level 
serdes/meta
array that encodes its identity path. Each entry is 
{id, model, label?}
— 
label
is the slugified name and is present on entities keyed by NanoID. Example:
yaml
serdes/meta:
- id: NDzkGoTCdRcaRyt7GOepg
  label: my_entity_name
  model: Card
validate-schema
reads 
serdes/meta
to determine which entity type each file represents. The full rules (including nested entities and composite identity paths) are in 
spec.md
.
每个实体都带有一个顶级
serdes/meta
数组，用于编码其标识路径。每个条目为
{id, model, label?}
——
label
是名称的slug化形式，在使用NanoID作为键的实体中存在。示例：
yaml
serdes/meta:
- id: NDzkGoTCdRcaRyt7GOepg
  label: my_entity_name
  model: Card
validate-schema
会读取
serdes/meta
来确定每个文件对应的实体类型。完整规则（包括嵌套实体和复合标识路径）在
spec.md
中。

Reading the spec

阅读规范

This skill ships with a local snapshot of the spec as 
spec.md
alongside 
SKILL.md
.
Beyond the per-entity shapes summarized in this SKILL, 
spec.md
also covers: MBQL query form (stages, field references, joins, expressions, aggregations, filter/expression operators, temporal bucketing, binning), native queries and template tags (
text
, 
number
, 
date
, 
boolean
, 
dimension
, 
temporal-unit
, 
card
, 
snippet
, 
table
), visualization settings, click behavior, and dashboard/card parameters. Reach for 
spec.md
whenever edits touch any of those.
Read on demand, not eagerly. Open 
spec.md
only when you are about to read or modify content files for the entities listed above — e.g. the user asks to edit a card, add a dashcard, tweak a transform, or similar work that implies YAML edits. Do not open it at session start or for tasks unrelated to representation YAML.
If the bundled copy looks out of date with the upstream package, the skill's own 
README.md
documents how to refresh it with 
extract-spec
.
本技能随附了一份本地快照版规范
spec.md
，与
SKILL.md
放在一起。
除了本SKILL中总结的各实体结构外，
spec.md
还涵盖：MBQL查询形式（阶段、字段引用、连接、表达式、聚合、筛选/表达式运算符、时间分桶、分箱）、原生查询和模板标签（
text
、
number
、
date
、
boolean
、
dimension
、
temporal-unit
、
card
、
snippet
、
table
）、可视化设置、点击行为以及仪表盘/卡片参数。当编辑涉及这些内容时，请查阅
spec.md
。
按需阅读，无需提前通读。 仅当您要读取或修改上述实体的内容文件时才打开
spec.md
——例如用户要求编辑卡片、添加仪表盘卡片、调整转换，或其他涉及YAML编辑的类似工作。不要在会话开始时或与表示YAML无关的任务中打开它。
如果捆绑的副本与上游包版本不符，本技能的
README.md
文档说明了如何使用
extract-spec
刷新它。

Validating

验证

Validate edits with the built-in CLI:
sh
npx @metabase/representations validate-schema --folder <path>
Pass the top-level export folder, or the git repository root. The tool walks the import paths listed above, reads 
serdes/meta
on each file to pick the right validation rules, and exits non-zero on failure. Prefer running this over manually cross-checking field shapes. It's essentially instant, so invoke it whenever useful — after each edit, between edits, whenever the shape of a file feels uncertain. No reason to batch.
使用内置CLI工具验证编辑内容：
sh
npx @metabase/representations validate-schema --folder <path>
传入顶级导出文件夹或Git仓库根目录。该工具会遍历上述导入路径，读取每个文件的
serdes/meta
以选择正确的验证规则，验证失败时会返回非零退出码。优先使用此工具，而非手动检查字段结构。它几乎瞬间完成，因此只要有用就可以调用——每次编辑后、编辑过程中、对文件结构不确定时都可以。无需批量操作。

Generating entity IDs

生成实体ID

Every entity needs a 21-character NanoID for 
entity_id
. Generate one (or several) with the bundled CLI:
sh
npx @metabase/representations generate-entity-id
每个实体都需要一个21字符的NanoID作为
entity_id
。使用捆绑的CLI工具生成一个（或多个）：
sh
npx @metabase/representations generate-entity-id

→ LZfXLFzPPR4NNrgjlWDxn

→ LZfXLFzPPR4NNrgjlWDxn

npx @metabase/representations generate-entity-id --count 5
undefined
npx @metabase/representations generate-entity-id --count 5
undefined

Generating UUIDs

生成UUID

Some fields in the format require v4 UUIDs rather than NanoIDs — notably 
lib/uuid
on MBQL aggregation clauses (referenced from 
order-by
and later stages) and the 
id
on dashboard/card parameters. Generate them with:
sh
npx @metabase/representations generate-uuid
该格式中的某些字段需要v4 UUID而非NanoID——特别是MBQL聚合子句中的
lib/uuid
（在
order-by
及后续阶段中引用）以及仪表盘/卡片参数的
id
。使用以下命令生成：
sh
npx @metabase/representations generate-uuid

→ 1d4e9fdf-49ae-4fbe-ae27-05e7c6a5cfe8

→ 1d4e9fdf-49ae-4fbe-ae27-05e7c6a5cfe8

npx @metabase/representations generate-uuid --count 3
undefined
npx @metabase/representations generate-uuid --count 3
undefined