Backfill de pipeline: reprocessar sem reescrever o mês

Calendário de dias antigos sendo reprocessado por um tubo, com um mês lacrado intocado

Backfill de pipeline é reprocessar um período que já passou porque a regra, a fonte ou a carga falhou. O efeito certo é substituir aquele recorte pela leitura nova. O efeito errado é somar o mesmo pedido, a mesma nota ou o mesmo evento por cima do que a reunião já fechou.

Antes de apertar o botão, escreva três coisas: qual chave identifica o fato, qual janela pode mudar e qual janela está lacrada. Sem isso, o backfill vira um segundo histórico ao lado do primeiro.

Uma chave de documento substituindo o dia antigo em vez de empilhar uma segunda cópia
O dia reprocessado substitui o anterior. O mês já fechado permanece lacrado.

Quando o backfill é o remédio certo?

Vale quando a regra assinada mudou e o passado precisa da mesma definição, quando uma carga falhou e o dia ficou pela metade, ou quando um campo passou a vir preenchido e o histórico antigo está vazio. Não vale para “ver se o número fica mais bonito”.

Se o mês já foi apresentado como fechado, a correção entra como ajuste visível, não como edição muda. O backfill técnico pode recalcular a tabela. A narrativa do fechamento não se reescreve sozinha.

O que a chave impede no reprocesso?

A chave é o documento, o pedido ou o evento, não o horário em que a carga rodou. Ao reprocessar o dia 12, cada chave daquele dia substitui a versão anterior. Chave nova entra. Chave que sumiu da fonte sai, se a regra disser que ausência significa cancelamento.

Sem chave, a carga de backfill só sabe acrescentar. O dia 12 passa a ter duas cópias e a receita dobra. O teste mínimo, antes de produção, é reprocessar um dia pequeno e conferir que a contagem de chaves distintas não mudou além do que a fonte explica.

Situação na fonteO que o backfill fazO que não faz
Mesma chave, valor corrigidoSubstitui a linhaNão soma as duas versões
Chave nova no períodoIncluiNão inventa chave fora da janela
Chave sumiu e a regra é cancelarRemove ou marca canceladaNão deixa o valor antigo mudo
Mês lacradoNão entraNão reabre porque a query ficou fácil

Como marcar a janela que pode mudar?

A janela é um intervalo de datas de negócio, não “tudo até ontem”. Exemplo: notas emitidas entre 1 e 15 de março, porque o campo de frete passou a ser excluído nessa vigência. Abril não entra. Fevereiro fechado não entra.

Escreva também o que acontece na borda. Um pedido criado em fevereiro e faturado em março segue a data que a métrica usa, a da nota ou a do pedido, a mesma da definição oficial. Backfill com a data errada corrige um mês e fura o outro.

Como não derrubar o uso enquanto reprocessa?

O recorte novo se constrói ao lado e só troca a partição quando a checagem passa: volume, soma de controle e uma amostra de chaves. Trocar a tabela no meio da query faz a reunião ler metade do mês antigo e metade do novo.

O horário importa. Backfill de um ano inteiro no meio do expediente compete com o dashboard. Rode fora do uso, com teto de custo se o warehouse cobra por byte lido. Partição que não está na janela nem é lida.

O que fica registrado depois?

Fica a janela, a versão da regra, quem disparou e o resultado da checagem. Sem esse registro, daqui a um mês ninguém sabe se o salto do gráfico foi operação ou reprocesso. O catálogo da métrica aponta a vigência, se a definição mudou junto.

Um segundo backfill da mesma janela só roda se o primeiro ficou incompleto ou se a regra mudou de novo. Repetir por hábito gasta custo e abre chance de uma versão intermediária vazar para a tabela oficial.

Um exemplo de dia incompleto

A carga de terça terminou com metade das notas porque o ERP caiu às 11h. Quarta de manhã a fonte está completa. O backfill pede só a data de emissão de terça, substitui as chaves daquele dia e compara a soma com o relatório fiscal. Se fechar, a partição de terça troca. Segunda e quarta não se mexem.

Se alguém tivesse rodado “os últimos 90 dias” para garantir, o mês já apresentado entraria de novo na conta e qualquer correção fiscal antiga reabriria um fechamento. A janela curta é o que torna o backfill seguro.

Checklist prático

O backfill pode ir para produção quando a janela, a chave e a checagem estão escritas.

  • Motivo do reprocesso escrito: falha de carga, regra nova ou campo que passou a vir
  • Chave de negócio que substitui a linha, em vez de acrescentar
  • Janela de datas de negócio, com a borda da métrica explícita
  • Mês ou período lacrado fora do recorte
  • Construção ao lado e troca só depois da soma de controle
  • Custo e horário fora do pico de uso do dashboard
  • Registro de quem disparou, qual versão e qual janela
  • Proibição de repetir a mesma janela sem motivo novo

Erros comuns

O mês dobrado quase sempre nasce de um destes atalhos.

  • Reprocessar “tudo” porque é mais simples do que escolher a data
  • Carga que só insere e nunca substitui a chave
  • Trocar a tabela oficial no meio da execução
  • Usar a data da carga em vez da data do documento
  • Reabrir mês fechado sem decisão de quem apresentou o número
  • Não comparar a soma com um relatório de controle da fonte
  • Rodar o ano inteiro no horário em que a diretoria abre o painel
  • Repetir o mesmo backfill sem registrar a versão anterior

Onde o reprocesso entra na engenharia?

Em engenharia de dados, o backfill de pipeline é uma publicação do passado: janela, chave e checagem, não um botão de recarregar tudo.

Perguntas frequentes

▸Todo erro de carga pede backfill?

Não. Se a carga seguinte já reescreve o dia em aberto pela chave, o dia se corrige sozinho. Backfill é para o período que a rotina normal não vai mais tocar, ou para uma regra que precisa valer num recorte antigo.

▸Posso reprocessar o ano para padronizar a métrica?

Pode se a definição nova foi assinada para valer no histórico e se o mês fechado tem uma decisão explícita. Sem isso, padronizar reescreve uma reunião que já aconteceu. A janela começa onde a vigência começa.

▸Como saber se duplicou?

Pela contagem de chaves distintas e pela soma contra o relatório da fonte, antes de trocar a partição oficial. Se as duas versões do mesmo documento aparecem juntas, a carga acrescentou em vez de substituir.

▸Backfill e carga diária podem rodar juntos?

Só se escreverem partições diferentes, ou se a diária esperar a troca terminar. Os dois escrevendo o mesmo dia produzem uma corrida: um termina com a versão que o outro acabou de apagar.

▸E se a fonte também mudou o documento antigo?

A leitura nova traz o documento como a fonte está agora. Se a fonte corrigiu um imposto, o backfill acompanha, dentro da janela. Fora da janela, a mudança da fonte espera uma decisão, não entra de carona.

▸Preciso avisar quem usa o número?

Sim quando o valor de um período já mostrado muda. O registro técnico não substitui o aviso. A ficha da métrica ganha a data do reprocesso e o motivo, para a comparação entre meses continuar explicável.