A Arquitetura Medallion Não É o Que Você Pensa que É

Se você esteve em qualquer lugar perto da Engenharia de Dados nos últimos cinco anos, já viu o diagrama. Três caixas coloridas empilhadas verticalmente: bronze embaixo, prata no meio, ouro no topo. Setas apontando para cima. Talvez um logo de lakehouse no canto. O post no blog explica que bronze é bruto, prata é limpo, ouro está pronto para analytics. Simples. Elegante. Pronto.

Só que não está pronto. Mal começou.

A Arquitetura Medallion é o padrão mais mal compreendido da Engenharia de Dados moderna. Não porque é complicado — não é — mas porque a forma como é ensinado retira tudo o que o torna útil. O que sobra são três nomes de pastas e uma vaga noção de que seus dados devem fluir "para cima". Isso não é uma arquitetura. É um sistema de arquivamento.

Já revisei dezenas de plataformas de dados que afirmam implementar Medallion. A maioria delas usa a terminologia — bronze, prata, ouro — sem implementar o padrão real. Elas têm três esquemas em seu warehouse, três prefixos em seu object store, três diretórios em seu projeto de transformação. Mas quando você olha o que está dentro dessas camadas, as fronteiras são arbitrárias, os contratos são indefinidos e as garantias são inexistentes. As camadas são decoração, não engenharia.

Isso importa porque Medallion, quando implementada corretamente, resolve um problema real e importante: fornece uma cadeia de suprimento de dados confiável, depurável e evoluível. Quando implementada como culto de carga — copiada de posts de blog sem entender o propósito subjacente — ela fornece três pastas e uma falsa sensação de ordem.

Deixe-me explicar o que o padrão realmente é, os cinco erros que quase todo mundo comete e quando você deve ignorar Medallion completamente.

O que Medallion realmente é

Deixe de lado o marketing e os diagramas bonitos. Medallion é um contrato de qualidade de dados em camadas. Cada camada faz uma garantia específica sobre os dados que contém. A garantia em cada camada é estritamente mais forte do que a da camada abaixo. Esse é todo o padrão. Todo o resto é detalhe de implementação.

Bronze: a camada bruta

Bronze é uma cópia imutável dos dados de origem, exatamente como chegaram. Sem transformações. Sem limpeza. Sem renomear colunas. Sem fazer cast de tipos. A garantia é simples: esses dados são idênticos ao que o sistema de origem produziu. Se a origem enviou nulls, bronze tem nulls. Se a origem enviou registros duplicados, bronze tem registros duplicados. Se a origem enviou uma string onde você esperava um inteiro, bronze tem uma string.

Essa imutabilidade é todo o ponto. Bronze é sua apólice de seguro. Quando uma transformação se revela errada — quando alguém descobre que "status = 7" na verdade significa algo diferente do que o desenvolvedor original assumiu — você volta para bronze e re-deriva. Se bronze é mutável, você perdeu os dados originais e perdeu a capacidade de se recuperar de erros. Isso não é uma inconveniência menor. É uma falha arquitetural fundamental.

Prata: a camada conformada

Prata são dados limpos, validados, desduplicados e com tipos aplicados. A garantia é: esses dados são estruturalmente corretos e internamente consistentes. Colunas têm os tipos certos. Nulls são tratados conforme a política. Duplicatas são resolvidas. Timestamps estão em um fuso horário consistente. Chaves são validadas. O esquema é aplicado.

Prata é onde você lida com a bagunça do mundo real. Sistemas de origem são caóticos — eles enviam diferentes formatos de data, têm nulls implícitos, duplicam registros durante retries, mudam esquemas sem aviso. Prata absorve todo esse caos e produz dados limpos, confiáveis e estruturalmente consistentes. Mas — e isso é crítico — prata não contém lógica de negócio. Ela não calcula receita. Não classifica clientes. Não agrega transações. Ela apenas torna os dados confiáveis no nível estrutural.

