What is the medallion architecture?
Organising a lakehouse in 3 layers of rising quality: bronze for raw data, silver for cleaned and joined data, and gold for tables shaped for reports and AI.
intermediate · Also called Bronze, silver, gold, Multi-hop architecture
Once raw files and finished tables live in the same LakehouseLakehouseOne store for all of an organisation's data: cheap files in cloud storage, as in a data lake, with the tables, transactions and fast queries of a data warehouse on top., someone opening a table needs to know which kind it is. Is this the data as it arrived, or has someone checked it? The medallion architecture answers with 3 names borrowed from sports medals: bronze, silver and gold.
3 layers of rising trust
Bronze is the data as it arrived from the source, kept close to its raw form. Most fields are often stored as plain strings or semi-structured values, so nothing is lost if the source sends something unexpected. Full history is kept, so everything downstream can be rebuilt from it.
Silver is the data checked and cleaned. Duplicates are removed, strings become dates and numbers, quality rulesData QualityHow far data can be trusted: complete, correct, on time and in the expected shape. Pipelines check it with rules and stop or flag rows that fail. run, and records that arrived late or out of order are put right. Silver tables are joined into a consistent picture: an order with its customer and its products.
Gold is data shaped for a use: daily revenue by region, a customer's lifetime value, the table behind one dashboard. It is often summed up rather than row by row, and it is what most people outside the data team should read.
Follow one order through
A customer places an order. The shop's database records it, and change data capture copies the change into a bronze table exactly as it came, including a duplicate sent twice after a network retry.
In silver, the duplicate is dropped, the amount becomes a number, the email is removed because no report needs it, and a rule drops any order with a negative total. On Databricks that rule is a pipeline expectation that drops, keeps or stops on a bad row.
In gold, the order is one of thousands summed into yesterday's revenue for its region. That number is what the finance dashboard shows, and what an AI assistant should quote.
- "1001" "42.50" "de"
- "1002" "19.99" "FR"
- "1002" "19.99" "FR"
- "1003" "-15.00" "de"
- "1004" "120" "de"
- "9999" "1000000000" "DE"
- "1005" "64.00" "fr"
Copied as it came. Nothing dropped.
Not built yet
Duplicates out, types cast, 2 rules.
Not built yet
GROUP BY day, country.
Revenue on 14 October, read from bronze
€1,000,000,187.48
Read from bronze, revenue on 14 October comes to €1,000,000,187.48: the order sent twice, the negative row and the test order all count.
The orders and amounts are made up; a real silver step also drops columns no report needs, such as email. On Databricks the 2 rules would be expectations in a pipeline, and each layer is a table.
A convention, not a law
Databricks calls the medallion architecture a recommended practice, not a requirement. Some teams use 2 layers, some use 5. The names matter less than the rule they encode: every table says how far it can be trusted, and data only moves towards gold through checks.
Because each layer is a versioned table in an open table formatOpen Table FormatA published way of storing a table as plain data files plus a log of changes, so many engines can read and safely write it. Delta Lake and Apache Iceberg are the best known., a mistake in silver can be fixed and silver rebuilt from bronze, without going back to the source. That is the reason to keep bronze raw.
Why it matters for AI
The layers tell an AI system what to read. An assistant answering a question about revenue should read gold tables, or a semantic layerSemantic LayerOne shared definition of business terms and metrics, such as revenue or active customer, that reports, dashboards and AI assistants all read instead of writing their own. defined on them, where the definitions were agreed. Pointed at bronze, it will count the duplicate order and the test records too, and give the wrong total with complete confidence.
Documents follow the same path. Raw PDFs are bronze; parsed, cleaned text is silver; the chunks and vectors an assistant searches are a gold product of their own, made by an embedding pipelineEmbedding PipelineThe pipeline that turns source documents into searchable vectors: it reads new and changed content, chunks it, embeds each chunk and keeps the vector index in step with the source..
Sources