Orquestração com Airflow

Agende pipelines com dependências, novas tentativas e reprocessamento, entendendo DAGs, backfill, sensores e XCom.

Cerca de 16 min · Revisado em

Ao final, você vai conseguir

  • Explicar o que um orquestrador faz que o cron não faz
  • Ordenar tarefas de um DAG respeitando dependências e detectar ciclos
  • Ler um arquivo de DAG com TaskFlow e configurar agendamento, catchup e retries
  • Testar uma tarefa, limpar só a etapa que falhou e fazer um backfill pela linha de comando
  • Decidir o que pode passar por XCom e quando usar um sensor

Seu pipeline funciona quando você roda à mão. Agora ele precisa rodar sozinho toda madrugada, esperar o arquivo do parceiro chegar, tentar de novo quando a API cair e avisar alguém quando não tiver jeito. E, quando o financeiro pedir para refazer setembro inteiro, isso precisa ser um comando, não uma semana de trabalho. Quem cuida disso é um orquestrador, e o Apache Airflow é o mais pedido nas vagas de dados.

Do cron ao orquestrador

O jeito mais simples de agendar um programa é o cron, o agendador que vem no Linux. Uma linha diz “rode este comando todo dia às 3h”. Para um script isolado, é ótimo.

Uma linha de crontab: minuto, hora, dia do mês, mês, dia da semana, comando

0 3 * * * python /home/dados/pipeline.py >> /home/dados/pipeline.log 2>&1

O problema aparece quando o pipeline cresce. O cron não sabe que a carga de clientes depende da de pedidos, não tenta de novo, não guarda histórico de cada etapa e não sabe reprocessar dias passados. Um orquestrador cuida exatamente disso: dependências, agendamento, novas tentativas, histórico e alertas.

O cron dá conta, ou você precisa de um orquestrador?

O cron resolve · Precisa de orquestrador

  • Rodar um único script todo dia às 3h
  • Fazer um backup a cada hora
  • Rodar a carga de clientes só depois que a de pedidos terminar
  • Tentar de novo só a etapa que falhou, 5 minutos depois
  • Reprocessar os 30 dias de setembro, um por um
  • Ver o histórico de execuções e o log de cada etapa

Tarefas e dependências: o DAG

No Airflow, um pipeline é um DAG: um conjunto de tarefas ligadas por setas que dizem “esta roda antes daquela”. A sigla vem do inglês e descreve três regras.

Grafo (Graph)
Pontos ligados por setas. Cada ponto é uma tarefa, como “extrair pedidos” ou “carregar no banco”.
Direcionado (Directed)
Cada seta tem um sentido: de quem roda antes para quem roda depois.
Acíclico (Acyclic)
Seguindo as setas, nunca se volta a uma tarefa já visitada. Se A depende de B e B depende de A, nenhuma das duas consegue começar.

Um DAG de vendas tem estas tarefas. Coloque numa ordem em que as dependências sejam respeitadas.

  • Esperar o arquivo de vendas da loja chegar
  • Extrair as vendas do arquivo
  • Validar o esquema e as contagens
  • Carregar na tabela tratada
  • Rodar os modelos dbt dos marts
  • Avisar o time no chat que o painel foi atualizado

Para decidir o que roda, o Airflow faz algo simples: a cada momento, procura as tarefas cujas dependências já terminaram. Se houver várias prontas ao mesmo tempo, elas podem rodar em paralelo. Você vai implementar essa regra agora.

Quem pode rodar agora?

Complete a lista prontas: uma tarefa está pronta quando ainda não está em feitas e todas as tarefas de que ela depende já estão. Dica: all(a in feitas for a in antes). Rode e veja as rodadas.

dependencias = {
    "extrair_pedidos": [],
    "extrair_clientes": [],
    "validar": ["extrair_pedidos", "extrair_clientes"],
    "transformar": ["validar"],
    "carregar": ["transformar"],
    "avisar_time": ["carregar"],
}


def ordem_de_execucao(deps):
    feitas = []
    rodadas = []
    while len(feitas) < len(deps):
        # Uma tarefa está pronta quando ainda não foi feita
        # e TODAS as tarefas de que ela depende já foram feitas.
        prontas = []  # TODO: monte esta lista
        if not prontas:
            raise ValueError("ciclo ou dependência inexistente")
        rodadas.append(sorted(prontas))
        feitas.extend(sorted(prontas))
    return feitas, rodadas


try:
    ordem, rodadas = ordem_de_execucao(dependencias)
except ValueError as erro:
    ordem, rodadas = [], []
    print("Erro:", erro)

for numero, grupo in enumerate(rodadas, start=1):
    print(f"Rodada {numero}: {', '.join(grupo)}")