Ouro: a camada modelada para o negócio

Ouro são dados modelados para consumidores de negócio específicos. A garantia é: esses dados respondem a uma pergunta de negócio específica corretamente. Receita por região. Valor vitalício do cliente. Features de previsão de churn. KPIs operacionais. Tabelas ouro contêm lógica de negócio — os joins, cálculos, agregações e classificações que transformam dados limpos em respostas de negócio.

O insight chave sobre ouro: não existe uma única camada ouro. Existem muitas. Consumidores diferentes precisam de modelos diferentes. O time de finanças precisa de dados de receita agregados por período contábil com regras específicas de reconhecimento. O time de marketing precisa dos mesmos dados subjacentes agregados por campanha com lógica de atribuição. O time de ML precisa de tabelas de features com grão diferente e semântica temporal diferente. Tudo isso é ouro — e tudo isso deve ser separado, explicitamente desenhado para seu consumidor.

Note o que o diagrama enfatiza: garantias, não pastas. Cada camada tem um contrato específico sobre o que é verdade sobre os dados dentro dela. Se você não consegue articular a garantia em cada fronteira, você não tem uma Arquitetura Medallion. Você tem três esquemas com nomes bonitos.

Os cinco erros que quase todo mundo comete

Já auditei implementações de Medallion em empresas que variam de startups de 20 pessoas a times de dados empresariais com cinquenta engenheiros. Os mesmos cinco erros aparecem de novo e de novo. Eles não são casos extremos — são a norma.

Erro 1: Tratar camadas como pastas em vez de contratos

Esse é o erro mais comum e mais prejudicial. Um time cria três esquemas — bronze, prata, ouro — e começa a colocar tabelas neles com base em intuição. Dados mais ou menos brutos vão para bronze. Dados mais ou menos limpos vão para prata. Tabelas finais vão para ouro. Não há definição formal do que qualifica uma tabela para uma determinada camada. Não há validação nas fronteiras.

A consequência é que você não pode confiar em nenhuma camada. Uma tabela em "prata" pode ter duplicatas, pode ter tipos errados, pode ter nulls onde não deveria. Ninguém sabe, porque ninguém definiu o que prata garante. Quando um dashboard mostra um número errado, você não consegue localizar onde está o problema, porque nenhuma camada faz uma promessa contra a qual você possa testar.

A correção: escreva o contrato de cada camada. Literalmente. Um documento que diga "uma tabela em prata deve satisfazer estas condições: sem chaves primárias duplicadas, todas as colunas tipadas de acordo com o schema registry, todos os timestamps em UTC, política de nulls aplicada." Então teste essas condições em cada transição de camada.

Erro 2: Colocar lógica de negócio em prata

Prata deve ser agnóstica de domínio. Deve limpar os dados de formas que qualquer consumidor downstream iria querer: desduplicar, aplicar tipos, conformar timestamps, validar chaves. No momento em que você coloca lógica de negócio em prata — calcular receita, classificar clientes em segmentos, aplicar regras de desconto — você acoplou todo consumidor downstream às definições de negócio de um time.

Uma vez auditei uma plataforma onde prata continha uma coluna customer_segment derivada das regras de classificação do time de marketing. O time de ML precisava de uma segmentação diferente para seu modelo de churn. Mas eles estavam lendo de prata, que já tinha a segmentação de marketing embutida. Eles não conseguiam obter os atributos brutos de que precisavam para construir sua própria classificação. A camada prata "compartilhada" tinha se tornado um gargalo porque codificava a lógica de negócio de um time como se fosse verdade universal.

Lógica de negócio pertence a ouro. Diferentes camadas ouro podem aplicar lógica diferente aos mesmos dados de prata. Esse é todo o ponto de ter múltiplas saídas ouro.

Erro 3: Tornar bronze mutável

Esse geralmente acontece por razões de custo. "Estamos gastando demais com armazenamento. Vamos limpar bronze e remover dados com mais de 90 dias." Ou acontece acidentalmente: um pipeline sobrescreve tabelas bronze em vez de fazer append.

