Medallion Architecture: Bronze, Silver and Gold Layers

1. What is medallion architecture?

Medallion architecture is a data design pattern that organizes your lakehouse into three progressive layers: bronze (raw), silver (cleaned), and gold (business-ready). Each layer improves data quality and moves closer to business value. The medal names carry the ordering and nothing else: a bronze table is not lower quality by accident, it is raw on purpose.

The pattern assumes a lakehouse underneath it: one storage layer, open table formats, and engines reading the same files. If that part is not settled yet, the data lakehouse architecture guide covers the storage and table format decisions that bronze, silver and gold sit on top of. Teams coming from a classic warehouse usually compare both against the data warehouse design guide before committing.

When to use medallion architecture:

2. Bronze vs silver vs gold: what goes in each layer

The shortest way to tell the three apart is by the question each one answers. Bronze answers what arrived, byte for byte, with no opinion about whether it is correct. Silver answers what is true: one row per business entity, types resolved, duplicates gone, keys joined across sources. Gold answers what the business asked, in the shape of a specific dashboard, metric or model. Each layer has its own purpose, owner, quality bar and access rules.

Key principles for each transition:

Each transition is a pipeline job in its own right. Sketching both hops as a data pipeline diagram before writing code surfaces grain mismatches and missing dedup keys while they are still cheap to fix.

3. What the bronze layer is for

Bronze exists to be a replayable record of what each source system sent. It is your "data lake" in the truest sense: everything lands here, exactly as it arrived. The goal is durability and traceability, not cleanliness. If you can drop every silver and gold table and rebuild the platform from bronze alone, bronze is doing its job.

Bronze table structure:

-- Bronze: raw_orders
CREATE TABLE bronze.raw_orders (
  -- Ingestion metadata
  _ingested_at      TIMESTAMP,
  _source_file      STRING,
  _batch_id         STRING,

  -- Raw payload (store as-is)
  raw_payload       STRING,  -- JSON string, unparsed

  -- Or if structured:
  order_id          STRING,  -- Not validated yet
  customer_id       STRING,
  order_date        STRING,  -- Could be any format
  amount            STRING,  -- Could have currency symbols
  status            STRING
)
PARTITIONED BY (_ingested_at::DATE)

4. What the silver layer is for

Silver is where the real work happens. This is your "single source of truth" for cleaned, validated, entity-level data. Think of it as enterprise-grade data. And if upstream teams keep breaking your silver models with surprise schema changes, formalize the expectations as data contracts rather than patching the cleanup logic every sprint.

Silver layer responsibilities:

-- models/silver/orders.sql
WITH source AS (
  SELECT * FROM {{ source('bronze', 'raw_orders') }}
  WHERE _ingested_at >= CURRENT_DATE - INTERVAL '7 days'
),

deduplicated AS (
  SELECT *,
    ROW_NUMBER() OVER (
      PARTITION BY order_id
      ORDER BY _ingested_at DESC
    ) as row_num
  FROM source
),

cleaned AS (
  SELECT
    -- Cast and validate types
    CAST(order_id AS BIGINT) AS order_id,
    CAST(customer_id AS BIGINT) AS customer_id,

    -- Standardize date format
    TO_DATE(order_date, 'YYYY-MM-DD') AS order_date,

    -- Clean amount (remove currency symbols)
    CAST(REGEXP_REPLACE(amount, '[^0-9.]', '') AS DECIMAL(10,2)) AS amount,

    -- Normalize status to uppercase
    UPPER(TRIM(status)) AS status,

    -- Keep lineage
    _ingested_at,
    _batch_id
  FROM deduplicated
  WHERE row_num = 1
    AND order_id IS NOT NULL
)

SELECT * FROM cleaned

Two details in that model are the ones teams get wrong. The dedup window is a rolling seven days rather than the current batch, because a source that resends yesterday with a correction has to overwrite yesterday, not sit next to it. And the ingestion metadata survives into silver, which is what lets you trace a wrong number in a dashboard back to the file it came from. Keeping those columns is the cheapest lineage you will ever have.

5. What the gold layer is for

Gold is where business value lives. These are the tables your stakeholders actually query. Think dimensional models, metrics, and use-case-specific aggregates. A gold table is allowed to be redundant with another gold table, because each one is shaped for its consumer rather than for generality.

Common gold layer patterns:

-- models/gold/fact_orders.sql
WITH orders AS (
  SELECT * FROM {{ ref('silver_orders') }}
),

customers AS (
  SELECT * FROM {{ ref('dim_customers') }}
),

products AS (
  SELECT * FROM {{ ref('dim_products') }}
)

SELECT
  -- Surrogate key
  {{ dbt_utils.generate_surrogate_key(['o.order_id']) }} AS order_key,

  -- Foreign keys to dimensions
  c.customer_key,
  p.product_key,
  d.date_key,

  -- Degenerate dimensions
  o.order_id,
  o.status,

  -- Measures
  o.quantity,
  o.unit_price,
  o.quantity * o.unit_price AS line_total,
  o.discount_amount,

  -- Audit columns
  o._ingested_at AS source_loaded_at,
  CURRENT_TIMESTAMP AS dbt_loaded_at

FROM orders o
LEFT JOIN customers c ON o.customer_id = c.customer_id
LEFT JOIN products p ON o.product_id = p.product_id
LEFT JOIN {{ ref('dim_date') }} d ON o.order_date = d.date_day

6. Medallion architecture naming conventions

The rule that makes everything else easier: the layer goes in the schema, the entity goes in the table, and the environment goes in the catalog or database. That gives you names like prod.silver.orders and dev.silver.orders, so the same SQL runs in both, and it lets you grant permissions on a whole layer in one statement instead of enumerating tables.