com_ciclo = {"a": ["b"], "b": ["a"]}
try:
    ordem_de_execucao(com_ciclo)
    print("Ciclo NÃO detectado")
except ValueError:
    print("Ciclo detectado: o Airflow recusaria este DAG")
  • As 6 tarefas aparecem, cada uma uma vez só
  • As duas extrações rodam juntas na primeira rodada
  • validar só roda depois das duas extrações
  • avisar_time é a última tarefa
O exemplo com ciclo (a depende de b, b depende de a) foi detectado. O que aconteceria se o programa não checasse if not prontas?

Nenhuma tarefa ficaria pronta e o laço rodaria para sempre, sem erro e sem progresso. Por isso o Airflow recusa DAGs com ciclo logo ao ler o arquivo, antes de qualquer execução.

Por dentro de um arquivo de DAG

Um DAG do Airflow é um arquivo Python numa pasta que o Airflow vigia, geralmente dags/. O jeito moderno de escrever é a TaskFlow API: funções Python comuns com os decoradores @dag e @task. Um decorador é a linha com @ acima da função, que muda o que ela significa.

O arquivo dags/vendas_diarias.py

from datetime import datetime, timedelta

from airflow.sdk import dag, task


@dag(
    schedule="0 3 * * *",
    start_date=datetime(2026, 10, 1),
    catchup=False,
    default_args={"retries": 2, "retry_delay": timedelta(minutes=5)},
)
def vendas_diarias():
    @task
    def extrair(ds=None):
        return f"bruto/pedidos/{ds}.csv"

    @task
    def transformar(caminho):
        return caminho.replace("bruto", "tratado")

    @task
    def carregar(caminho):
        print(f"Upsert de {caminho} na tabela pedidos")

    carregar(transformar(extrair()))


vendas_diarias()
  • Importação: Assim no Airflow 3. No Airflow 2, a mesma coisa vem de airflow.decorators. Se um tutorial antigo der erro de importação, é isso.
  • Agendamento: A mesma sintaxe do cron: todo dia às 3h. Também aceita atalhos como "@daily".
  • Data de início: A partir de quando existem períodos para processar. Não é “quando o DAG foi ligado”.
  • catchup: Com True, ao ligar o DAG o Airflow cria uma execução para cada período desde start_date que ainda não rodou. False começa do período mais recente.
  • Novas tentativas: Toda tarefa que falhar tenta mais 2 vezes, esperando 5 minutos entre elas. Só a tarefa que falhou repete; as que já deram certo ficam como estão.
  • Uma tarefa: Cada função com @task vira uma tarefa. O parâmetro ds é preenchido pelo Airflow com a data do período desta execução, no formato 2026-10-02.
  • Dependências: Passar o resultado de uma tarefa para outra cria a seta entre elas: extrair, depois transformar, depois carregar. Com operadores clássicos, a mesma ideia se escreve extrair >> transformar >> carregar.
  • Registro: Chamar a função no fim do arquivo é o que registra o DAG. Sem essa linha, ele não aparece na interface.

Complete o DAG: ele não deve criar execuções para dias passados, cada tarefa deve tentar até 3 vezes de novo, e baixar é uma tarefa.

@dag(
    schedule="0 6 * * *",
    start_date=datetime(2026, 10, 1),
    catchup=____,
    default_args={"____": 3},
)
def boletim_vacinacao():
    @____
    def baixar(ds=None):
        ...

Execuções, falhas e backfill

Cada execução de um DAG cuida de um intervalo de dados: a execução que roda às 3h do dia 3 processa os dados do dia 2. O Airflow entrega essa data para as tarefas (é o ds). Uma tarefa bem escrita usa essa data, nunca o relógio, para decidir o que processar.

Backfill é rodar o DAG para períodos passados: um mês que falhou, ou uma tabela nova que precisa de histórico. Com tarefas que usam ds e cargas idempotentes, é só pedir as datas. Se uma única tarefa falhou, você limpa (clear) só ela, e o Airflow a roda de novo junto com as que vêm depois.

Operando o Airflow pela linha de comando

