Medallion Architecture Diagram: Bronze, Silver and Gold Layers

Every data platform eventually grows a swamp: five tables called orders, nobody sure which one finance uses, and a dashboard that broke because someone fixed a bug upstream. The medallion architecture is a simple answer to that mess. It organizes a lakehouse into three layers, bronze, silver and gold, each with a clear contract about how trustworthy its data is and who may use it.

The idea is popular because it is easy to explain, and frequently misapplied because it is easy to explain. This post covers what each layer holds and what it must not, how data moves between them, data quality checks, reprocessing, governance, the common pitfalls, and when you do not need the pattern at all, with a diagram you can adapt.

The three layers at a glance

The name comes from Databricks, whose documentation describes the layers as raw, validated and enriched. In practice:

Read the layers as a quality contract rather than a count of processing steps. Bronze promises completeness, silver promises correctness, and gold promises usefulness for a named audience.

Bronze: keep everything, change nothing

Bronze is where raw data lands: files from object storage, Kafka topics, change data capture streams from operational databases, exports from SaaS tools. The rules:

• Append only. Never update or delete bronze records as part of normal processing.
• Minimal parsing. Databricks recommends storing most fields as strings, variant or binary values in bronze, so an unexpected schema change upstream does not drop data.
• Add metadata: ingestion time, source system, file name or topic offset. You will need them for debugging and replays.
• Keep it long enough to rebuild. Bronze retention defines how far back you can recompute silver and gold after a bug fix.

Bronze contains everything, including personal data you may later wish you had not copied. Restrict access to pipelines, and consider tokenizing or encrypting sensitive fields at ingestion. The GDPR data mapping diagram helps track where personal data flows.

Silver: make it correct

Silver is where most engineering effort goes:

• Parse and type fields, normalize timestamps to UTC and standardize units and codes.
• Deduplicate records that arrived twice, which happens with every at-least-once source.
• Apply changes. For change data capture sources, merge inserts, updates and deletes into a current-state table.
• Conform keys so that a customer has the same identifier whether it came from the CRM or the billing system.
• Quarantine instead of dropping. Rows that fail validation go to a quarantine table with the reason, where someone can see them.

A typical silver merge with Delta Lake or Apache Iceberg in Spark SQL keeps only the latest version of each order:

MERGE INTO silver.orders AS t
USING (
  SELECT * FROM (
    SELECT *, ROW_NUMBER() OVER (PARTITION BY order_id ORDER BY updated_at DESC) AS rn
    FROM bronze.orders_raw
    WHERE _ingested_at > '2026-11-01T00:00:00Z'
  ) WHERE rn = 1
) AS s
ON t.order_id = s.order_id
WHEN MATCHED AND s.updated_at > t.updated_at THEN UPDATE SET *
WHEN NOT MATCHED THEN INSERT *;

Data quality rules belong at this boundary. Databricks pipelines, for example, declare them as expectations that warn, drop the offending rows or fail the update:

CREATE OR REFRESH STREAMING TABLE silver_payments (
  CONSTRAINT positive_amount EXPECT (amount > 0) ON VIOLATION DROP ROW,
  CONSTRAINT known_currency EXPECT (currency IN ('USD', 'EUR', 'GBP')) ON VIOLATION DROP ROW
)
AS SELECT * FROM STREAM(bronze_payments);

Whatever tool you use, make the rules visible and count the rows they reject.

Gold: make it useful

Gold tables are built for consumers: a star schema for finance reporting, daily revenue by region for the executive dashboard, customer features for a churn model. Each gold table should have an owner, a documented definition and a freshness target. Metric definitions such as "active customer" or "net revenue" belong here, written once, not re-implemented in every dashboard.

Gold is also where you denormalize and aggregate for speed. Silver keeps detail; gold answers questions.

Batch, streaming or both

The layers do not dictate latency. Each hop can run as a nightly batch, an hourly incremental job or a continuous stream with checkpoints. Many teams stream from sources into bronze and silver, so data is current within minutes, and refresh gold aggregates on a schedule that matches how often anyone looks at them. Process incrementally wherever you can: reading only new bronze data since the last run is what keeps costs flat as data grows.

Reprocessing and history

