Backfill no Airflow 3: Controles e Limites

Se preferir começar por um resumo, peça um TL;DR ao ChatGPT ou ao Claude .

Índice

1. Políticas de reprocessamento
2. Concorrência não é isolamento de capacidade
3. Interrupções e retomada
4. Versão do código e efeitos históricos
5. Faça uma simulação antes de criar execuções
6. Três decisões comuns
   1. Recuperar datas sem execução
   2. Recalcular uma regra de negócio
   3. Corrigir falhas pontuais
7. Critério de conclusão
8. Referências

Backfill é a criação de DAG Runs para datas passadas. No Airflow 3, a operação pode ser iniciada pela CLI, pela API REST e pela interface. Isso centraliza o estado do reprocessamento, mas não torna as tasks idempotentes nem garante recuperação automática depois de qualquer interrupção.

A documentação oficial de Backfill limita o recurso a DAGs com agenda baseada em tempo. O intervalo informado é interpretado segundo o calendário do DAG.

Políticas de reprocessamento

O comportamento depende do estado das execuções existentes para cada data lógica:

• none: não cria outra execução quando já existe um DAG Run para a data, independentemente do estado;
• failed: cria uma execução quando o DAG Run mais recente daquela data falhou;
• completed: cria uma execução quando o DAG Run mais recente terminou com sucesso ou falha.

Na interface, essas opções aparecem como Missing Runs, Missing and Errored Runs e All Runs. Se a execução mais recente ainda estiver em estado running ou queued, o Airflow não cria outra para a mesma data, qualquer que seja a política escolhida.

Essas políticas tratam DAG Runs, não a correção de tasks específicas. Quando apenas algumas tasks precisam ser executadas novamente, limpar as instâncias afetadas pode ser mais proporcional do que criar um novo backfill.

Concorrência não é isolamento de capacidade

max_active_runs limita quantos DAG Runs daquele backfill podem ficar ativos ao mesmo tempo. Esse limite é aplicado separadamente do max_active_runs normal do DAG.

Separado não significa sem impacto. As execuções históricas continuam disputando workers, pools, conexões de banco, APIs, rede e armazenamento com outros workloads. Antes de escolher o valor, verifique:

• capacidade disponível nos pools e no executor;
• limites das fontes e destinos;
• volume processado por intervalo;
• duração e memória das tasks;
• efeito sobre os fluxos regulares;
• janela disponível para interromper o backfill se necessário.

Interrupções e retomada

O estado do backfill e dos DAG Runs permite observar o que foi criado e concluído. Isso não sustenta a afirmação de que qualquer processamento interrompido será retomado automaticamente do ponto exato.

O resultado depende do componente que falhou e da implementação da task:

• uma task falhada só será repetida automaticamente dentro da política de retries configurada;
• um worker pode morrer depois de alterar um sistema externo e antes de registrar sucesso;
• uma task sem checkpoint pode reiniciar todo o intervalo;
• uma escrita não idempotente pode duplicar dados ou efeitos;
• credenciais, código ou dependências podem continuar indisponíveis depois que o scheduler voltar.

Depois de uma interrupção, examine DAG Runs e task instances em queued, running ou failed. Decida entre aguardar, limpar tasks, corrigir a causa ou criar um novo backfill. Essa decisão não deve ser delegada apenas ao estado exibido na interface.

Versão do código e efeitos históricos

Aplicar uma regra nova ao passado exige saber qual versão do DAG e das dependências será executada. Também exige decidir se os resultados anteriores serão substituídos, versionados ou mantidos para auditoria.

Antes de reprocessar, confirme:

• versão do DAG, providers e bibliotecas;
• intervalo e timezone utilizados;
• disponibilidade das fontes históricas;
• destino e estratégia de sobrescrita;
• idempotência ou deduplicação;
• efeitos externos, como mensagens, cobranças e chamadas de APIs;
• validações de qualidade esperadas para cada partição.

Faça uma simulação antes de criar execuções

A CLI oferece --dry-run para listar as datas consideradas. A criação efetiva ainda depende dos estados existentes no momento da execução.

airflow backfill create \
  --dag-id vendas_diarias \
  --from-date 2026-07-01 \
  --to-date 2026-07-05 \
  --reprocess-behavior failed \
  --max-active-runs 2 \
  --dry-run

Depois de revisar as datas, execute o mesmo comando sem --dry-run. Eu começaria com um intervalo pequeno e compararia o resultado antes de ampliar o período.

Três decisões comuns

Recuperar datas sem execução

Use a política correspondente a execuções ausentes e valide se a fonte histórica voltou a ficar disponível. O término do DAG não demonstra sozinho que todas as partições foram preenchidas.

Recalcular uma regra de negócio

Use uma política que permita recriar execuções concluídas somente depois de definir versão do código, destino e reconciliação. Compare o resultado antigo com o novo antes de substituir dados usados por relatórios ou decisões.

Corrigir falhas pontuais

Se o DAG Run falhou e precisa ser recriado, a política failed pode selecionar essas datas. Se apenas algumas tasks precisam repetir, avalie limpar as instâncias específicas para evitar trabalho e efeitos desnecessários.

Critério de conclusão

Considere o backfill concluído quando:

• todas as datas esperadas foram criadas ou justificadamente ignoradas;
• DAG Runs e tasks terminaram nos estados previstos;
• contagens, partições e regras de qualidade foram reconciliadas;
• não houve duplicação de efeitos externos;
• o workload regular permaneceu dentro dos limites aceitos;
• falhas, intervenções e versões executadas ficaram registradas.

A interface melhora a operação e a rastreabilidade. A segurança do reprocessamento continua dependendo do desenho das tasks, da capacidade do ambiente e da validação dos dados produzidos.

Referências

APACHE AIRFLOW. Backfill. Disponível em: https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/backfill.html

APACHE AIRFLOW. DAG Runs. Disponível em: https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dag-run.html