Pipeline de dados — Bronze, Silver e Gold

Estado: Preview. Execução determinística provada em teste; execução real no datalake e no worker = NÃO MEDIDO — custo e latência de nuvem não são medidos e, por isso, não são publicados. Isso descreve a medição, não uma fila de liberação: a execução depende de o ambiente de nuvem do workspace estar configurado (sem ele, falha com mensagem em vez de fingir sucesso). Dados de exemplo sintéticos.

Leia antes: README.md (vocabulário + template). Incremental/backfill/checkpoint estão em ingestao-incremental-backfill.md; agendamento/retry/DLQ em agendamento-retry-dlq.md.

As duas trilhas ao vivo#

O produto mostra o progresso em tempo real com passos serializáveis (client + server).

Ingestão de uma fonte (detalhe do pipeline /sources/[id], seção "Tabelas do Bronze" → "Ingerir ao vivo"):

validar → landing → bronze → registrar

• validar — confere conexão e credenciais cifradas
• landing — envia os brutos para a landing
• bronze — carrega verbatim na camada Bronze do datalake
• registrar — atualiza catálogo e última sincronização (grava lastSyncAt)

Pipeline de engenharia (página /pipeline):

ingest → bronze → silver → gold → publish

O que cada camada faz (implementação de referência determinística)#

O pipeline tem uma implementação de referência (em dev roda sobre SQLite; os mesmos contratos valem no datalake por workspace). Dados de exemplo: uma tabela sintética vendas com colunas pedido_id, data_pedido, cliente_id, uf, categoria, produto, preco_unitario, quantidade, forma_pagamento, status.

Bronze — cru, verbatim, auditável

• Ingestão verbatim em transação: cada linha da origem entra como texto, sem conversão, com carimbos _ingest_at, _source, _row.
• Garante o nº de campos (preenche faltantes com "") — nunca descarta linha na Bronze.
• No caminho SaaS/landing, os brutos vão para landing/<prefix>/_saas/<sourceId>/<stamp>/<tabela>/chunk-NNNN.json em NDJSON (um objeto por linha), depois uma única carga lê todos os pedaços.

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

Regras de qualidade aplicadas linha a linha (uma reprovação = linha descartada, contada em rejectedRows):

rejectedRows = bronzeRows − silverRows — a diferença é sempre visível (nada some em silêncio).

Gold — datamarts agregados

Marts recriados a cada run (idempotente): gold_receita_mensal, gold_receita_uf, gold_receita_categoria (com share), gold_kpis (linha única: receita total, pedidos, ticket médio, nº de UFs, período). Cada run grava um pipeline_runs (bronze/silver/rejected/marts/duração/KPIs).

Publish

O upsert do dashboard gold republica o painel público (published: true) — rodar o pipeline torna os dados gold visíveis sem ação manual.

Ficha (template dos 9 campos)#

1. Estado — Preview. Pipeline determinístico provado em teste; materialização real no datalake = NÃO MEDIDO (liberação em nuvem ainda não exercida).
2. O que faz — leva dados da origem até marts Gold prontos para dashboard, passando por qualidade e deduplicação na Silver.
3. Como funciona — medalhão Bronze→Silver→Gold; Bronze verbatim, Silver com regras de qualidade + dedupe, Gold agregado. Datasets por workspace <prefix>_bronze/_silver/_gold.
4. Plano · Permissão — núcleo · verificação de acesso · chaves de desligamento para execução de ingestão (carga) e atualização de painéis (republicar).
5. Custo — as cargas e consultas no datalake são cobráveis; o custo é estimado pelo motor de custo e limitado por um teto de bytes faturáveis (ver custo-limites-seguranca.md). Custo faturado real = NÃO MEDIDO.
6. Limites — profiling: teto 50 colunas, 5 exemplos × 60 chars, payload 32 KiB; carga SaaS default batchSize 5.000 / maxRows 200.000.
7. Segurança — datasets/buckets escopados por workspace; nomes de coluna interpolados só a partir de allowlist; PII mascarada no profiling.
8. Como validar — no console, rode o pipeline de um workspace de exemplo e confira, na tela de execução, os contadores Bronze/Silver/rejeitadas e os marts Gold gerados; o painel gold é republicado automaticamente ao final.
9. Estado real / claim permitido — "Pipeline medalhão determinístico (qualidade + dedupe) provado; materialização real no datalake pendente de liberação em nuvem."

Profiling do catálogo (amostra segura)#

O profiling é puro. Dada uma amostra + o schema, computa por coluna: tipo declarado × inferido (divergência = sinal de sujeira), % de nulos, nº de distintos (sempre estimativa), min/max de numéricas/datas, comprimento médio de texto e até 5 exemplos.

Segurança embutida (o motivo do módulo existir separado):

• Coluna PII → exemplos viram •••; min/max/distintos/comprimento suprimidos (só a % de nulos sobrevive).
• Coluna oculta (governança) → nem aparece (o nome não viaja).
• Tetos: 50 colunas, exemplo 60 chars, payload total ≤ 32 KiB (corta com aviso).

Schema drift (o mart não quebra em silêncio)#

O schema descoberto vira um baseline serializável e é comparado baseline × atual:

A severidade é a pior encontrada; o mart é marcado como "quebra" quando há atencao.

Saneamento automático da carga (o pipeline não quebra por nome de chave)#

O saneamento é o plano B da carga no datalake: a ingestão agendada puxa arquivos dos sistemas do cliente direto para a landing — chaves com acento/espaço/vazias ("preço", "nome do cliente") derrubariam o load ("Invalid field name"). Quando o load NDJSON falha, o arquivo é saneado (minúsculas, sem acento, _; vazia → coluna; começa com número → col_) e recarregado. Também explode envelopes ({meta..., data:[...]}) e converte array/pretty-JSON para NDJSON. Regra conservadora: linha não-parseável é mantida como está (não inventa dado).

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

As transformações de negócio são uma IR versionada compilada para SQL determinístico (passos pt-BR: substituir, texto, datas, dividir, condicional; group-by/joins com prevenção de fan-out consciente de grão). Versionamento, execução paralela de conferência e rollback são provados; a publicação real no datalake é liberação em nuvem ainda não exercida. As saídas são congeladas pelo conjunto de testes de referência, com resultado idêntico a cada execução.