Metabase Database Metadata Format

Metabase represents database metadata — synced databases, their tables, and their fields — as a tree of YAML files. Files are diff-friendly: numeric IDs are omitted entirely, and foreign keys use natural-key tuples like ["Sample Database", "PUBLIC", "ORDERS"] instead of database identifiers.

The format is defined by a specification bundled alongside this file as spec.md (upstream source: metabase/database-metadata). The same project ships a CLI (@metabase/database-metadata on npm) that converts the raw JSON exported from a Metabase instance into the YAML tree described by the spec.

Canonical layout

All metadata for a project lives under a top-level .metadata/ directory:

.metadata/databases/ — the YAML tree. This is the canonical source for the agent. Read these files to understand the schema, columns, types, and FK relationships.
.metadata/table_metadata.json — the raw JSON exported from the Metabase instance. Potentially multi-megabyte (or multi-gigabyte) JSON with flat databases / tables / fields arrays. Never open, grep, or pass it to tools. It exists only as input to the extractor.

The .metadata/ directory should be gitignored. On large warehouses the extracted metadata can reach gigabytes — committing it would make the repo painful or unusable.

First-time setup

Do not run any of the steps below proactively at session start. Only run them when the user explicitly asks to fetch metadata, set up the workflow, or requests something that plainly requires knowledge of the database schema (e.g. "write a query against ORDERS", "describe what tables exist").

metabase-database-metadata