Definition
The medallion architecture is a way of organizing data inside a lake or lakehouse into a small number of layers, usually three, that each represent a different level of cleanliness and readiness for use. The raw layer holds data close to how it arrived, largely untouched. A middle layer holds that same data after it has been cleaned, validated, and standardized. A final layer holds data that has been shaped into the specific, aggregated form business users and reports actually consume. Data moves through the layers in one direction, getting more refined and more trustworthy at each stop, which is the whole idea behind the pattern.
It exists because dumping everything into one big undifferentiated pile of data, historically what a lot of early data lakes actually were, turned into a mess nobody could navigate. Raw files sat next to cleaned tables next to half finished experiments, with no clear signal about which version of a dataset was safe to build a report on and which was still being sorted out. Teams needed a structure that made trustworthiness visible just from where a table lived, so someone querying data could tell at a glance whether they were looking at something raw and unreliable or something vetted and ready.
The naive version of this idea is just having "a raw folder and a clean folder," which sounds similar but usually lacks the discipline that makes the real pattern work. A proper medallion setup has consistent rules about what has to happen for data to move from one layer to the next, defined transformations, validation checks, and often automated tests, so that landing in the refined layer actually means something specific rather than just "someone moved the file." Without those rules enforced consistently, you get folders with reassuring names sitting on top of the same inconsistent mess they were meant to fix.
By 2026, the medallion architecture has become close to a default mental model for organizing data inside a lakehouse, popularized heavily through the growth of lakehouse platforms and now taught as a standard pattern in most data engineering courses and documentation. Plenty of teams use the bronze, silver, gold naming even when their underlying platform is not a full lakehouse, simply because the layered idea is useful on its own. It is not universal, some teams still prefer their own naming or a two-layer version, but the underlying concept of progressive refinement through named layers is close to standard practice now.
This page covers how data actually moves through the medallion layers, how the pattern compares to the older staging and mart layering used in traditional data warehouses, how it differs from the broader idea of a data lakehouse, and where the pattern is worth adopting versus where it adds structure nobody needs. The durable idea is simple even if the implementation details vary: separate data by how much you trust it, make that trust level visible in where the data lives, and never let a report sit on top of a table that has not earned its way there.
Key Takeaways
- The medallion architecture organizes data into layers, typically bronze, silver, and gold, that represent increasing levels of cleanliness and readiness for use.
- It exists because undifferentiated data lakes made it impossible to tell which tables were trustworthy and which were still raw or unfinished.
- A real medallion setup enforces specific rules for moving data between layers, not just informal folders with reassuring names.
- By 2026, the pattern is close to a default convention for organizing data inside a lakehouse, taught widely as a standard practice.
- The core idea is making trust level visible through where data lives, so nobody accidentally builds a report on unvetted data.
How the Medallion Architecture Works
Data enters at the bottom layer close to its original form, ingested from source systems, files, or streams with minimal transformation applied, mostly just capturing it reliably and adding basic metadata like when it arrived and where it came from. The point of this first stop is not to make the data pretty, it is to make sure nothing is lost and that there is always a faithful copy of what actually came in, in case something downstream needs reprocessing later.
From there, a set of transformation jobs pulls that raw data forward into a middle layer, applying cleaning, deduplication, type casting, and joins across sources that need to be combined. This is usually where most of the actual engineering effort lives, since resolving inconsistent formats, filtering out bad records, and reconciling data from multiple systems is genuinely hard work, and getting it wrong here means every layer built on top inherits the same mistake.
The data that survives that cleaning process moves on to a final layer, shaped into the specific, often aggregated form that business users and reporting tools actually query, sales totals by region, customer metrics rolled up by month, whatever matches how the business actually thinks about the data. This layer is usually the smallest and the most curated, built for a specific set of known questions rather than for flexibility, since flexibility was already handled by the layers underneath it.
The movement between layers is typically automated through scheduled or event-triggered pipelines, often incremental, processing only new or changed data rather than reprocessing everything from scratch each time. Each promotion step usually includes some form of validation, checking that a transformation did not silently drop rows or introduce nulls where there should not be any, so that arriving in a higher layer carries a real guarantee about quality rather than just being a location on disk.
The Medallion Architecture Compared to Traditional Warehouse Layering
Long before anyone said bronze, silver, or gold, data warehouse teams were already building layered pipelines: a staging area holding data close to source form, an integration or operational data store layer where data got cleaned and conformed, and a presentation or mart layer built for specific reporting needs. The intent behind that structure and the intent behind the medallion architecture are nearly identical, protect the raw and give people a trustworthy, curated destination to actually query.
Where the two diverge is the environment they were built for. Traditional warehouse layering generally assumed structured, relational data with a schema defined before anything got loaded, schema on write, which made sense when storage was expensive and every table had a known shape ahead of time. The medallion pattern grew up in data lakes and lakehouses, where storage is cheap enough to keep raw files in whatever messy format they arrived in, and schema gets applied later, schema on read, once someone actually needs to make sense of the data.
That difference in origin shows up in how seriously each pattern treats the raw layer. Traditional staging areas were often treated as temporary, sometimes wiped clean after a load completed, since storage cost made keeping everything forever unappealing. The bronze layer in a medallion setup is usually meant to persist indefinitely as an immutable historical record, precisely because cheap lake storage makes that affordable, and having the original data available for reprocessing turns out to matter more than most teams expect until the day they actually need it.
The honest tradeoff is that a lot of what feels new about the medallion architecture is really the vocabulary and the tooling ecosystem around it, dbt models, lakehouse platforms, and orchestration tools that all speak in bronze, silver, gold terms now, rather than some fundamentally different engineering idea. Teams that already had disciplined staging, integration, and mart layers were doing something functionally close to medallion architecture years before the name existed. What changed is that the pattern now has a shared, memorable name that gets teams on the same page faster.
What Makes the Medallion Architecture Different From a Data Lakehouse
A data lakehouse is a platform architecture, a way of combining the cheap, flexible storage of a data lake with features that used to be exclusive to data warehouses: transactional guarantees, schema enforcement, and the ability to reliably update or delete specific rows rather than only ever appending new files. It is an infrastructure decision, built on table formats like Delta Lake, Iceberg, or Hudi, about how data gets stored and managed underneath everything else.
The medallion architecture is something different: an organizational convention for how to structure the data that lives inside whatever storage platform you have chosen, lakehouse or otherwise. It answers "how should we arrange our tables so trust level is visible," which is a modeling and process question, not a storage engine question. You can have a lakehouse and organize your data completely differently from bronze, silver, gold, and you can apply a bronze, silver, gold style layering inside a plain data lake or even a traditional warehouse that has nothing to do with lakehouse table formats.
The two get conflated constantly because they showed up in the same conversation for years and are frequently adopted together in practice. A team announcing "we moved to a lakehouse" often means both things happened at once, a new storage platform and a new layered organization scheme, and it is easy to walk away thinking the two are the same decision. They are not, and treating them as one thing makes it harder to reason about which problem a given change is actually solving.
The practical difference matters when something is not working. If reports are slow or data is inconsistent, the fix might be an infrastructure problem, the lakehouse platform choice, or it might be an organizational problem, how the layers are structured and what rules govern moving between them. Diagnosing which one is broken requires keeping the two concepts separate in your head, even though most real deployments run them side by side without much friction.
Where the Medallion Architecture Fits and Where It Does Not
The medallion architecture fits well in organizations pulling data from many different sources and serving many different consuming teams, where a shared structure genuinely helps people who did not build a pipeline understand what they are looking at. Once there are enough tables that nobody remembers off the top of their head which ones are safe to build on, a consistent layering, visible in naming or in schema location, saves a lot of Slack messages asking whether a given table is trustworthy.
It also fits well anywhere the ability to reprocess from raw actually gets used, not just theoretically available. Machine learning workflows that need to retrain against slightly different feature definitions, or business logic that changes often enough that yesterday's transformation rules will not be right forever, benefit enormously from having an untouched bronze layer to rebuild from, rather than needing to re-extract from the original source system every time the business changes its mind about a calculation.
It fits poorly for a small team running one or two pipelines feeding one dashboard, where three formal layers, each with its own transformation logic and validation, is more process than the problem actually requires. At that scale, one well-tested pipeline from source to destination is easier to reason about and faster to build than a layered structure designed for a scale of complexity that has not shown up yet.
It also fits poorly for use cases where the multi-hop nature of the pattern, data moving through bronze, then silver, then gold on separate schedules, introduces more delay than a direct pipeline would. Real time fraud detection or live operational alerting often cannot tolerate the batch or incremental promotion cycle a medallion setup typically runs on, and forcing that use case through three layers just to stay consistent with everything else can quietly turn a latency-sensitive system into a slow one.
How to Implement the Medallion Architecture Well
Keep the raw layer genuinely raw. It is tempting to sneak in a little cleaning at ingestion, fixing an obviously wrong date format or dropping a clearly duplicate row, but every shortcut like that chips away at the one guarantee that layer is supposed to provide, an unedited copy of what actually arrived. The day you need to reprocess from scratch because a downstream transformation turned out to be wrong, you want to be certain the raw layer never quietly diverged from the real source.
Write explicit, testable rules for what has to be true before data can move up a layer, rather than letting each pipeline decide informally. A record moving from bronze to silver might need to pass schema validation and null checks, and moving from silver to gold might need specific business rules applied and reconciled against known totals. Documenting these rules, and testing that pipelines actually enforce them, is what turns the layer names into real guarantees instead of just folder labels that sound reassuring.
Do not treat three layers as a law of physics. Some pipelines genuinely need a fourth layer for a particularly gnarly transformation step, and some simple pipelines are honestly fine with two. The number of layers should track the actual complexity of getting from raw to business ready, and forcing every single pipeline through the same three hop structure regardless of how simple or complex it actually is adds ceremony without adding safety.
Match access and governance controls to the trust level each layer represents. Bronze, being raw and possibly containing sensitive or unvalidated information, usually deserves tighter access than gold, which has been through validation and is meant for broad business consumption. Treating every layer with the same access policy defeats part of the purpose of layering in the first place, since one benefit of the structure is being able to open up access gradually as data earns more trust.
Write down what "gold" actually means for each business domain, because this is the layer where definitions diverge the most and cause the most confusion later. One team's gold revenue table might net out refunds and another's might not, and if that difference is not documented, two dashboards built from two different gold tables will disagree with each other in a meeting, with nobody able to explain why, since both tables are technically labeled gold and both technically passed validation.
Best Practices
- Keep the bronze layer genuinely raw and immutable, resisting the temptation to clean data at ingestion.
- Define explicit, testable rules for moving data between layers instead of letting each pipeline decide informally.
- Adjust the number of layers to the actual complexity of a pipeline rather than forcing every one through the same three hops.
- Match access controls to each layer's trust level, keeping bronze tighter and gold more broadly available.
- Document exactly what each gold table's business logic means, since this is where the most costly disagreements between teams show up.
Common Misconceptions
- The medallion architecture is not the same thing as a data lakehouse; it is an organizational convention that is commonly built on top of one but is not the storage platform itself.
- The medallion architecture is not defined by having three folders with the right names; it depends on enforced rules for what qualifies data to move between layers.
- The medallion architecture is not always exactly three layers; the right number tracks the pipeline's actual complexity, not a fixed rule.
- The medallion architecture is not primarily a new technical idea; it is largely a shared vocabulary for a layered pattern data warehouse teams were already using.
- The medallion architecture is not automatically appropriate for low-latency use cases; the multi-hop promotion between layers can introduce delay a direct pipeline would avoid.