No momento em que bronze é mutável, você perdeu o benefício central do padrão Medallion. Bronze é seu botão de rewind. Quando você descobre que uma transformação estava errada — e você vai descobrir isso, não é questão de "se" — você re-deriva prata e ouro a partir de bronze. Se bronze foi modificado, você está re-derivando a partir de uma base corrompida. Você pode nem saber que está corrompido até que os números não batam e você já tenha gasto três dias depurando.

Armazenamento é barato. Re-derivar dados do nada não é. Mantenha bronze imutável. Use políticas de ciclo de vida e camadas de cold storage para gerenciar custos, mas nunca delete ou modifique os dados.

Erro 4: Ter apenas uma camada ouro

Esse erro vem de levar o diagrama de três camadas literalmente demais. Bronze é uma camada, prata é uma camada, portanto ouro deve ser uma camada. Errado. Ouro é onde você modela dados para perguntas de negócio específicas, e perguntas diferentes requerem modelos diferentes.

Um mart financeiro agrega por período fiscal com regras específicas de reconhecimento de receita. Um mart de marketing agrega por campanha com janelas de atribuição. Um dashboard operacional precisa de grão em tempo real ou quase-real. Um feature store de ML precisa de correção point-in-time. Tentar servir tudo isso a partir de um único esquema ouro significa que toda tabela é um compromisso — granular demais para os executivos, agregado demais para o time de ML, usando o calendário fiscal errado para o financeiro.

Construa camadas ouro separadas (eu as chamo de marts) para cada grande consumidor ou domínio. Todos leem das mesmas tabelas prata, mas modelam os dados de forma diferente. Isso não é duplicação — é especialização.

Erro 5: Pular prata

"Somos um time pequeno. Não temos tempo para uma camada prata. Vamos direto de bronze para ouro."

Já ouvi isso uma dúzia de vezes. O time que pula prata sempre paga o preço dentro de seis meses. Eis por quê: sem uma camada limpa compartilhada, cada modelo ouro tem que lidar com a limpeza de dados sozinho. Modelo A desduplica pedidos de um jeito. Modelo B os desduplica de outro jeito. Quando os números não batem, ninguém consegue dizer se o problema está na lógica de negócio ou na lógica de limpeza — porque elas estão emaranhadas em cada modelo.

Prata é a fundação compartilhada. Ela resolve o problema de limpeza uma vez, e cada modelo ouro é construído sobre essa fundação limpa. É também a fronteira de depuração mais natural: quando algo parece errado em ouro, você verifica prata primeiro. Se prata está limpo, o problema está na lógica de negócio de ouro. Se prata está sujo, o problema está upstream. Sem prata, você está depurando o pipeline inteiro toda vez.

O tempo que você "economiza" pulando prata é gasto dez vezes mais em depuração e combate a incêndios de qualidade de dados. Toda. Vez.

Quando Medallion é o padrão errado

Medallion é um bom padrão. Não é o único padrão. Existem arquiteturas legítimas onde Medallion não se encaixa, e forçá-lo cria mais problemas do que resolve.

Cargas de trabalho em tempo real e streaming

Medallion é fundamentalmente um padrão orientado a batch. Assume que os dados fluem pelas camadas em execuções discretas — extrair, depois limpar, depois modelar. Cargas de trabalho de streaming precisam que os dados estejam disponíveis em milissegundos, não minutos. Você pode adaptar conceitos de Medallion para streaming (um "tópico bronze" em um message broker, por exemplo), mas o padrão perde a maioria de seus benefícios quando latência é a restrição primária. Streaming tem seus próprios padrões — event sourcing, CQRS, materialized views — que servem melhor ao requisito de latência.

Pipelines muito simples

