Databricks Medallion Architecture

Medallion architecture is a design pattern that organizes lakehouse data into three quality layers named bronze, silver, and gold. Data starts raw and messy in bronze, becomes clean and trusted in silver, and ends up shaped for business questions in gold. Each layer has one clear job, which keeps pipelines simple and easy to repair.

The Water Treatment Analogy

Think of a city water system. Rainwater arrives from rivers and lakes with mud and leaves. A treatment plant filters the water and removes impurities. A final stage adds the right minerals and delivers it to homes. Nobody drinks straight from the river, and nobody redoes the treatment at every tap.

MEDALLION LAYERS
──────────────────────────────────────────────────────────
SOURCES            BRONZE            SILVER            GOLD
(apps, files,  ──► Raw copy   ──►   Cleaned,    ──►   Business-ready
 databases)        as received      checked data      summary tables
                                                          │
                                        ┌─────────────────┼───────────────┐
                                        ▼                 ▼               ▼
                                   Dashboards       ML models     Data sharing

Bronze Layer: Raw Data

The bronze layer stores data exactly as it arrives. Engineers add a few helpful columns, such as the load time and the source file name, and leave everything else untouched. A faithful raw copy gives the team a safe starting point. Any later mistake can be fixed by rebuilding downstream layers from bronze.

-- Bronze table: raw orders as received
SELECT order_id, customer, amount, _rescued_data, load_time
FROM main.shop.bronze_orders;

Silver Layer: Clean and Trusted Data

The silver layer fixes the problems in raw data. Engineers remove duplicates, correct data types, standardize names, drop invalid rows, and join related sources. Silver tables describe real business objects, such as customers, orders, and products.

CREATE OR REPLACE TABLE main.shop.silver_orders AS
SELECT DISTINCT
       CAST(order_id AS BIGINT)       AS order_id,
       TRIM(UPPER(customer))           AS customer,
       CAST(amount AS DECIMAL(10,2))   AS amount,
       CAST(order_time AS TIMESTAMP)   AS order_time
FROM main.shop.bronze_orders
WHERE order_id IS NOT NULL
  AND amount > 0;

Data scientists and analysts often explore silver tables directly, because those tables hold detailed, reliable records.

Gold Layer: Business-Ready Data

The gold layer holds summaries and measures built for a specific purpose. A sales dashboard reads a daily revenue table. A finance report reads a monthly profit table. Gold tables stay small, fast, and easy to understand.

CREATE OR REPLACE TABLE main.shop.gold_daily_revenue AS
SELECT DATE(order_time) AS sale_date,
       COUNT(*)         AS orders,
       SUM(amount)      AS revenue
FROM main.shop.silver_orders
GROUP BY DATE(order_time);

Layer Comparison

Feature	Bronze	Silver	Gold
Data quality	Raw	Cleaned and validated	Aggregated and curated
Typical user	Data engineers	Engineers, scientists, analysts	Business users and dashboards
Row detail	Every record	Every valid record	Summaries
Change frequency	Append only	Append and update	Rebuilt or refreshed

Example: Ride Booking Company

A ride booking company receives trip events from its mobile app. The bronze table keeps every event as sent. The silver table removes test trips, fixes time zones, and links each trip to a driver. The gold tables show trips per city per hour and driver earnings per week.

RIDE COMPANY PIPELINE
──────────────────────────────────────────────────────────
Mobile app events
      │
      ▼
BRONZE: trip_events_raw        (all events, untouched)
      │  remove test trips, fix time zones, join drivers
      ▼
SILVER: trips_clean            (one row per real trip)
      │  group by city and hour, group by driver and week
      ▼
GOLD: trips_per_city_hour      GOLD: driver_weekly_earnings

Design Rules That Keep Layers Healthy

Move Data in One Direction

Data flows from bronze to silver to gold. Gold tables never write back into silver.

Keep Each Layer Focused

Cleaning belongs in silver, and business math belongs in gold. Mixed responsibilities make bugs hard to trace.

Use Delta Tables Everywhere

Delta tables give every layer transactions, history, and schema checks. A bad gold table rolls back to an earlier version in seconds.

Name Tables Clearly

Prefixes such as bronze_, silver_, and gold_ tell users the quality level at a glance. Separate schemas for each layer add the same clarity.

Common Mistakes

• Cleaning data inside bronze, which destroys the raw record.
• Building dashboards on bronze tables that contain duplicates.
• Creating too many gold tables with overlapping meaning.
• Skipping documentation, which leaves users unsure which layer to trust.

Key Points

• Medallion architecture arranges data into bronze, silver, and gold layers.
• Bronze keeps raw data, silver holds cleaned data, and gold serves business needs.
• Each layer has one purpose, which simplifies testing and repair.
• Data flows forward through the layers and never backward.
• Delta tables in every layer provide history and rollback.
• Clear names and schemas help users pick the right layer.