Liste os DAGs, teste uma tarefa isolada, recupere uma falha e faça um backfill.

  1. Liste os DAGs que o Airflow encontrou.

    airflow dags list
    dag_id             | fileloc                              | owners  | is_paused
    ===================+======================================+=========+==========
    boletim_vacinacao  | /opt/airflow/dags/boletim.py         | airflow | True
    vendas_diarias     | /opt/airflow/dags/vendas_diarias.py  | airflow | False
  2. Teste só a tarefa extrair do DAG vendas_diarias para o dia 2026-10-02, sem afetar o histórico.

    airflow tasks test vendas_diarias extrair 2026-10-02
    INFO - Dependencies all met for dag_id=vendas_diarias, task_id=extrair
    INFO - Baixando pedidos de 2026-10-02 (página 1 de 2)
    INFO - 137 pedidos salvos em bruto/pedidos/2026-10-02.csv
    INFO - Done. Returned value was: bruto/pedidos/2026-10-02.csv
    INFO - Marking task as SUCCESS. dag_id=vendas_diarias, task_id=extrair
  3. Na madrugada do dia 6, carregar falhou nas 3 tentativas porque o banco estava em manutenção. O banco voltou. Limpe só essa tarefa no período 2026-10-05 para ela rodar de novo.

    airflow tasks clear vendas_diarias -t carregar -s 2026-10-05 -e 2026-10-05 -y
    <TaskInstance: vendas_diarias.carregar scheduled__2026-10-05T03:00:00+00:00 [failed]>
    Cleared 1 task instance(s). O scheduler vai rodar a tarefa de novo.
  4. A tabela de vendas foi criada agora e precisa do histórico de setembro. Crie um backfill de 2026-09-01 a 2026-09-30.

    airflow backfill create --dag-id vendas_diarias --from-date 2026-09-01 --to-date 2026-09-30
    Backfill criado para vendas_diarias: 30 execuções, de 2026-09-01 a 2026-09-30.
    As execuções entram na fila respeitando max_active_runs=3.

A tarefa carregar decide o período com datetime.now() - timedelta(days=1). O que acontece no backfill de setembro?

  • As 30 execuções carregam os dados de ontem, e setembro continua vazio
  • Funciona, porque o Airflow ajusta o relógio para cada execução
  • O Airflow recusa o backfill porque a tarefa usa datetime

Esperar e conversar: sensores e XCom

Às vezes o pipeline depende de algo que você não controla: o arquivo do parceiro que “chega entre 2h e 5h”. Um sensor é uma tarefa que verifica uma condição de tempos em tempos e só termina quando ela é verdadeira, ou quando o tempo limite estoura.

Um sensor que confere a cada 5 minutos, por até 3 horas

@task.sensor(poke_interval=300, timeout=3 * 60 * 60, mode="reschedule")
def esperar_arquivo(ds=None):
    return Path(f"/dados/entrada/vendas_{ds}.csv").exists()

O mode="reschedule" libera a vaga de execução entre uma conferência e outra. Sem ele, o sensor ocupa um trabalhador do Airflow parado por horas, esperando.

Quando uma tarefa devolve um valor, como o caminho do arquivo em extrair, o Airflow o guarda num XCom (cross-communication), uma mensagem curta salva no banco interno do próprio Airflow. Esse banco não foi feito para guardar dados de negócio: passe referências, não os dados.

O que pode passar entre tarefas por XCom?

Pode: pequeno · Não pode: grande demais

  • O caminho do arquivo extraído
  • A quantidade de linhas carregadas
  • O nome da tabela temporária criada
  • Uma lista com 2 milhões de pedidos
  • O conteúdo inteiro do CSV do dia
  • Todos os registros de clientes com CPF

Hoje é 14 de outubro. Você liga um DAG diário com start_date em 1º de janeiro e esqueceu de definir catchup=False, numa versão em que o padrão é True. O que acontece?

  • O Airflow cria perto de 290 execuções, uma para cada dia desde janeiro
  • Só a execução de hoje roda
  • O DAG não liga até você mudar a start_date

Fechamento

  • O cron agenda comandos; um orquestrador como o Airflow cuida de dependências, novas tentativas, histórico, alertas e reprocessamento.
  • Um DAG é um conjunto de tarefas ligadas por setas, sem ciclos; tarefas cujas dependências terminaram podem rodar em paralelo.
  • Na TaskFlow API, @dag define agendamento, start_date, catchup e retries, e cada função com @task vira uma tarefa.
  • Cada execução processa um intervalo de dados (ds); tarefas que usam essa data e cargas idempotentes tornam seguros os retries, o clear e o backfill.
  • Sensores esperam condições externas; XCom carrega só mensagens pequenas, como caminhos e contagens.

Orquestre o seu pipeline

Pegue o pipeline batch que você já roda à mão e coloque no Airflow local, usando o Docker Compose oficial ou airflow standalone num ambiente virtual.

  1. Escreva um DAG com TaskFlow que tenha pelo menos três tarefas (extrair, transformar, carregar), catchup=False e retries
  2. Faça cada tarefa usar ds para decidir o período e grave com upsert ou sobrescrevendo o dia
  3. Teste cada tarefa com airflow tasks test antes de ligar o DAG
  4. Provoque uma falha na tarefa de carga, corrija e use clear para rodar só ela de novo
  5. Faça um backfill de 7 dias e confira com SELECT COUNT(*) por dia que nada duplicou
  6. Registre no README um print do DAG na interface e como recuperar uma falha

Referências

Cursos relacionados