Leia antes:
README.md. Camadas do medalhão empipeline-medalhao.md.
Escopo desta página — leia antes de procurar o campo na tela. Os três modos abaixo são do refresh incremental de snapshot (widget/mart). Eles não são os modos de escrita da camada Bronze: ali existem só
full(substituir) eappend(acrescentar) — verconceitos-modos-de-carga.md. Na Bronze a idempotência vem de apagar a janela no destino antes de acrescentar (DELETE da janela + acréscimo), não de umMERGE/upsert por chave; e a etapa Carga do pipeline não tem campo "chave de upsert" — a chave que você informa lá é a marca d'água do incremental. Deduplicação por chave de negócio é assunto das Transformações (Silver).
Verdade de produção (hoje). A carga incremental de rotina está ligada nos dois executores — o executor em nuvem e o caminho inline do pipeline pedem o plano de recorte e avançam a marca d'água depois de carregar. Mas a economia é por tabela, não por fonte: só carrega por recorte a tabela com ingestão Append e uma coluna-chave de data/hora. Sem as duas, a carga daquela tabela continua substituindo a tabela inteira — e é isso que a própria tela da etapa Carga informa, tabela por tabela, com o motivo por extenso.
Duas consequências práticas: deleção física na origem não é capturada por marca d'água (ver a seção de limites), e ligar uma cadência de minutos numa fonte cujas tabelas não recortam não reduz bytes. Nesse caso a tabela que não recorta mantém o ritmo de lote — uma carga por dia, como antes da cadência existir — em vez de recarregar a tabela inteira a cada poucos minutos. A tela da etapa Carga diz, tabela por tabela, quais recortam.
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:
- resultado particionável pela coluna de período (cada partição se calcula sozinha);
- consulta ordena pela coluna de período, ASC, como 1ª chave (histórico + recente já saem na ordem do full);
- 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 e não perde linha na fronteira do watermark. A repetição não duplica porque a carga apaga a janela no destino antes de acrescentar (DELETE da janela + acréscimo) — a idempotência vem daí, não de um MERGE por chave. - 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)#
- Estado — disponível. Elegibilidade e igualdade de resultado entre incremental e full são cobertas por testes automáticos.
- O que faz — atualiza snapshots sem recalcular tudo, com garantia de bater com resultado idêntico a cada execução com o full.
- Como funciona — full (fallback, substitui a tabela) · período (janela recente) · chave/watermark (delta por marca d'água, com a janela apagada antes do acréscimo) · backfill (janela ampla / 1ª extração) · checkpoint (retomada).
- 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.
- Custo — incremental existe para reduzir custo (menos bytes lidos → menor custo estimado); o teto de volume por consulta protege sempre.
- Limites — janela período default 7 / teto 400 dias; paginação teto 10.000 páginas / 5.000.000 linhas; cursor ≤ 64 chars.
- Segurança — nomes de coluna validados como identificadores; literal de cursor anti-injeção; escopo por workspace na carga.
- 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).
- Em resumo — incremental por período e por chave, com o mesmo resultado do full; quando não dá para garantir isso, o produto recorre ao full.