Medallion Architecture

Overview

Medallion architecture, popularized by Databricks, is a layering convention for lakehouse tables. Bronze is raw, silver is validated and conformed, gold is curated for consumption. Each layer has a defined quality bar and owner.

How it works

Ingestion appends records exactly as received, plus load time and source file. Silver jobs read bronze incrementally, apply rules, and merge into keyed tables. Gold jobs aggregate for dashboards, ML features or data products.

sources --> BRONZE (raw, append-only)
        --> SILVER (deduped, typed, validated)
        --> GOLD (aggregates, star schemas)

A typical silver step in SQL:

MERGE INTO silver.orders s
USING (SELECT * FROM bronze.orders WHERE _load_ts > :watermark) b
ON s.order_id = b.order_id
WHEN MATCHED THEN UPDATE SET *
WHEN NOT MATCHED THEN INSERT *;

Quality rules, such as not-null keys or valid ranges, run between layers. Failing records go to a quarantine table instead of blocking the pipeline.

Pitfalls

• Treating layers as a rigid three-hop rule: some domains need extra intermediate tables, others fewer.
• No contracts between layers: schema drift in bronze silently breaks silver.
• Business logic scattered in gold: duplicate definitions of revenue or active user emerge. Centralize metrics in shared silver or a semantic layer.
• Open access to bronze: raw tables often hold sensitive fields; apply access control per layer.
• Unbounded retention of every layer wastes money; set lifecycle rules.

Key takeaways

• Bronze preserves truth, silver provides trusted entities, gold serves use cases.
• Incremental merges keep layers cheap to maintain.
• Gate promotion with automated quality checks and quarantine bad rows.
• Layers are a convention, so enforce them with naming, permissions and ownership.