Because bronze is immutable, a bug in silver logic is recoverable: fix the code, rebuild the affected silver partitions from bronze, then rebuild gold. Table formats such as Delta Lake and Iceberg add snapshots, so you can query a table as of yesterday, audit a change or roll back a bad load. Plan for this from the start: keep transformations deterministic and partition tables so that rebuilding a month does not mean rebuilding everything.

Governance by layer

Put each layer in its own schema in your catalog, for example ops.bronze, ops.silver and ops.gold, which is the layout Databricks uses in its own example. Then grant access by layer: pipelines write bronze, engineers and analysts read silver, and most of the company reads only gold. Lineage across layers answers the question everyone asks during an incident: which dashboards depend on this broken source?

Pitfalls

• Treating three as a rule. Some sources need more steps, some need fewer. The contract matters, not the number of hops.
• Business logic in silver. Silver should be reusable by many consumers. Logic that serves one report belongs in gold.
• Gold as a dumping ground. Without owners, gold fills with one-off tables that nobody maintains. Review and retire them.
• Copying everything three times. Large raw datasets stored in three forms cost real money. Keep silver to the columns and history people actually need.
• Skipping quarantine. Silently dropped rows are how numbers drift without anyone noticing.

When medallion is overkill

If your data fits comfortably in a cloud warehouse and arrives from a handful of sources, you may not need a lakehouse at all. The common dbt convention of staging, intermediate and marts expresses the same idea of increasing refinement inside one warehouse:

The names matter less than the discipline: raw data kept intact, one clean version of each entity, and purpose-built tables with owners.

The medallion diagram

How to read it:

• Sources on the left: change data from Postgres, events from Kafka and a CRM export.
• Three colored frames are the layers. Bronze holds raw files, silver holds cleaned tables and a quarantine store, gold holds business tables.
• Edges between frames are pipeline steps, labeled with what they do: parse, deduplicate, merge, aggregate.
• Consumers on the right: BI dashboards and a feature store for machine learning read only from gold.
• The Markdown block lists the contract for each layer.

Drawing data platforms that people can navigate

• Color the layers. Bronze, silver and gold are memorable precisely because they are visual; use the colors.
• Label every hop with its operation, not just an arrow. "Dedupe and merge" tells a reviewer where to look for a bug.
• Show who reads what. Access by layer is a design decision, and the diagram should make it obvious that dashboards never read bronze.
• Include the quarantine path. It shows reviewers where rejected data goes.

The broader pipeline around the lakehouse is covered in the data pipeline architecture diagram, the streaming sources in the Kafka architecture diagram, and the ML consumers in the MLOps architecture diagram.

Build it in Archboard

1. Sign in with Google or GitHub and create a diagram.
2. Add a Postgres node and a Kafka node from the Data pack, and an External System from the C4 Model pack for the CRM, as sources.
3. Add three Core Frame nodes named Bronze, Silver and Gold, colored to match.
4. Inside bronze, add an Object Store from the Data pack for raw files. Inside silver, add a Data Warehouse node for cleaned tables and an Object Store for quarantine. Inside gold, add another Data Warehouse node for business tables.
5. Add a Core Box for BI dashboards and a Feature store from the ML pack as consumers.
6. Label the edges with each step and add a Markdown block from the Core pack with the layer rules.

The example uses 13 diagram nodes, within the Free plan.

FAQ

What is the medallion architecture? A way to organize a lakehouse into three layers of increasing quality: bronze for raw data as received, silver for cleaned and conformed data, and gold for business-ready tables built for specific uses.

What is the difference between silver and gold? Silver holds correct, reusable data at the detail level, one table per entity or event type. Gold holds tables shaped for a purpose, such as aggregates, star schemas or ML features, with an owner and definitions.

Should bronze data ever be modified? Not as part of normal processing. Bronze is append-only so you can rebuild everything downstream. Exceptions are legal deletion requests and retention limits, which need their own process.

Is the medallion architecture only for Databricks? No. The name comes from Databricks, but the pattern works with any lakehouse or warehouse: Delta Lake, Apache Iceberg, Snowflake or BigQuery, with Spark, dbt or other tools.

Do I always need three layers? No. Use as many steps as your sources need. The important parts are an untouched raw copy, one clean version of each entity, and purpose-built tables with owners.

Start free — one seat, no credit card.