The rules worth writing down:

Folder and database structure:

# Typical naming convention
catalog/
├── bronze/
│   ├── raw_orders
│   ├── raw_customers
│   ├── raw_products
│   └── raw_events
├── silver/
│   ├── orders           # Cleaned orders
│   ├── customers        # Cleaned customers
│   ├── products         # Cleaned products
│   └── events           # Cleaned events
├── gold/
│   ├── dim_customers    # Dimension: customers
│   ├── dim_products     # Dimension: products
│   ├── dim_date         # Dimension: date
│   ├── fact_orders      # Fact: orders
│   └── agg_daily_sales  # Aggregate: daily sales
└── quarantine/
    ├── orders_failed    # Records that failed validation
    └── events_failed

7. What the Databricks documentation says about bronze, silver and gold

Databricks coined the term and publishes the definition in two places: a glossary entry on databricks.com and the lakehouse architecture section of the product documentation. The definition itself is deliberately short. Medallion architecture is described as a data design pattern used to logically organize data in a lakehouse, with the goal of incrementally and progressively improving the structure and quality of the data as it flows through bronze, then silver, then gold. Everything past that sentence in the docs is guidance rather than rule, which is why implementations differ so widely and still call themselves medallion.

On Databricks specifically, the pieces that carry the pattern are Unity Catalog for the three-level catalog.schema.table namespace, Auto Loader for incremental file ingestion into bronze, and Delta Lake MERGE or streaming tables for the two hops. Because Unity Catalog has three levels, the layer can live either at the catalog level or at the schema level, and both layouts appear in the Databricks examples. The Unity Catalog structure guide walks through that decision, and the Databricks platform diagram guide covers documenting the result.

8. Bronze, silver and gold on Snowflake, BigQuery and open lakehouses

Medallion works on any modern data platform. None of them except Databricks has a native notion of layers, which is good news: the layers are just containers you create, and every platform gives you a way to secure and bill them separately.

Snowflake

Two layouts are common: three databases (RAW, SILVER, GOLD) when you want separate storage grants and separate cost attribution, or one database with three schemas when cross-layer queries are frequent. Bronze is usually loaded by Snowpipe or an EL tool into a table with a VARIANT column, which keeps the JSON payload intact and still queryable, so you get bronze fidelity without giving up SQL access. The hops are built with streams and tasks, or with dynamic tables when you would rather declare the target state than orchestrate it. One warning worth repeating: Time Travel is not bronze. Its retention tops out at 90 days on the higher editions and one day on Standard, so it covers a bad deploy last Tuesday, not a reprocessing request for last year. The Snowflake architecture guide covers warehouse sizing per layer.

BigQuery

Layers are datasets, and the dataset is also the unit of location and access control, so one dataset per layer per region falls out naturally. Bronze commonly uses ingestion-time partitioning so a reprocessing job can target the exact load window, and external tables over Cloud Storage let you keep untouched files as a landing zone in front of bronze without loading them twice. Gold is where partitioning and clustering earn their keep, since BigQuery bills the bytes each dashboard query scans.

Open lakehouse on object storage

With Iceberg, Hudi or Delta on S3, GCS or ADLS, the layers are prefixes plus catalog namespaces, and a catalog (Glue, Nessie, Polaris or another REST catalog) is what makes them tables rather than folders. The pattern to avoid is bronze as loose Parquet with no table format, because you lose atomic writes and schema evolution exactly where late and malformed data arrives.

9. Medallion architecture in dbt: staging, intermediate and marts

dbt has its own three-part convention (staging, intermediate, marts) and it maps onto medallion cleanly once you accept one thing: dbt does not build bronze. An ingestion tool such as Fivetran, Airbyte, Auto Loader or Snowpipe lands bronze, and dbt declares it as a source. Everything dbt builds starts at silver.

# models/staging/_sources.yml
sources:
  - name: bronze
    schema: bronze
    loaded_at_field: _ingested_at
    freshness:
      warn_after: {count: 12, period: hour}
      error_after: {count: 24, period: hour}
    tables:
      - name: raw_orders
      - name: raw_customers

# dbt_project.yml
models:
  my_platform:
    staging:
      +schema: silver
      +materialized: view
    intermediate:
      +schema: silver
      +materialized: ephemeral
    marts:
      +schema: gold
      +materialized: table

One gotcha with that config: by default dbt builds a custom schema name by concatenating the target schema and the value you set, so +schema: gold produces analytics_gold rather than gold. If you want the layer names bare, override the generate_schema_name macro in your project. It is a ten-line macro and it is the standard first customization of a medallion dbt project.

The rest of the project conventions, folder layout, model contracts and CI, are in the dbt best practices guide.

10. How to draw a medallion architecture diagram

A medallion diagram is read by two audiences: an engineer who needs to know which job writes which table, and a stakeholder who needs to know where a number comes from. One picture can serve both if it follows four rules.

This is the part Datadef was built for. Describe the platform in a sentence, naming the sources, the engine and the marts, and it draws the three layers as labeled zones with the real Databricks, Snowflake, dbt, Fivetran, Airflow and Kafka icons rather than generic boxes, then leaves it on a canvas you can edit. Zone names in the request are treated as a specification, so asking for one zone per medallion layer gives you exactly that. The result can be published as a live embed in a README, Notion page or Confluence page, where the image follows the canvas instead of being a screenshot that ages. The prompter at the top of this page is already seeded with a medallion lakehouse, and the medallion generator is the same thing with a blank description.

For the wider question of keeping a lakehouse diagram accurate over time rather than drawing it once, see how to document a lakehouse.

11. Medallion architecture best practices

The checks that belong at each boundary, and what to alert on rather than log, are in the data quality best practices guide.

12. Frequently asked questions