Se você tem um sistema de origem, um consumidor e uma transformação direta, três camadas são overhead. Uma abordagem de duas camadas (bruto + modelado) ou mesmo um único pipeline bem testado é suficiente. Não crie complexidade para satisfazer um padrão. O padrão existe para gerenciar complexidade que já está lá.

Arquiteturas Data Mesh

Em um Data Mesh, cada time de domínio detém seus produtos de dados ponta a ponta. Eles definem seus próprios contratos de qualidade, seus próprios esquemas, suas próprias interfaces. Uma Arquitetura Medallion centralizada com camadas bronze e prata compartilhadas contradiz o princípio de propriedade de domínio do mesh. Cada domínio pode usar Medallion internamente, mas o mesh em si opera sob princípios diferentes — governança federada, descentralização orientada a domínio, infraestrutura self-serve.

Prototipagem e exploração

Quando você ainda está descobrindo que perguntas fazer e que dados precisa, camadas formais te atrasam. Explore livremente em um sandbox. Leia dos sistemas de origem diretamente. Itere rápido. Quando padrões emergem e você sabe como deve ser o pipeline de produção, então introduza Medallion. O padrão é para produtos de dados em produção, não para descoberta.

Um modelo mental melhor: a cadeia de suprimento de dados

O diagrama que todo mundo desenha — três caixas empilhadas com setas — é tecnicamente correto mas pedagogicamente inútil. Não transmite por que as camadas existem ou como se relacionam. Aqui está um modelo mental melhor: pense em Medallion como uma cadeia de suprimento de manufatura.

Bronze são matérias-primas. Minério, madeira, petróleo cru. Você as estoca exatamente como chegam dos fornecedores. Não as processa até que precise. Nunca joga fora, porque você pode descobrir um novo uso para elas depois. O armazém de matérias-primas é sua reserva estratégica.

Prata é o chão de fábrica. É onde as matérias-primas são inspecionadas, limpas, cortadas na especificação e preparadas para montagem. O chão de fábrica não fabrica produtos acabados — fabrica peças padronizadas. Essas peças são úteis para múltiplas linhas de montagem. O chão de fábrica é infraestrutura compartilhada: cada linha de produto se beneficia dos mesmos componentes com qualidade controlada.

Ouro é o produto acabado. Cada produto é projetado para um cliente específico com requisitos específicos. O dashboard executivo é um carro de luxo — polido, agregado, de alto nível. O feature store de ML é ferramental de precisão — exato, granular, temporalmente correto. O relatório de compliance é um manual de segurança — completo, auditável, de padrão regulatório. Mesmas matérias-primas, mesma fábrica, produtos diferentes.

Esse modelo mental torna as decisões de design óbvias. Você não colocaria a lógica de montagem do produto no chão de fábrica — isso acoplaria todo produto a um único design. Você não pularia a inspeção de qualidade para economizar tempo — você enviaria peças defeituosas para toda linha de montagem. Você não jogaria fora matérias-primas para economizar espaço no armazém — perderia a capacidade de construir novos produtos a partir do suprimento existente.

Como eu realmente implemento

Teoria é útil. Implementação é o que importa. Aqui está como construo Arquiteturas Medallion na prática — as convenções de nomenclatura, a estratégia de testes, a estrutura de diretórios e as decisões que pegam a maioria dos times de surpresa.

Convenções de nomenclatura

Nomenclatura é uma daquelas coisas que parece trivial até você ter 300 tabelas e não conseguir achar nada. Eu uso um esquema consistente baseado em prefixos:

• bronze_{origem}_{tabela} — ex.: bronze_crm_contacts, bronze_payments_transactions
• silver_{dominio}_{entidade} — ex.: silver_customers_contacts, silver_finance_transactions
• gold_{mart}_{tabela} — ex.: gold_marketing_campaign_performance, gold_finance_monthly_revenue

O prefixo te diz a camada. O segundo segmento te diz a origem (para bronze), domínio (para prata) ou mart consumidor (para ouro). O resto descreve a entidade. Você acha qualquer tabela em três segundos.

