Tutorial — criar uma validação de qualidade

Estado: Preview. As regras de qualidade e a deduplicação são provadas por teste e congeladas pelo conjunto de testes de referência; a materialização real no datalake = NÃO MEDIDO. Exemplos sintéticos.

Leia antes: Qualidade, deduplicação e rejeitados · Pipeline medalhão.

O que é#

Uma validação de qualidade é o conjunto de regras aplicadas na passagem Bronze → Silver: o que é válido segue para a Silver; o que reprova é contado e fica de fora (o cru permanece no Bronze). Este tutorial mostra como pensar, aplicar e medir essas regras.

Para que serve#

Evitar que dado sujo (data inválida, preço zero, duplicata) contamine dashboards e respostas — e medir quanto do seu dado está fora do padrão.

Quando usar / quando não usar#

• Use sempre: toda fonte que vira dashboard precisa passar pela Silver.
• Não trate a Silver como descarte definitivo — o Bronze guarda o cru para inspeção e reprocessamento.

Plano e permissões#

• Núcleo · verificação de acesso · chave de desligamento execução de ingestão.

Pré-requisitos#

1. Dados já no Bronze (via pipeline full ou importar arquivo).
2. Saber qual é a chave de negócio da tabela (para deduplicar).

Tipos de regra (e o que cada uma faz)#

Regra de ouro: corrija quando é seguro (preenchimento/normalização) e descarte quando não é (obrigatório/domínio/tipo). Toda linha descartada entra na conta de rejeitadas.

Passo a passo#

1. Escolha a chave de deduplicação (ex.: pedido_id).
2. Liste as regras duras (que descartam): campos obrigatórios, domínios proibidos, formatos de data/número, UF válida.
3. Liste as regras brandas (que corrigem): preenchimento de vazios, normalização.
4. Defina as derivações (ex.: receita).
5. Aplique na transformação Silver e rode o pipeline.
6. Meça: confira rejectedRows = bronzeRows − silverRows no registro de execução.
7. Investigue picos de rejeição olhando o Bronze (o cru está lá).

Exemplo (sintético)#

Dado sujo no Bronze:

pedido_id;data_pedido;uf;categoria;preco_unitario;quantidade;status
P-1001;2026-01-03;SP;Bebidas;12,90;3;pago
P-1001;2026-01-03;SP;Bebidas;12,90;3;pago # duplicata → descarta a 2ª
P-1002;2026/01/03;RJ;Limpeza;29,90;1;pago # data inválida → descarta
P-1003;2026-01-04;Minas;Bebidas;12,90;2;pago # UF inválida → descarta
P-1004;2026-01-04;MG;;0;1;pago # preço 0 → descarta
P-1005;2026-01-05;MG;;12,90;2;cancelado # cancelado → descarta
P-1006;2026-01-05;SP;;12,90;2;pago # categoria vazia → "Sem categoria" (mantém)

Resultado: de 7 linhas no Bronze, 1 passa para a Silver (P-1006, com categoria "Sem categoria" e receita = 25,80); 6 rejeitadas — e você vê exatamente isso no contador.

Resultado esperado#

• Silver só com linhas válidas e sem duplicatas por chave.
• Contador de rejeitadas explícito por execução (nada some em silêncio).
• Aviso de schema drift quando a fonte muda: coluna nova → info; coluna removida / tipo mudado / tabela removida → atencao (o mart que a lê é marcado como "quebra").

Limites e custos#

• Profiling seguro: teto 50 colunas, 5 exemplos × 60 chars, payload ≤ 32 KiB.
• As regras rodam na carga (sem custo de plataforma extra além do load/queries). Custo faturado em BRL = NÃO MEDIDO.

Segurança#

• Coluna PII no profiling → exemplos •••, min/max/distintos suprimidos.
• Coluna oculta por governança → nem aparece.
• O cru rejeitado continua apenas no Bronze do seu workspace, nunca exposto a outro.

Erros comuns#

Diagnóstico#

• Compare bronzeRows × silverRows a cada run; um salto de rejeição indica mudança na fonte.
• Use o profiling para ver % de nulos e tipo inferido × declarado (divergência = sujeira).

Relacionados#

• Qualidade, deduplicação e rejeitados (conceito)
• Construir Bronze/Silver/Gold
• Tratar falha e DLQ

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