Medallion architecture

Teams adopt a medallion architecture when a data lake has become a place where nobody can say which copy of a table is safe to use. Naming three levels of refinement, and agreeing what each one promises, tells every reader where to look and every pipeline where to write.

Why use a medallion architecture?

• A contract per layer. Bronze is raw, silver is clean, gold is ready to report on. A table’s location tells you how far to trust it.
• Reprocessing without re-ingesting. The raw data stays in bronze, so fixing a bug in a transformation is a rerun, not a request to the source team.
• Quality improves in steps. Each hop does one kind of work, which keeps jobs small and tests specific.
• A traceable path. Every gold number can be followed back through silver to the bronze rows it came from, which is data lineage you get from the structure.

What are the three layers of a medallion architecture?

The diagram at the top of this page shows the layers inside one lakehouse. Data moves left to right and is never edited in place.

• Bronze. Raw data exactly as it arrived, appended and never updated, with metadata such as the load time and the source file. Nothing is cleaned. Only pipelines and data engineers read it.
• Silver. Cleaned and conformed data: duplicates removed, types cast, values validated and keys standardized, so the same customer has one id whichever source it came from. There is usually one table per business entity.
• Gold. Tables built for a specific use: aggregates, star schemas and feature tables, with metric definitions the business has agreed. Dashboards and reports read from here.

Layer	State of the data	Example tables	Main readers
Bronze	Raw, as ingested	orders_raw, events_raw	Pipelines, data engineers
Silver	Cleaned, deduplicated, conformed	orders, customers	Data scientists, ad hoc analysis
Gold	Aggregated and modeled per use case	daily_revenue, customer_360	Dashboards, reports, analysts

How does data move through the layers?

Follow five order records through the example. They arrive from the source as text, and bronze stores all five, including order 1041 twice and an order whose amount is “N/A”. Keeping the bad rows is deliberate. Bronze is the record of what was received.

The silver job reads bronze and applies the rules every downstream user would otherwise write for themselves. It keeps one row per order id, casts the amount to a decimal and normalizes the country codes. The row that fails validation is written to a quarantine table for review, not dropped silently. Three valid rows land in silver.

The gold job reads silver and answers one question, revenue by country. Two orders from the US total 125.40 and one from Germany totals 120.00. A different question gets its own gold table from the same silver rows.

Each arrow is a job that can be rerun, tested and scheduled on its own, and most run incrementally, processing only the rows that arrived since the last run.

How does medallion architecture compare with data warehouse layers?

Medallion layer	Warehouse layer	Purpose
Bronze	Staging	Raw copies of the sources
Silver	Core	Cleaned, integrated business entities
Gold	Data marts	Tables shaped for one audience

The idea is the same one a data warehouse has always used. The difference is where the layers live. Medallion architecture grew up on the lakehouse, where all three layers are files in object storage under an open table format such as Delta Lake or Apache Iceberg, and bronze can hold JSON, logs and documents as easily as rows.

It is a layering convention, not a product or a pipeline design. How data gets into bronze and between the layers is the job of an ETL pipeline, and how the layers fit with ingestion and serving is the wider data pipeline architecture.

How do you implement a medallion architecture?

1. Write down each layer’s contract. What is guaranteed, who may read it and which jobs may write to it.
2. Land sources in bronze unchanged. Append only, with the load time and source recorded.
3. Build silver per entity. Deduplicate, cast, validate and conform keys, and quarantine what fails.
4. Build gold per use case. Read from silver only, with definitions agreed with the people who use the numbers.
5. Test at each boundary. Uniqueness, nulls, row counts and freshness, before the next layer runs.
6. Control access by layer. Bronze often holds raw personal data, so restrict it and open gold widely.
7. Draw it. A data flow diagram of sources, layers and consumers is the quickest way to show a new team where their tables belong.

What are common medallion architecture mistakes?

• Cleaning on the way into bronze. Once the raw record is gone, a transformation bug cannot be undone.
• Gold built straight from bronze. Every team then repeats the same cleaning, slightly differently.
• Business logic in silver. Silver should stay true to the sources and reusable. Metric definitions belong in gold.
• A gold table for every request. Hundreds of near-duplicate tables bring back the problem the layers were meant to solve.
• Treating the layers as a data model. Three schemas named bronze, silver and gold say nothing about how the tables inside them are designed.

What tools help with a medallion architecture?

• Lakehouse and warehouse platforms. Any platform with cheap storage and a SQL engine can hold the three layers, usually as one schema or catalog per layer.
• Transformation and orchestration tools. Frameworks that run SQL or notebook jobs in dependency order, with tests at each boundary and a schedule for the whole chain.
• AI diagramming tools. Tools like Eraser turn a description of your sources, layers and consumers into a data flow diagram you can keep editing as text, which helps when a design review needs to see what lands where.

For more on this kind of diagram, see data flow diagrams.

Frequently asked questions