Testes nas fronteiras das camadas

O contrato em cada fronteira de camada precisa ser testado. Não "esperamos que prata esteja limpo" — de fato testado, em cada execução. Isso é comumente implementado com o framework de testes embutido de uma ferramenta de transformação, mas o conceito é universal independente do tooling.

Na fronteira bronze-para-prata, eu testo: unicidade de chave primária, conformidade com a política de nulls (quais colunas permitem nulls e quais não), conformidade de tipo (a coluna de timestamp é de fato um timestamp?) e integridade referencial onde aplicável. Na fronteira prata-para-ouro, testo: correção das regras de negócio (o cálculo de receita bate com a definição do time financeiro?), completude da agregação (as partes somam o todo?) e correção temporal (estamos incluindo os intervalos de data certos?).

Esses testes são a implementação dos contratos de qualidade. Sem eles, você só tem asserções em um documento que ninguém checa.

Aplicação de esquema

Bronze pode usar esquema-na-leitura — os dados chegam como estão e você define o esquema quando consulta. Isso é importante porque esquemas de origem mudam sem aviso, e você não quer que seu pipeline de ingestão quebre toda vez que um sistema de origem adiciona uma coluna.

Prata deve usar esquema-na-escrita — o esquema é aplicado quando os dados entram na camada. Se um tipo de coluna muda upstream, a transformação bronze-para-prata deve capturar, logar e ou lidar com isso ou falhar ruidosamente. Desvio silencioso de esquema em prata é um pesadelo de depuração.

Ouro usa esquema-na-escrita estrito com documentação explícita de colunas. Toda coluna em uma tabela ouro tem uma descrição, uma definição de negócio e um dono. Se você não consegue explicar o que uma coluna significa em termos de negócio, ela não deveria estar em ouro.

Rastreamento de linhagem

Toda tabela deveria rastrear de volta para suas entradas. Se alguém pergunta "de onde vem o número de receita no dashboard executivo?" você deveria ser capaz de responder: vem de gold_finance_monthly_revenue, que é construída a partir de silver_finance_transactions e silver_finance_exchange_rates, que são construídas a partir de bronze_payments_transactions e bronze_forex_daily_rates. Isso é linhagem — e é o que torna toda a arquitetura depurável.

A maioria dos frameworks de transformação modernos gera linhagem automaticamente a partir do grafo de dependências. Se o seu não gera, mantenha manualmente. Vale o esforço. Quando algo quebra às 3 da manhã e o engenheiro de plantão precisa rastrear um número errado até sua origem, linhagem é a diferença entre uma correção de 20 minutos e uma sessão de depuração de 4 horas.

Como é a estrutura de diretórios

Em um projeto de transformação, eu tipicamente estruturo os modelos assim:

models/
  bronze/
    crm/
    payments/
    marketing/
  silver/
    customers/
    finance/
    products/
  gold/
    marketing_mart/
    finance_mart/
    ml_features/
    operational_mart/

Cada diretório tem sua própria configuração de esquema, sua própria suíte de testes e sua própria documentação. A estrutura espelha a arquitetura, o que torna a navegação intuitiva e o onboarding rápido.

Documente suas decisões de Medallion

Eis o que ninguém te conta sobre Arquitetura Medallion: a parte mais difícil não é construí-la. É mantê-la depois que a pessoa que a construiu vai embora.

Toda implementação de Medallion está cheia de decisões que não são visíveis no código. Por que a lógica de desduplicação de clientes em prata usa e-mail em vez de número de telefone? Porque a origem CRM tem dados de telefone não confiáveis — o engenheiro original descobriu isso durante uma sessão de depuração de três dias seis meses atrás. Por que o mart financeiro usa um calendário fiscal diferente do mart de marketing? Porque o período de relatório do time financeiro não se alinha com meses do calendário — eles fecham na última sexta-feira de cada mês.

