SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场metabase-database-metadata

metabase-database-metadata

数据与分析

查看项目

更新于 10-15 09:18

技能介绍

用途

Metabase Database Metadata 用于以 YAML 文件树的形式表示 Metabase 实例中同步的数据库元数据，包括数据库、表与字段。该格式面向差异对比设计：不包含数字 ID，外键使用自然键元组而非数据库标识符，便于版本管理与人工阅读。

主要能力

  • 以 YAML 树描述数据库、表、字段三类实体。
  • 外键使用自然键元组：数据库外键为数据库名称字符串；表外键为 [database, schema_or_null, table]；字段外键为 [database, schema_or_null, table, field, ...nested_field_names]。
  • 字段级外键通过 parent_id（嵌套字段父级）与 fk_target_field_id（外键列引用的主键）表示。
  • 字段类型属性包括：database_type（驱动返回的原生类型字符串）、base_type（与原生类型对应的 Metabase 类型）、effective_type（查询时 Metabase 实际使用的类型，仅在与 base_type 不同时输出）、coercion_strategy（从 base_type 生成 effective_type 的规则）、semantic_type（业务域标签，如 type/PK、type/FK、type/Email 等）。
  • 随附 spec.md 规范快照，包含完整类型层级与可用强制转换策略。
  • 提供 npm 包 @metabase/database-metadata，其 CLI 可将 Metabase 导出的原始 JSON 转换为规范描述的 YAML 树。

使用方式

目录布局

所有元数据位于顶层 .metadata/ 目录：

  • .metadata/databases/ — YAML 树，代理的规范数据源，用于理解模式、列、类型与外键关系。
  • .metadata/table_metadata.json — 从 Metabase 实例导出的原始 JSON，可能达数 MB 或数 GB，包含扁平的 databases / tables / fields 数组。不应打开、检索或传给工具，仅作为提取器的输入。

.metadata/ 目录应加入 .gitignore。在大型数仓上提取的元数据可达数 GB，提交会使仓库难以使用。

首次设置

不要在会话开始时主动执行以下步骤。仅在用户明确要求获取元数据、设置工作流，或任务明显需要了解数据库模式时（例如“针对 ORDERS 写查询”“描述有哪些表”）才执行。

  1. 确保 .metadata/ 已加入 .gitignore。读取仓库的 .gitignore 并确认其中包含 .metadata/。若没有，先询问用户再修改。

  2. 从 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

若用户未提供凭据，先询问再执行调用。

  1. 提取。在 .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，以免残留陈旧文件。

实体与文件

三类实体，两种文件：

  • 数据库：文件 .metadata/databases/{db}/{db}.yaml，表示一个已连接的数据源（Postgres、MySQL、BigQuery 等），以名称标识。
  • 表：文件 .metadata/databases/{db}/schemas/{schema}/tables/{table}.yaml（无模式数据库为 .../tables/{table}.yaml），表示物理表或视图，包含内联的 fields 数组。
  • 字段：嵌套在表 YAML 中，无独立文件，表示列，包含 base_type、database_type，以及可选的 effective_type、semantic_type、coercion_strategy、parent_id、fk_target_field_id。

阅读规范

本技能随附规范本地快照 spec.md，与 SKILL.md 并列。按需阅读，不要预先打开。仅当需要 SKILL.md 摘要之外的细节时（例如完整的 base-type / semantic-type 层级、全部强制转换策略列表、确切的文件夹路径规则）才打开 spec.md。不要在会话开始时打开，也不要为与元数据树无关的任务打开。若随附副本与上游包相比显得过时，技能自身的 README.md 记录了如何用 extract-spec 刷新。

适用场景

  • 需要了解数据库模式、列、类型与外键关系以编写查询。
  • 需要以差异友好的方式对 Metabase 元数据进行版本管理。
  • 需要将 Metabase 导出的原始 JSON 转换为可读的 YAML 树。

限制

  • 原始 JSON 可能达数 GB，不应直接打开、检索或传给工具。
  • .metadata/ 目录应加入 .gitignore，否则可能使仓库难以使用。
  • 会话开始时不应主动抓取元数据，仅在用户明确要求或任务需要时触发。
  • 刷新仅限用户发起，不得静默刷新。
  • 导出端点需要 API 密钥与基础 URL，未提供时需先询问用户。
  • 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。