Medallion Architecture Explained: Bronze, Silver & Gold Layers

Last Updated: August 2026 | 13 min read

Quick Answer: Medallion architecture is a lakehouse design pattern that organizes data into three progressively refined layers — Bronze (raw, exactly as ingested), Silver (cleaned, validated, and conformed), and Gold (business-level aggregates and dimensional models). Data quality and business value rise at each hop, and every layer is a persisted, queryable table (Delta Lake, Apache Iceberg, or Hudi). The point is separation of concerns: raw data is never thrown away, cleaning is isolated from business logic, and each stage can be reprocessed, audited, and served independently. It is not a replacement for ETL — you use ETL/ELT jobs to move data Bronze → Silver → Gold.

Most data platforms fail slowly, not loudly. A pipeline "works" for months, then someone asks "why doesn't the revenue dashboard match finance?" — and nobody can trace the number back through the layers because raw data was overwritten and the cleaning logic is tangled with the business logic. Medallion architecture exists to prevent exactly this. In this guide you'll learn what the Bronze, Silver, and Gold layers actually do, how to build them in PySpark, where data quality checks belong, and the anti-patterns that quietly break lakehouses in production.

What is medallion architecture?

Medallion architecture is a data design pattern that structures a lakehouse into multiple layers of increasing quality — conventionally Bronze, Silver, and Gold. The name was popularized by Databricks, and the medal metaphor is deliberate: data gets "more valuable" as it is promoted up the tiers, the same way bronze, silver, and gold rank in ascending worth.

The pattern is sometimes called a multi-hop architecture, because data makes one hop per layer and is transformed at each hop. Crucially, medallion architecture is not a product you install — it is a convention for how you name, organize, and govern your tables. It sits on top of an ACID table format (Delta Lake vs Iceberg both work) and is orchestrated by ordinary ETL or ELT jobs.

The three layers, explained

The core of medallion architecture is a clear contract for what each layer is — and is not — allowed to contain. Getting this boundary right is what makes the pattern valuable.

Bronze — the raw landing zone

The Bronze layer stores source data exactly as it arrived, with no business logic applied. You ingest from Kafka topics, database CDC streams, files, or APIs and write the records verbatim, adding only ingestion metadata: the source name, an ingest timestamp, and the file or offset it came from.

Bronze is append-only and treated as an immutable historical archive. Because you never mutate it, you can always replay a downstream transformation from raw whenever logic changes or a bug is found. Keep schema enforcement light here — capture the data first, validate it on the way to Silver.

Silver — cleaned and conformed

The Silver layer holds data that has been deduplicated, type-cast, validated, and conformed into a consistent enterprise view. This is where the real engineering happens: parse the raw JSON, cast strings to proper types, drop or quarantine malformed rows, deduplicate on a business key, standardize units and enumerations, and often join several Bronze sources into clean tables that represent core entities (customers, orders, events).

Silver is the layer most analysts and data scientists should build on, because it is the first place the data is trustworthy. Apply the bulk of your data quality tests at the Bronze → Silver boundary, and handle history here too — Slowly Changing Dimension (SCD Type 2) tracking usually lives in Silver.

Gold — business-level and consumption-ready

The Gold layer contains curated, aggregated tables built for a specific business purpose. These are your star-schema facts and dimensions, pre-computed metrics, and denormalized tables tuned for a dashboard, a report, or a machine-learning feature set. Gold tables are shaped by consumption, not by the source — one Silver table often fans out into several Gold tables for different teams.

Because Gold is where numbers get published, add a final round of business-rule and reconciliation checks here so a KPI never ships wrong.

Layer responsibilities at a glance

This is the table to bookmark — it captures the contract for each layer in one place.

Why use medallion architecture?

The pattern's value is separation of concerns: each layer has one job, so failures are isolated and traceable. Concretely, it gives you:

• Reprocessability. Because Bronze is never destroyed, you can rebuild Silver and Gold from raw whenever logic changes or a bug is fixed — no re-ingestion from the source needed. This pairs naturally with idempotent pipelines and safe backfills.
• Debuggability. When a Gold number looks wrong, you trace it back one hop at a time — Gold → Silver → Bronze — instead of guessing inside one giant transformation.
• Clear ownership and trust. "Build on Silver" becomes a governance rule everyone understands; nobody accidentally reports off raw, half-cleaned data.
• Incremental, cheap refinement. Each hop can run on its own schedule and only process new or changed data via MERGE, which keeps compute costs down.
• Format independence. The convention rides on Delta, Iceberg, or Hudi, so you are not locked into one vendor.

How to build medallion layers in PySpark

Here is the shape of a real multi-hop pipeline. The example uses Delta Lake syntax, but the same structure works on Apache Iceberg by swapping the format.

# ── Bronze: ingest raw, add metadata, append only ──────────────────
from pyspark.sql import functions as F

raw = (spark.read.format("json").load("s3://landing/events/"))

(raw
    .withColumn("_ingest_ts", F.current_timestamp())
    .withColumn("_source_file", F.input_file_name())
    .write.format("delta").mode("append")
    .saveAsTable("bronze.events"))

# ── Silver: clean, cast, dedupe, validate, then MERGE upsert ───────
from delta.tables import DeltaTable

bronze = spark.table("bronze.events")

clean = (bronze
    .withColumn("event_ts", F.to_timestamp("event_time"))
    .withColumn("user_id",  F.col("user_id").cast("long"))
    .filter(F.col("user_id").isNotNull())               # drop bad keys
    .dropDuplicates(["event_id"]))                       # dedupe on business key