Essas decisões são críticas. Também são invisíveis. Elas vivem na cabeça do engenheiro original, em threads de Slack que são arquivadas, em notas de reunião que ninguém relê. Quando esse engenheiro vai embora — e ele vai embora — a próxima pessoa herda um sistema cheio de escolhas que não entende. Ela vai mudar a lógica de desduplicação para usar números de telefone (parece mais confiável, certo?) e quebrar tudo. Ela vai "consertar" o calendário fiscal para usar meses padrão e produzir relatórios financeiros errados por três meses antes que alguém perceba.

A solução é documentar suas decisões de Medallion em uma base de conhecimento estruturada — não como páginas de wiki espalhadas ou arquivos README, mas como um corpo de conhecimento institucional cruzado e pesquisável. Para toda decisão não óbvia em sua Arquitetura Medallion, registre:

• Qual é a decisão (ex.: "Desduplicação de clientes usa e-mail como chave primária")
• Por que foi feita (ex.: "Dados de telefone do CRM têm 15% de taxa de duplicatas devido a inconsistências de formatação")
• Qual era a alternativa (ex.: "Consideramos desduplicação por telefone, mas produzia 8% de falsos positivos")
• Quando deve ser revisitada (ex.: "Se o CRM migrar para uma nova plataforma, reavaliar a qualidade dos dados de telefone")

Eu escrevi sobre essa abordagem em detalhe em A Estratégia da Base de Conhecimento. A versão curta: sua Arquitetura Medallion deve ter uma base de conhecimento companheira que capture o porquê de toda escolha de design significativa. A arquitetura é o "o quê". A base de conhecimento é o "porquê". Ambos são essenciais para manutenibilidade a longo prazo.

Quando o próximo engenheiro entra — ou quando um agente de IA precisa entender seu sistema para planejar uma migração — a base de conhecimento fornece o contexto que o código sozinho não pode. É a diferença entre herdar um sistema que você pode manter e herdar um sistema que você só pode temer.

A Conclusão Principal

A Arquitetura Medallion é simples. Essa é sua força e sua armadilha. A simplicidade convida à cópia sem reflexão — copie o diagrama de três camadas, crie três esquemas, considere pronto. Os times que extraem valor real de Medallion são os que vão além do diagrama e implementam o que o padrão realmente requer:

• Defina contratos explícitos de qualidade em cada camada. Escreva-os. Teste-os em cada execução. Se você não consegue articular o que uma camada garante, a camada não existe — é apenas um namespace.
• Mantenha prata agnóstica de domínio. Limpe, conforme, valide — mas não codifique lógica de negócio. Isso pertence a ouro, onde consumidores diferentes podem aplicar suas próprias regras.
• Nunca mute bronze. É imutável. É append-only. É sua capacidade de se recuperar de todo erro que você vai cometer em prata e ouro. Trate como sagrado.
• Construa múltiplas camadas ouro. Consumidores diferentes precisam de modelos diferentes. Uma camada ouro compartilhada é um compromisso que não serve ninguém bem.
• Não pule prata. O tempo que você economiza agora é gasto dez vezes mais depois em depuração e combate a incêndios de qualidade de dados.
• Não force o padrão. Streaming, pipelines simples, arquiteturas mesh e trabalho exploratório têm padrões melhores. Use Medallion onde se encaixa. Ignore onde não se encaixa.
• Documente suas decisões. A arquitetura é o "o quê". A base de conhecimento é o "porquê". Ambos são essenciais para o sistema sobreviver à partida do seu construtor original.

Medallion não é bronze/prata/ouro. É um contrato de qualidade que se compõe com cada camada. Implemente os contratos, não apenas os rótulos, e você terá uma cadeia de suprimento de dados confiável, depurável e evoluível. Pule os contratos, e você terá três pastas e uma falsa sensação de ordem.

O padrão é simples. Fazê-lo certo requer disciplina. Mas o retorno — uma plataforma de dados onde você pode confiar em cada número, rastrear cada linhagem e depurar cada problema — vale o rigor.