Estado: Preview. A identidade "incremental == full" é provada por teste determinístico (esta capacidade = GA-candidato); a execução real no datalake e o custo faturado = NÃO MEDIDO. Dados de exemplo sintéticos.
Leia antes:
conceitos-fluxo-de-dados.md. Referência detalhada:ingestao-incremental-backfill.md.
A regra que não pode quebrar#
Existe um invariante único por trás de todos os modos incrementais: 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 o motivo no log).
"Um refresh caro é problema de custo; um número errado é problema de produto."
Os três modos, em linguagem de negócio#
Full (completa)
Recalcula tudo, do zero. É o fallback seguro sempre disponível: qualquer recusa de um modo incremental cai aqui. Correta por definição, é a mais cara.
- Use quando: é a 1ª carga; a tabela é pequena; a fonte apaga linhas e você não tem sinal de deleção; ou você quer a garantia máxima de exatidão.
Incremental por watermark (marca d'água)
Guarda a marca d'água — o maior valor de uma coluna que só cresce (uma data de
atualização, um id sequencial) — e, na próxima execução, busca só as linhas novas
(coluna > marca). O resto do histórico é reaproveitado intacto.
No pull de banco, isso é feito por KEYSET (seek): a consulta ordena pela coluna de
watermark (ORDER BY wm ASC) e filtra WHERE wm > <última marca>, avançando a marca
para o maior valor do último lote. Diferente de paginar por OFFSET, o KEYSET é
estável mesmo se a fonte muda durante a extração.
- Use quando: a tabela é grande e só cresce/atualiza (pedidos, eventos, lançamentos) e existe uma coluna crescente confiável.
- Não use quando: a fonte remove linhas fisicamente sem deixar rastro (veja "Semântica de deleção" abaixo) ou não há coluna crescente estável.
Backfill (carga histórica)
Trazer o histórico anterior à janela incremental — por exemplo, os últimos 24 meses quando o incremental só olha os últimos dias.
- Como: aumentar a janela recente (no incremental por período) ou rodar um full uma vez. No pull de banco/BigQuery, a primeira extração já é o backfill: percorre a paginação até o teto e as execuções seguintes retomam pelo watermark.
- Use quando: você acabou de conectar uma fonte, mudou a regra de negócio, ou precisa reprocessar um período específico.
Qual escolher (guia rápido)#
| Situação | Modo recomendado |
|---|---|
| Primeira carga de uma fonte | Full (é o backfill inicial) |
Tabela grande que só cresce, com data/id crescente | Incremental por watermark |
| Tabela pequena (poucos milhares de linhas) | Full (simples e barato o bastante) |
| Fonte que apaga linhas sem sinal de deleção | Full (ou período re-buscando dias inteiros) |
| Precisa reprocessar um histórico antigo | Backfill (janela ampla ou full pontual) |
Watermark não é CDC (honestidade)#
Isto é importante e o produto é explícito:
- Watermark (o que existe hoje): compara uma coluna crescente e traz o delta por
>. É simples, robusto e barato — mas não vê deleções e depende de a coluna crescer de fato. - CDC — Change Data Capture (Roadmap): ler o log de transações da fonte para capturar cada INSERT/UPDATE/DELETE. Não existe no Ingestia hoje. Não confunda os dois: quando esta documentação fala em "carga incremental", é sempre por watermark.
Semântica de deleção (limitação assumida)
O merge incremental é UPSERT por chave. Sem um sinal de deleção, o incremental não remove uma chave que sumiu da origem — o mesmo contrato de ferramentas como dbt e Power BI. Dois sinais opcionais restauram a exatidão sob deleção:
- partições completas — dentro de uma partição re-buscada por inteiro, a chave antiga ausente do delta é removida;
- tombstones (chaves deletadas) — deleções explícitas, quando a origem as fornece.
Um dado cuja origem apaga linhas não deve usar watermark puro. Use o modo por período (re-busca dias inteiros) ou faça full.
Por que o incremental "recusa e faz full"#
O produto prefere um refresh caro a um número errado. Ele cai para full, com motivo legível no log, quando: não há snapshot anterior; o snapshot está truncado/vazio/com erro; não há coluna de cursor utilizável; a ordenação não é exatamente a chave ASC; ou o delta não pode ser recortado com segurança. Isso é uma feature, não uma falha.
Limites e custos#
- Janela incremental por período: default 7 dias, teto 400.
- Paginação de extração: teto duro 10.000 páginas / 5.000.000 linhas.
- Fragmentação do pull de banco:
batchSizedefault 5.000 (entre 100 e 50.000);maxRowsdefault 200.000 (até 5.000.000). - Literal de cursor: ≤ 64 caracteres, sem aspas/barra/quebra (anti-injeção).
- O incremental existe para reduzir custo (menos bytes lidos). O custo faturado em BRL e a latência de nuvem permanecem NÃO MEDIDO — sem promessa.
Segurança#
Nomes de coluna (chave/cursor) são validados como identificadores simples antes de entrar no SQL; o valor do cursor usa bind por engine (parâmetro nomeado), nunca concatenação. Escopo por workspace em toda a carga.
Relacionados#
- Referência: full, incremental, backfill e checkpoint
- Tutorial: pipeline incremental por watermark
- Tutorial: executar backfill
- Como os dados fluem (visão geral)
Última revisão: 2026-09-08.