Histórico e retomada sem duplicar

Selo de estado: Preview (teto atual do produto) · Curso ACD-220 — Pipelines e medalhão Bronze/Silver/Gold · Aula 5 de 12 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai executar backfill com checkpoint — trazer histórico anterior à janela do dia a dia, escolhendo a forma certa e sabendo o que a escrita faz no destino.

Vídeo#

Identificador no manifesto: acd-220-05-backfill-e-checkpoint · duração-alvo 7 min · tela do produto: /sources.

Roteiro de gravação (5 capítulos):

Conteúdo#

Backfill é trazer o que está atrás da janela

Backfill é trazer o histórico anterior à janela que o dia a dia cobre — por exemplo, os últimos 24 meses quando a carga diária só olha os últimos dias. Use quando acabou de conectar uma fonte, mudou uma regra de negócio, ou precisa reprocessar um período específico.

As três formas, e qual escolher

Depois do backfill, volte ao dia a dia (Append), que é mais barato. Backfill lê muito — é a operação mais cara do curso.

"Dias para retroagir" não é um teto global

Três números diferentes convivem no produto, e confundi-los gera expectativa errada:

A frase que a própria tela exibe resolve o resto: "Horário de EXECUÇÃO ≠ intervalo dos DADOS. O horário acima diz quando a carga roda; a janela de reprocessamento (dias para retroagir) diz que período é processado."

Reprocessar período: ler a política de escrita antes de confirmar

Na recuperação de uma execução existem quatro modos distintos — e antes eles pareciam a mesma coisa:

O quarto só tem efeito de recorte quando existe uma coluna de recorte (a coluna-chave do Append). A prévia declara a política de escrita:

• substituicao_total — a carga substitui a tabela inteira. O período não filtra nada: serve de rastro do que foi pedido, e a tela diz isso em vez de prometer um filtro que não acontece.
• recorte_por_intervalo — a extração filtra coluna >= início AND coluna < fim e a escrita apaga só as linhas daquela janela antes de acrescentar as novas. Idempotente dentro da janela, sem tocar no resto do histórico.

A janela pedida é validada e as recusas são explícitas, porque cada uma delas apagaria ou reescreveria dado errado: sem início ou sem fim (não se inventa "últimos N dias"), início ≥ fim, fim no futuro, ou janela maior que o teto (seria recarga total disfarçada).

Checkpoint: retomar sem duplicar nem perder

Numa extração longa que é interrompida, o SDK de conectores usa um checkpoint:

• lê o checkpoint antes de extrair;
• grava depois de cada lote entregue — e só conta lote aceito;
• limpa ao concluir, para que a próxima execução agendada recomece do zero.

A semântica importa: 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. Conectores de arquivo pulam blobs já processados (nome ≤ último processado) para não reprocessar.

Tetos que você precisa saber de cabeça

Quando a extração bate o teto, ela sinaliza hadMore: há mais na origem. Aí você amplia o teto conscientemente ou fatia o backfill por período — não aumente no escuro.

Exemplo: a Comércio Aurora

Maria conectou vendas e quer os últimos 90 dias. Caminho: (1) roda um Full uma vez, que traz o histórico até o teto de paginação; (2) troca vendas para Append com atualizado_em; (3) deixa Dias para retroagir = 7 na Operação, para recuperar vendas que chegam atrasadas; (4) quando descobre que janeiro veio errado por causa de uma regra antiga, usa Reprocessar período de 2026-01-01 a 2026-02-01, lê na prévia que a política é recorte_por_intervalo e confirma — o resto do histórico não é tocado. Se a prévia dissesse substituicao_total, ela saberia que a tabela inteira seria reescrita e decidiria com essa informação.

Erros comuns

Faça você mesmo#

No workspace de treino Aurora Varejo, em vendas, com dados sintéticos cujo histórico você conhece.

1. Em /sources, abra o pipeline de vendas e, na etapa Operação, leia o campo Dias para retroagir. Coloque 7 e leia o texto de ajuda.
2. Leia a caixa "Horário de EXECUÇÃO ≠ intervalo dos DADOS" e explique para você mesmo a diferença em uma frase.
3. Publique e rode um Full uma vez (o backfill inicial). Anote a contagem na Bronze e a data mais antiga presente.
4. Troque vendas para Append com atualizado_em, publique e rode. Confirme que a contagem cresceu sem reler o histórico.
5. Em /dags, na execução, abra a recuperação e escolha Reprocessar período. Peça uma janela de 90 dias e leia a prévia: política de escrita, tarefas incluídas e efeito no destino.
6. Confirme o reprocessamento e, ao final, confira no Console de dados que apenas as linhas daquele período mudaram — a data mais antiga do passo 3 continua lá.
7. Repita o mesmo reprocessamento e confirme que a contagem não mudou (idempotente dentro da janela).
8. Peça de propósito uma janela inválida (fim no futuro, ou mais de 366 dias) e leia a recusa.

Você terminou quando o histórico de 90 dias está na Bronze, você leu a política de escrita na prévia antes de confirmar, o reprocessamento repetido não duplicou nada, e você consegue explicar por que ligar a agenda não recupera o atraso.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• data/tutoriais/executar-backfill
• data/ingestao-incremental-backfill
• orquestracao/recuperar-uma-falha

Capacidades ensinadas#

C07.1 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".