Arquitetura medalhão: o que é, quando usar e quando é exagero

Imagem de capa

Três camadas empilhadas dentro de uma tela escura, cada uma mais estreita que a de baixo. O conteúdo passa de uma para a outra e vai ficando mais organizado: registros soltos embaixo, uma grade regular no meio, e três barras somadas em cima.

O comercial mudou a regra de comissão no meio do trimestre, e alguém precisa refletir isso no painel até sexta.

A regra está escrita dentro da consulta que alimenta o painel. A mesma consulta que limpa o texto do estado, converte o valor que veio como texto e junta quatro tabelas.

O problema é que mexer na regra significa mexer em tudo isso junto. E ninguém consegue dizer, antes de rodar, se o faturamento vai continuar batendo depois da mudança.

Neste artigo, explicamos o que entra em cada camada da arquitetura medalhão, por que a separação evita esse retrabalho e em que situações três camadas são mais do que o problema pede.

O que é a arquitetura medalhão

É um padrão de organização, não uma tecnologia. O nome vem das medalhas — bronze, prata e ouro, em qualidade crescente —, e a cada passagem o dado fica mais estruturado e mais confiável.

A Databricks popularizou o termo ao descrever a organização de um lakehouse — o armazenamento que junta arquivo bruto e tabela analítica no mesmo lugar. Mas o padrão não depende de fornecedor nenhum, e funciona igual em banco relacional, em armazém de dados e em armazenamento de arquivos.

Seguir a arquitetura medalhão é uma boa prática recomendada, não uma exigência.

A frase é da documentação da própria Databricks, e vale reter para a última seção deste artigo.

Figura 1 — o mesmo registro nas três camadas

Três faixas empilhadas com o mesmo pedido atravessando as três. Na bronze ele aparece como veio da origem, com o valor em texto e o estado escrito de dois jeitos. Na prata, convertido e padronizado. Na ouro, somado por mês e por estado. À direita de cada faixa, quem consome aquela camada.

Bronze: o dado como chegou

A camada bronze guarda o dado exatamente como veio da origem: sem limpeza, sem correção e sem padronização, inclusive os erros.

Guardar dado errado de propósito parece contraintuitivo, e o motivo é prático: a bronze é a rede de segurança. Quando uma regra da camada seguinte se mostra equivocada — e isso acontece —, você reprocessa a partir da bronze em vez de puxar tudo da origem outra vez.

A origem pode não ter mais aquele histórico, pode ter mudado de estrutura, e pode estar fora do ar justamente no dia em que você precisar dela.

• Guarde quando e de onde o dado veio. Data da carga e identificação da origem, em coluna própria. Sem isso, reprocessar vira adivinhação.
• Só acrescente, nunca sobrescreva. Se a bronze é substituída a cada carga, ela deixou de ser rede de segurança e virou apenas uma cópia do estado atual.

O que não entra aqui: regra de negócio, junção entre tabelas, conversão de tipo e remoção de duplicado. Tudo isso é a camada seguinte.

Prata: onde o trabalho acontece

A camada prata é onde o dado é limpo, padronizado e integrado. É a que mais trabalho dá e a que menos aparece em apresentação.

• Conversão de tipo. Texto que vira número, texto que vira data. O R$ 1.234,56 que chegou como texto e o 19/08/2026 no formato daqui.
• Padronização. S e N de um sistema, 1 e 0 de outro, true e false de um terceiro, todos virando a mesma coisa.
• Remoção de duplicado. O mesmo cliente cadastrado em três origens.
• Validação. Campo obrigatório que veio vazio, chave que deveria ser única, valor fora da lista aceita.
• Junção entre tabelas relacionadas. Pedido com cliente, cliente com região.

O resultado é o dado confiável e detalhado, ainda sem agregação. É a camada que o analista usa para investigar, e a que o cientista de dados prefere, porque preserva o detalhe.

O que não entra na prata é a regra que depende de decisão da empresa: meta, comissão, classificação de cliente por faixa. Isso é ouro.

Ouro: o que o painel consome

