Tutorial — executar um backfill (carga histórica)

Estado: Preview. As regras de janela e retomada são provadas por teste; a execução real no datalake e no worker = NÃO MEDIDO. Exemplos sintéticos.

Leia antes: Modos de carga · Referência: incremental e backfill.

O que é#

Backfill é trazer o histórico anterior à janela que o incremental normalmente cobre — por exemplo, os últimos 24 meses quando o refresh diário só olha os últimos dias.

Para que serve#

• Popular uma fonte recém-conectada com todo o histórico.
• Reprocessar um período específico após uma correção de regra.
• Ampliar a série temporal de um dashboard para trás.

Quando usar / quando não usar#

• Use quando: você acabou de conectar a fonte, mudou a lógica de negócio, ou precisa de um período antigo que o incremental não alcança.
• Não use quando: o histórico já está carregado e você só quer o dia a dia — aí o incremental por watermark basta.

Plano e permissões#

• Núcleo · verificação de acesso · chaves de desligamento para execução de ingestão, atualização de painéis.

Pré-requisitos#

1. Uma fonte conectada e testada.
2. Clareza do período ou volume que você quer trazer.

As três formas de fazer backfill#

Passo a passo#

1. Decida o alcance. Todo o histórico? Faça um full. Um período específico? Amplie a janela por período.
2. Backfill por full: abra a fonte, garanta as tabelas selecionadas e rode o pipeline em modo full (veja o tutorial de pipeline full).
3. Backfill por janela: aumente recentDays para cobrir o período desejado (teto 400 dias) e rode o refresh — ele recalcula a janela ampliada.
4. Backfill de conector novo: basta rodar a primeira extração; ela percorre a paginação até o teto duro. As execuções seguintes continuam do checkpoint.
5. Depois do backfill, volte ao incremental para o dia a dia (mais barato).

Exemplo (sintético)#

Você conectou um pedidos novo e quer os últimos 2 anos:

1) Rode um FULL uma vez → traz todo o histórico até o teto de paginação.
2) Ative o INCREMENTAL → coluna de watermark = atualizado_em.
3) Refresh diário → traz só o delta a partir daí.

Se precisar reprocessar só janeiro/2026 num agregado por período:

Aumente recentDays o suficiente para a janela cobrir 2026-01 e rode o refresh.

Como a retomada funciona (checkpoint)#

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

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

Assim a retomada não duplica nem perde linha. Conectores como o Azure Blob pulam blobs já processados (nome ≤ último processado) para não reprocessar.

Resultado esperado#

• O histórico desejado aparece no Bronze e, após o pipeline, nos marts Gold.
• Uma extração que bate o teto sinaliza hadMore (há mais na origem) — aí você amplia o teto conscientemente ou passa ao incremental.

Limites e custos#

• Teto duro de paginação: 10.000 páginas / 5.000.000 linhas.
• Janela por período: teto 400 dias.
• maxRows do pull: default 200.000 (até 5.000.000).
• Backfill lê muito — é a operação mais cara. Rode fora do horário de pico e volte ao incremental depois. Custo faturado em BRL = NÃO MEDIDO.

Segurança#

• Escopo por workspace em toda a carga; segredos redigidos em erros/logs.
• A retomada por checkpoint é escopada ao chamador; nenhum estado vaza entre clientes.

Erros comuns#

Diagnóstico#

• Cheque o histórico de execuções: bronzeRows/silverRows e se hadMore foi sinalizado.
• Para conectores, veja a observabilidade (execuções, freshness) para confirmar que a fonte está "em dia".

Relacionados#

• Modos de carga (conceito)
• Criar pipeline incremental por watermark
• Criar pipeline full

Última revisão: 2026-09-08.