Tutorial — construir as camadas Bronze, Silver e Gold

Estado: Preview. As transformações são compiladas para SQL determinístico e congeladas pelo conjunto de testes de referência, com resultado idêntico a cada execução; a publicação real no datalake = NÃO MEDIDO. Exemplos sintéticos.

Leia antes: Pipeline medalhão · Como os dados fluem.

O que é#

O medalhão organiza o datalake em três camadas com papéis claros:

• Bronze — o dado cru e verbatim, como chegou, auditável.
• Silver — o dado limpo, tipado e deduplicado, pronto para modelar.
• Gold — os marts agregados, prontos para dashboards e Q&A.

Para que serve#

Separar "o que chegou" de "o que está limpo" de "o que está pronto" — para que um erro de transformação nunca destrua o dado original e cada camada tenha um propósito único.

Quando usar / quando não usar#

• Use sempre que quiser dados confiáveis para dashboards: o medalhão é o caminho padrão de qualquer fonte.
• Não pule direto para o Gold sem passar pela Silver — a qualidade e a deduplicação moram lá.

Plano e permissões#

• Núcleo · verificação de acesso · chaves de desligamento para execução de ingestão, atualização de painéis.

Pré-requisitos#

1. Uma fonte conectada com dados já no Bronze (via pipeline full ou importar arquivo).

Passo a passo#

1) Bronze — cru e auditável

• A ingestão grava cada linha verbatim (como texto), garantindo o número de campos (preenche faltantes com "") e adicionando carimbos _ingest_at, _source, _row.
• Nada é descartado no Bronze. É a sua retenção do dado original.
• No caminho SaaS/landing, os brutos viram NDJSON em landing/<prefix>/_saas/<sourceId>/<stamp>/<tabela>/chunk-NNNN.json e um único load job lê o glob chunk-*.json.

2) Silver — limpeza, tipagem, qualidade e deduplicação

As regras rodam linha a linha; uma reprovação = a linha não entra na Silver e é contada em rejectedRows. No exemplo vendas:

rejectedRows = bronzeRows − silverRows — a diferença é sempre visível.

3) Transformações Silver → Gold (código versionado)

As regras de negócio são uma IR versionada compilada para SQL determinístico. Os passos disponíveis (em pt-BR): substituir, texto, datas, dividir, condicional, além de group-by/joins com prevenção de fan-out consciente de grão. Versionamento, execução paralela de conferência (rodar sem publicar) e rollback são provados.

4) Gold — marts agregados

Os marts são recriados a cada run (idempotentes). No exemplo:

5) Publish

O upsert do dashboard Gold republica o painel automaticamente — rodar o pipeline torna os dados Gold visíveis sem ação manual.

Exemplo (sintético)#

Uma transformação de negócio típica na Silver → Gold:

1) datas: data_pedido → mes (YYYY-MM)
2) condicional: categoria vazia → "Sem categoria"
3) dividir: receita = preco_unitario × quantidade
4) group-by: SUM(receita), COUNT(*) por mes → gold_receita_mensal

Resultado esperado#

• Bronze com todas as linhas cruas; Silver com as linhas limpas e deduplicadas; Gold com os marts recriados.
• Um registro de execução com Bronze / Silver / rejeitadas / nº de marts / duração / KPIs.

Limites e custos#

• Profiling: teto 50 colunas, 5 exemplos × 60 chars, payload ≤ 32 KiB.
• Carga SaaS → Bronze: default batchSize 5.000, maxRows 200.000.
• Consultas no datalake são cobráveis e limitadas pelo teto de bytes faturáveis. Custo faturado em BRL = NÃO MEDIDO.

Segurança#

• Datasets escopados por workspace; nomes de coluna interpolados só a partir de allowlist.
• Schema drift avisa quando uma coluna some / muda de tipo (o mart não quebra em silêncio) — veja Qualidade.

Erros comuns#

Diagnóstico#

• Use o execução paralela de conferência para validar uma transformação antes de publicar.
• Compare os contadores Bronze/Silver/rejeitadas entre execuções.

Relacionados#

• Pipeline medalhão (referência)
• Criar validação de qualidade
• Criar pipeline full
• Acrescentar uma coluna numa tabela Silver ou Gold

Última revisão: 2026-09-08.