(DeltaTable.forName(spark, "silver.events").alias("t")
    .merge(clean.alias("s"), "t.event_id = s.event_id")
    .whenNotMatchedInsertAll()
    .whenMatchedUpdateAll()
    .execute())

# ── Gold: aggregate into a business metric table ──────────────────
gold = (spark.table("silver.events")
    .groupBy(F.to_date("event_ts").alias("day"), "country")
    .agg(F.countDistinct("user_id").alias("daily_active_users"),
         F.count("*").alias("event_count")))

(gold.write.format("delta").mode("overwrite")
    .partitionBy("day")
    .saveAsTable("gold.daily_active_users"))

Notice the write patterns differ by layer — append for Bronze, MERGE for Silver, overwrite/MERGE for Gold — exactly as the responsibilities table prescribes. Orchestrate the three hops with a tool like Airflow or dbt, running each as a dependent task.

Medallion architecture vs traditional staging

Traditional ETL uses transient staging tables that are truncated each run; medallion uses persisted, queryable layers that are kept. That single difference — persistence — is what unlocks reprocessing, auditing, and time travel.

Common mistakes (and how to avoid them)

• Putting business logic in Bronze. The moment you filter, join, or reshape on the way into Bronze, you lose your raw archive and your ability to reprocess. Bronze gets metadata only.
• Letting analysts build on Bronze. If people query raw data directly, "trust" has no meaning. Make Silver the published contract and enforce it.
• Collapsing Silver and Gold by habit. Cleaning and business modeling are different jobs; merging them recreates the tangled transformation medallion was meant to fix.
• Skipping quality gates between layers. A layer boundary is the natural place for a test. No gate means bad data silently promotes upward.
• Over-engineering with too many hops. Five layers for a three-table pipeline is cargo-culting. Match layers to complexity.
• Ignoring small files and partitioning. Append-heavy Bronze and MERGE-heavy Silver both generate small files fast; schedule compaction or your read performance decays.

From the field: On a monitoring platform I worked on (Telemetrix), the biggest reliability win wasn't a new tool — it was moving deduplication and schema-casting out of the ingestion job and into a dedicated Bronze → Silver step. Ingestion got simpler and never dropped data again, and when a parsing bug slipped through, we rebuilt three months of Silver from Bronze in an afternoon instead of re-pulling from the source. That is the entire promise of medallion architecture in one incident.

See how SolutionGigs can help

Designing a lakehouse that stays trustworthy as it grows is where most teams stumble — the pattern is simple, but the boundaries, quality gates, and compaction strategy take real experience to get right. If you're building or fixing a data platform, the vetted data engineers on solutiongigs.in have shipped exactly these architectures on Spark, Delta, and Iceberg. Post your project free and get matched with someone who's done it before.

Frequently Asked Questions

What is medallion architecture in simple terms?

Medallion architecture is a way of organizing a data lakehouse into three quality tiers — Bronze (raw), Silver (cleaned), and Gold (business-ready) — so data gets more trustworthy and more useful as it moves up. Each tier is a real table you can query, and raw data is always preserved so you can rebuild everything downstream if needed.

Why is it called medallion architecture?

It is named after Olympic-style medals — bronze, silver, and gold — which rank in ascending value. The metaphor captures the core idea that data becomes progressively more valuable and refined as it is promoted through the layers. Databricks popularized both the name and the pattern for lakehouse platforms.

Is medallion architecture only for Databricks?

No. Databricks coined the term and it pairs naturally with Delta Lake, but the pattern is vendor-neutral. You can implement identical Bronze, Silver, and Gold layers on Apache Iceberg or Apache Hudi, on any Spark platform, on AWS, GCP, or Azure. It is a design convention, not a proprietary feature.

How many layers should a medallion architecture have?

Three is the convention, but the right answer is "as many as your complexity needs." Simple pipelines sometimes merge Silver and Gold; complex enterprises add sub-layers within Silver. The non-negotiable principles are that raw data is preserved and that cleaning is separated from business logic — not a fixed layer count.

What is the difference between medallion architecture and a data warehouse?

A data warehouse is a system for storing and querying structured, modeled data; medallion architecture is a pattern for how you refine data on the way to being consumption-ready. In a modern lakehouse, the Gold layer often is your warehouse-style modeled data, while Bronze and Silver hold the raw and cleaned stages a classic warehouse would keep hidden or discard.

Can I use medallion architecture for streaming data?

Yes. Streaming fits medallion cleanly: land events in Bronze via Structured Streaming, clean and dedupe into Silver with stateful exactly-once processing, and materialize Gold aggregates with windowed metrics. Many teams run the same three layers in both batch and streaming modes over the same tables.

Conclusion

Medallion architecture endures because it encodes one hard-won lesson: keep your raw data, and never mix cleaning with business logic. Bronze preserves the truth, Silver makes it trustworthy, and Gold makes it useful — and because every layer is a persisted lakehouse table, you gain reprocessing, auditing, and time travel almost for free. It is not magic and it is not a product; it is a discipline for building data platforms that stay debuggable as they scale.

Start simple: three layers, one quality gate between each, append into Bronze, MERGE into Silver, aggregate into Gold. Add sub-layers only when real complexity demands them. Whether you're standing up a new lakehouse or untangling one that's grown brittle, this pattern will make your data both easier to trust and easier to fix. Ready to build it right? Get matched with a vetted data engineer on solutiongigs.in — it's free to post your project.

Mohammed Yaseen

Founder, SolutionGigs

Mohammed builds production data platforms on Spark, Delta Lake, and Apache Iceberg, and has designed medallion-style lakehouses for streaming and batch workloads. LinkedIn →