metabase-database-metadata

Metabase 数据库元数据格式

Metabase 将数据库元数据——已同步的数据库、它们的表和字段——表示为一棵 YAML 文件树。文件便于比较差异：完全省略数字 ID，外键则使用自然键元组，例如 ["Sample Database", "PUBLIC", "ORDERS"]，而不是数据库标识符。

此格式由与本文件一同提供的规范定义，文件名为 spec.md（上游来源：metabase/database-metadata）。同一项目还提供了一个 CLI（npm 上的 @metabase/database-metadata），可将从 Metabase 实例导出的原始 JSON 转换为规范所描述的 YAML 文件树。

标准目录结构

项目的所有元数据都存放在顶层 .metadata/ 目录下：

• .metadata/databases/ — YAML 文件树。**这是 Agent 的权威数据源。**读取这些文件以了解架构、列、类型和外键关系。
• .metadata/table_metadata.json — 从 Metabase 实例导出的原始 JSON。可能是数 MB（甚至数 GB）的 JSON，包含扁平的 databases / tables / fields 数组。**切勿打开、搜索或将其传给工具。**它仅作为提取器的输入。

.metadata/ 目录应加入 Git 忽略列表。对于大型数据仓库，提取出的元数据可能达到数 GB；提交它会让仓库变得臃肿，甚至无法使用。

首次设置

会话开始时，不要主动运行以下任何步骤。只有当用户明确要求获取元数据、设置工作流，或提出明显需要了解数据库架构的问题（例如“针对 ORDERS 编写查询”“描述现有哪些表”）时，才运行这些步骤。

触发设置后：

1. 确保 .metadata/ 已加入 Git 忽略列表

读取仓库的 .gitignore，确认其中列出了 .metadata/。如果没有，修改 .gitignore 前先询问用户，例如：

.metadata/ 未列入 .gitignore。提交它会使仓库变得臃肿（元数据可能达到数 GB）。要我将它加入吗？

只有在用户确认后，才能编辑 .gitignore。

2. 从 Metabase 导出元数据

通过调用 Metabase 实例上的 POST /api/ee/serialization/metadata/export，获取 table_metadata.json，并将响应写入 .metadata/table_metadata.json。该端点接受三个布尔查询参数，用于选择是否包含相应部分——它们的默认值均为 false，因此请求必须明确指定所需部分：

• with-databases — 包含 databases 数组。
• with-tables — 包含 tables 数组。
• with-fields — 包含 fields 数组。

完整导出通常将这三个参数都设为 true。用户会提供基础 URL 和 API 密钥（例如通过 METABASE_URL 和 METABASE_API_KEY 环境变量）：

mkdir -p .metadata
curl -sf -X POST "$METABASE_URL/api/ee/serialization/metadata/export?with-databases=true&with-tables=true&with-fields=true" \
  -H "X-API-Key: $METABASE_API_KEY" \
  -o .metadata/table_metadata.json

如果用户尚未提供凭据，请先询问，再发起调用。

3. 提取

将 .metadata/table_metadata.json 放置到位后：

rm -rf .metadata/databases
npx @metabase/database-metadata extract-table-metadata .metadata/table_metadata.json .metadata/databases

然后读取 .metadata/databases/ 下的 YAML 文件树，以回答用户的问题。

会话开始时的行为

会话开始时，不要运行任何获取数据的命令。只查看磁盘上的内容：

• 如果 .metadata/table_metadata.json 和 .metadata/databases/ 都存在，假定文件树足够新并直接使用。不要重新获取。
• 如果文件树缺失或不完整，在用户提出需要它的请求前不要做任何操作——之后再按上述首次设置流程执行。

如果使用过程中发现文件树似乎过时或不一致，请告知用户，让他们决定是否重新获取。绝不要静默刷新。

刷新（仅由用户发起）

如果用户明确要求刷新元数据，请重新运行导出调用，覆盖 .metadata/table_metadata.json，然后重新运行提取步骤。重新提取前务必先删除 .metadata/databases，以免遗留过时文件。

实体

三种实体类型，两种文件类型：

实体	文件	描述
Database	.metadata/databases/{db}/{db}.yaml	已连接的数据源（Postgres、MySQL、BigQuery 等）。按名称标识。
Table	.metadata/databases/{db}/schemas/{schema}/tables/{table}.yaml（或无 schema 的数据库使用 .../tables/{table}.yaml）	物理表或视图。包含一个 fields 数组，其中内联嵌套了所有列。
Field	（嵌套在 Table YAML 中，无单独文件）	一列。包含 base_type、database_type，以及可选的 effective_type、semantic_type、coercion_strategy、parent_id、fk_target_field_id。

外键

外键使用自然键元组，而非数字 ID：

• Database 外键：数据库名称（字符串）——例如 "Sample Database"
• Table 外键：[database, schema_or_null, table] ——例如 ["Sample Database", "PUBLIC", "ORDERS"]
• Field 外键：[database, schema_or_null, table, field, ...nested_field_names] ——例如，对于 JSON 展开的列 DATA.user.name，为 ["Sample Database", "PUBLIC", "EVENTS", "DATA", "user", "name"]

字段级外键以 parent_id（嵌套字段的父级）和 fk_target_field_id（外键列引用的主键）形式出现。

字段上的类型属性

• database_type ——驱动程序提供的原生类型字符串（BIGINT、VARCHAR、JSONB 等）。因数据库而异。
• base_type ——与原生类型对应的 Metabase 类型（type/BigInteger、type/Text、type/Structured 等）。
• effective_type ——Metabase 在查询时将该列视为的类型。仅当它与 base_type 不同时才会输出（即配置了强制类型转换时）。
• coercion_strategy ——根据 base_type 生成 effective_type 的规则（例如 Coercion/ISO8601->DateTime、Coercion/UNIXMilliSeconds->DateTime）。
• semantic_type ——业务领域标签（type/PK、type/FK、type/Email、type/Category、type/Latitude 等）。用于驱动 UI 和部分分析行为。

完整的类型层级和可用的强制类型转换策略请参阅随附的规范。

阅读规范

此技能附带一份规范的本地快照，文件名为 spec.md，与 SKILL.md 位于同一目录。

按需阅读，不要提前读取。 只有在确实需要了解 SKILL.md 摘要之外的细节时，才打开 spec.md——例如完整的基础类型／语义类型层级、完整的强制类型转换策略列表，或精确的文件夹路径规则。不要在会话开始时打开，也不要用于与元数据树无关的任务。

如果随附副本似乎落后于上游软件包，技能自身的 README.md 会说明如何使用 extract-spec 刷新它。