Ingestão — full, incremental, backfill e checkpoint

Estado: Preview. Identidade incremental==full provada em teste determinístico; execução real no datalake = NÃO MEDIDO.

Leia antes: README.md. Camadas do medalhão em pipeline-medalhao.md.

A regra que não pode quebrar#

Em todos os modos incrementais vale um invariante único: o resultado incremental tem de ser IDÊNTICO ao refresh completo — mesmas linhas, mesma ordem. Se houver a menor dúvida de elegibilidade, o produto recusa o incremental e faz o full (com motivo legível no log).

"Um refresh caro é problema de custo; um número errado é problema de produto."

Modo 1 — Full (completo)#

Recalcula tudo. É o fallback seguro sempre disponível: qualquer recusa de elegibilidade de um modo incremental cai aqui. Correto por definição, mais caro.

Modo 2 — Incremental por PERÍODO#

Para agregados por período (todo GROUP BY dia/mês): recalcula só a janela recente (default 7 dias, teto 400) e reaproveita o histórico do snapshot anterior.

Três condições que sustentam a identidade:

1. resultado particionável pela coluna de período (cada partição se calcula sozinha);
2. consulta ordena pela coluna de período, ASC, como 1ª chave (histórico + recente já saem na ordem do full);
3. snapshot anterior não truncado.

• Fuso: a chave de partição sai no fuso do painel (America/Sao_Paulo), nunca UTC — a venda das 22h do dia 31 em SP é 01h do dia 1º em UTC e cairia no mês errado.
• Limitação assumida: dado que chega atrasado com data mais velha que a janela não é recalculado (mesmo contrato de Power BI/dbt).
• Tipos de coluna: date (compara direto) · timestamp (converte para o fuso antes).

Modo 3 — Incremental por CHAVE / watermark#

Para tabelas de detalhe com id estável: guarda uma marca d'água (o maior valor da coluna-cursor no snapshot anterior) e, no próximo refresh, busca só as linhas com cursor >= marca (o delta). Cada linha do delta faz UPSERT por chave sobre o snapshot; o resto do histórico é reaproveitado intacto.

• Predicado >= (não >) de propósito: re-busca a linha exatamente na marca (upsert é idempotente) e não perde linha na fronteira do watermark.
• Marca d'água = maior valor do cursor entre as linhas; sem cursor utilizável → grava null → próximo refresh cai no full (seguro).

Semântica de deleção (limitação assumida): merge por chave é UPSERT. Sem sinal de deleção, o incremental não remove uma chave que sumiu da origem (mesmo contrato de qualquer watermark: dbt, Power BI). Dois sinais opcionais restauram a identidade sob deleção:

• completePartitions — dentro de uma partição re-buscada por inteiro, a chave antiga ausente do delta É removida;
• deletedKeys — tombstones explícitos (CDC com deleção).

Um visual cuja origem apaga linhas não deve usar mode:"key" puro — use o modo por período (re-busca dias inteiros) ou passe um dos sinais acima.

Recusas → full (cada uma com motivo): widget sem incremental configurado · sem SQL · sem snapshot anterior · snapshot com erro/truncado/vazio · sem cursor no snapshot anterior (caso N−1) · ORDER BY não é exatamente as chaves ASC · chave ausente em alguma linha do histórico · delta não recortável com segurança.

Anti-injeção: nomes de coluna (chaves/cursor) são validados como identificadores simples antes de entrar crus no SQL; o literal do cursor recusa aspas/barra/quebra e comprimento > 64 (fora disso → faz full).

Compatibilidade N−1: um leitor novo lê snapshot antigo (sem cursor) sem quebrar; e diante de snapshot antigo, recusa incremental e faz full.

Backfill (carga histórica)#

Backfill = trazer o histórico anterior à janela incremental. Na prática:

• Por período: aumentar recentDays (até o teto 400) força o recálculo de uma janela maior; um full cobre todo o histórico de uma vez.
• Por conector: a extração inicial percorre a paginação até o teto duro (default 10.000 páginas / 5.000.000 linhas) — a primeira execução é o backfill; as seguintes retomam por checkpoint/watermark. Conectores como Azure Blob pulam blobs já processados (nome ≤ último processado) para não reprocessar.

Checkpoint (retomada sem duplicar nem perder)#

O SDK de conectores expõe um contrato injetável de checkpoint (onde o estado mora — banco do produto/cache gerenciado/memória — é decisão do chamador; nenhuma tabela nasce no SDK):

• lê o checkpoint antes de extrair;
• grava após cada lote entregue (só conta lotes aceitos);
• limpa (null) ao concluir → a próxima execução agendada recomeça do zero.

Semântica: o checkpoint só existe entre a interrupção e a retomada. O retry vive abaixo da extração, então cada lote nunca é entregue duas vezes.

Ficha (template dos 9 campos)#

1. Estado — Preview. Elegibilidade e identidade incremental==full provadas por teste determinístico; execução real no datalake = NÃO MEDIDO.
2. O que faz — atualiza snapshots sem recalcular tudo, com garantia de bater com resultado idêntico a cada execução com o full.
3. Como funciona — full (fallback) · período (janela recente) · chave/watermark (delta + upsert) · backfill (janela ampla / 1ª extração) · checkpoint (retomada).
4. Plano · Permissão — núcleo · verificação de acesso · chaves de desligamento para execução de ingestão / atualização de painéis / consultas no console de dados.
5. Custo — incremental existe para reduzir custo (menos bytes lidos → menor custo estimado); o teto de volume por consulta protege sempre. Custo real = NÃO MEDIDO.
6. Limites — janela período default 7 / teto 400 dias; paginação teto 10.000 páginas / 5.000.000 linhas; cursor ≤ 64 chars.
7. Segurança — nomes de coluna validados como identificadores; literal de cursor anti-injeção; escopo por workspace na carga.
8. Como validar — no console, ative o incremental num visual de série temporal e confirme que o número do refresh incremental bate com o do refresh completo; force uma condição não elegível e confirme que o produto recorre ao full (por segurança do número).
9. Estado real / claim permitido — "Incremental por período e por chave (com compat N−1) provado determinístico; identidade com o full garantida por recusa conservadora."