A camada ouro é o dado pronto para o negócio. Agregado, modelado e organizado do jeito que a pergunta é feita.

Faturamento por mês e por região. Comissão calculada segundo a regra vigente. Cliente classificado por faixa de consumo. Tabelas de fatos e dimensões, se o modelo for dimensional.

É a camada mais próxima do painel e a mais volátil, porque regra de negócio muda com frequência. Está tudo bem que mude, desde que mude só ali.

E essa é a razão do padrão inteiro. Quando o comercial pede para alterar a regra de comissão, o trabalho fica confinado à ouro: a limpeza continua valendo, o dado bruto continua guardado, e nenhum outro relatório é afetado.

Uma regra de negócio deveria caber num lugar só.

Quando três camadas custam mais que ajudam

Esta é a parte que a maioria dos textos sobre o assunto não escreve.

Três camadas para um pipeline de cinco tabelas é estrutura demais para problema de menos. Cada camada é código a mais para manter, armazenamento a mais para pagar e um passo a mais para depurar quando o número não bate.

Duas camadas bastam quando as origens são poucas e estáveis, não há junção complexa entre elas, e a regra de negócio é simples o suficiente para viver junto da limpeza sem virar um nó.

Três camadas compensam quando qualquer um destes for verdade:

• Várias origens precisam ser reconciliadas entre si. O mesmo cliente, o mesmo produto, o mesmo pedido, escritos de jeitos diferentes.
• Mais de uma pessoa mexe no modelo. A separação vira contrato entre quem mantém a limpeza e quem mantém a regra.
• A regra de negócio muda com frequência. Cada mudança deveria tocar uma camada, não cinco consultas.
• Você já precisou reprocessar e não tinha de onde. Uma vez basta para a bronze se pagar.

O sinal mais confiável não é o volume de dado. É outro: quantas vezes você já teve que mexer em cinco lugares para mudar uma regra? Se a resposta é nenhuma, a camada a mais provavelmente não se paga ainda.

Onde o Januss entra

O medalhão é um padrão, não um recurso. Nenhuma ferramenta "tem" arquitetura medalhão — o que muda é quanto trabalho dá implementá-la.

No Januss, as três camadas são etapas do mesmo pipeline.

A bronze é a carga. O dado chega da origem no destino, com o modo de sincronização escolhido por tabela: carga completa, incremental, espelhamento ou histórico versionado. Para bancos, a leitura é do log de transações, o que preserva também as exclusões — informação que a bronze precisa guardar e que consulta agendada não captura.

A prata é a conversão mais as etapas de SQL. Treze regras de conversão encadeáveis por coluna, com oito formatos regionais, e a decisão coluna a coluna sobre o valor que não converte: parar a execução ou gravar nulo. Depois, etapas em SQL executadas dentro do banco de destino, com dependência entre elas e testes declarados que podem interromper a carga em vez de apenas avisar.

A ouro é a última etapa. SQL de agregação, materializado como tabela ou como visão, dependendo do que o painel precisa.

E há um detalhe de custo que vale saber antes da modelagem. A cobrança do Januss é por linha gravada, somando cada etapa que grava. Numa arquitetura de três camadas, a mesma linha pode ser contada três vezes. A saída é simples: transformação materializada como visão não copia dado e não consome franquia. Se a prata não precisa ser gravada, ela sai de graça, e só a ouro conta.

Duas coisas aparecem em quase todo texto sobre medalhão e o Januss não faz nenhuma das duas. Ele não desenha o mapa de linhagem entre as camadas, e não é um catálogo de dados.

O que ele sabe é qual etapa depende de qual, e usa isso para executar na ordem certa. Isso resolve a execução, não a documentação: não há uma tela que mostre de onde veio cada coluna da camada ouro.

Quer montar as três camadas com uma origem sua? São 14 dias de teste, sem cartão de crédito: criar seu ambiente.

Fontes

A definição do padrão e a frase citada acima vêm da documentação da Databricks, aberta em 27 de agosto de 2026:

• Databricks — What is the medallion lakehouse architecture?