Airflow para iniciantes: seu primeiro DAG em 45 minutos
Se você é DE Jr ou está em transição para DA, o Apache Airflow pode ajudar a sair do improviso de crons e scripts isolados para uma rotina de orquestração mais previsível.
Na prática, o Airflow permite visualizar fluxos, organizar dependências, reprocessar etapas específicas, configurar tentativas automáticas (retries) e acompanhar falhas com mais clareza. Além disso, ele cria uma base melhor para quando o pipeline deixa de ser um script local e passa a ser responsabilidade do time.
A proposta deste guia é direta: em cerca de 45 minutos, você vai entender os blocos essenciais e estruturar um pipeline ponta a ponta, seguindo o fluxo ingestão → transformação → carga. Ao longo do caminho, também verá boas práticas que ajudam esse primeiro DAG a evoluir do ambiente local para uma operação mais colaborativa.
Conceitos-chave (sem “bla-bla-bla”)
Antes de criar o primeiro pipeline, vale alinhar alguns conceitos. Dessa forma, você entende o papel de cada peça e evita tratar o Airflow como apenas “um cron com tela bonita”.
DAG
Um DAG, ou Directed Acyclic Graph, é o workflow do Airflow. Ele define quais tarefas existem, em que ordem elas devem rodar e quando o fluxo será executado.
Em outras palavras, o DAG descreve a lógica de orquestração. Por isso, ele deve deixar claro o caminho dos dados, as dependências entre etapas e o objetivo do pipeline.
Tarefas
As tarefas são as unidades de trabalho dentro do DAG. Uma tarefa pode extrair dados de uma API, transformar um arquivo CSV, carregar uma tabela no warehouse ou validar uma etapa do processo.
Além disso, a TaskFlow API simplifica a criação de pipelines em Python, especialmente quando você quer organizar funções de extract, transform e load com dependências mais legíveis.
Agendamento
O agendamento define quando o DAG deve executar. Você pode começar manualmente e, depois, configurar um @daily, um cron específico ou uma estratégia mais avançada com Timetables.
No entanto, agendar não é apenas escolher horário. Também é preciso entender qual intervalo de dados cada execução representa, para evitar duplicidade, lacunas ou reprocessamentos incorretos.
Retries e alertas
Retries ajudam a lidar com falhas intermitentes, como uma API fora do ar por alguns minutos ou uma instabilidade temporária no banco.
Além disso, callbacks e alertas permitem acionar ações quando uma tarefa falha, termina ou muda de estado. A documentação de Callbacks explica esse padrão para monitoramento e resposta operacional.
O que você vai “construir” em 45 minutos
Neste primeiro projeto, o objetivo não é criar uma arquitetura complexa. Pelo contrário, a ideia é montar um pipeline pequeno, claro e fácil de evoluir.
Você vai estruturar um fluxo com:
- ingestão de um conjunto pequeno, como CSV ou API;
- transformação simples, com limpeza, enriquecimento e validações;
- carga em um destino acessível, como SQLite ou Postgres;
- previsibilidade com retries, alertas e tags;
- organização de pastas e nomes que possam escalar no time.
Assim, mesmo um exercício inicial já nasce com práticas próximas do trabalho real em dados.
Estrutura de pastas que escala
Uma boa organização evita que o projeto vire uma pasta cheia de arquivos soltos. Por isso, comece separando orquestração, lógica, artefatos e testes.
Use uma estrutura simples:
dags/: arquivos dos fluxos, preferencialmente um arquivo por pipeline;include/: SQLs, configurações auxiliares e artefatos versionados;plugins/: operators, hooks e sensors customizados, quando forem necessários;tests/: testes de parsing do DAG e funções puras de transformação.
Na prática, essa divisão ajuda a manter o DAG mais legível. Além disso, ela reduz conflitos entre pessoas do time, facilita revisão de código e separa melhor a lógica reutilizável da camada de orquestração.
Padrões operacionais que evitam dor de cabeça
Depois da estrutura básica, o próximo passo é adotar padrões pequenos, mas consistentes.
Nomeação consistente
Use nomes previsíveis para DAGs e tarefas. Por exemplo, um DAG pode seguir o padrão dominio_fonte_periodicidade, como marketing_ads_daily.
Já as tarefas podem usar {etapa}_{tecnologia}, como extract_api, transform_pandas ou load_postgres. Dessa forma, qualquer pessoa do time entende rapidamente o que o pipeline faz.
Variables e Connections
Evite credenciais em código. Em vez disso, use Connections para armazenar informações de acesso a serviços externos e Variables para parâmetros de configuração.
Além disso, mantenha nomes claros para conexões e variáveis. Isso facilita manutenção, auditoria e migração entre ambientes.
Observabilidade
A observabilidade é uma das maiores vantagens do Airflow em relação a scripts isolados. Use a UI para acompanhar execuções, logs, duração das tarefas e histórico de falhas.
A documentação de Logging & Monitoring reforça a importância de logs e métricas para diagnosticar problemas em pipelines. Portanto, descreva o DAG, use tags e registre informações úteis nas tarefas.
Resiliência prática
Configure retries, retry_delay e, quando fizer sentido, exponential backoff. Assim, falhas transitórias não derrubam o pipeline imediatamente.
No entanto, retries não devem esconder problemas recorrentes. Se uma tarefa falha todos os dias e só passa na terceira tentativa, o time precisa investigar a causa.
Passo a passo (alto nível) para seu primeiro pipeline
1. Prepare o ambiente local
Para começar, suba o ambiente local seguindo a documentação oficial. Um caminho prático é usar o guia Running Airflow in Docker, indicado para testes e desenvolvimento local.
Depois disso, acesse a UI e confirme se o webserver, o scheduler e o banco de metadados estão funcionando.
2. Modele o fluxo do DAG
Em seguida, liste as etapas do seu ELT: extrair, transformar e carregar.
Nesse momento, pense também nas dependências. A transformação depende da ingestão? A carga só pode ocorrer depois de uma validação? O pipeline será diário ou manual?
Com essas respostas, fica mais fácil desenhar um DAG simples e evitar dependências confusas.
3. Defina tarefas com foco em legibilidade
Cada tarefa deve ter uma responsabilidade única e uma saída clara. Por exemplo, uma tarefa extrai dados, outra limpa campos e outra carrega a tabela final.
Além disso, prefira funções pequenas e reutilizáveis. Com a TaskFlow API, você consegue deixar o código mais próximo de um pipeline Python legível, sem excesso de “cola” entre etapas.
4. Configure agendamento e tags
No início, rode o DAG manualmente. Depois que o fluxo estiver validado, configure @daily, um cron específico ou outro padrão de agendamento.
Além disso, use tags para facilitar filtros na UI, como dominio:marketing, camada:bronze ou tipo:elt.
Dessa forma, quando o número de DAGs crescer, o time conseguirá encontrar fluxos por domínio, responsabilidade ou camada.
5. Garanta previsibilidade
Depois da primeira execução, configure retries, alertas e logs úteis.
Para tarefas críticas, avalie também SLA ou outro indicador operacional que ajude o time a entender quando uma entrega está atrasada.
Assim, o pipeline deixa de ser apenas “um script que roda” e passa a ser um processo monitorável.
6. Teste e reprocesse com segurança
Antes de confiar no pipeline, valide com dados pequenos. Em seguida, rode tarefas específicas e confira entradas, saídas e logs.
Quando precisar regularizar histórico, use Backfill com cuidado. Esse recurso permite criar execuções para datas passadas, mas deve ser usado com atenção para não duplicar dados ou sobrecarregar sistemas.
Organização para escalar em time
Quando mais pessoas começam a criar DAGs, padrões deixam de ser detalhe e viram requisito de colaboração.
Separe orquestração e lógica
Mantenha o DAG “magro”, apenas orquestrando etapas. Já a lógica de transformação pode ficar em módulos reutilizáveis.
Como resultado, o código fica mais fácil de testar, revisar e reaproveitar em outros pipelines.
Crie padrões de revisão
Antes do merge, revise owners, nomenclatura, retries, alertas, Variables, Connections e impacto em dados downstream.
Além disso, inclua um checklist simples no PR. Isso reduz decisões implícitas e ajuda pessoas novas a seguirem o padrão do time.
Documente no próprio DAG
Use a descrição do DAG para explicar input, output, riscos, frequência e procedimento de reprocessamento.
Dessa forma, a UI passa a ser também um ponto de consulta operacional, não apenas uma tela para ver status de execução.
Próximos passos: sensores e integrações analíticas
Depois do primeiro DAG, o próximo passo é tornar o pipeline mais orientado a eventos e mais conectado à stack analítica.
Sensores
Sensores são tarefas que esperam um evento acontecer. Por exemplo, eles podem aguardar a chegada de um arquivo, a disponibilidade de uma partição ou a conclusão de uma etapa externa.
No entanto, sensores precisam ser usados com atenção. Dependendo da configuração, eles podem ocupar recursos enquanto esperam. Por isso, avalie modos de execução, timeout e alternativas como operadores deferrable quando o volume crescer.
Integrações analíticas
Além disso, conecte o Airflow ao seu warehouse, como BigQuery, Snowflake, Redshift ou Postgres.
Também é comum acionar ferramentas de modelagem, como dbt, dentro do DAG. Nesse cenário, o Airflow orquestra o fluxo, enquanto o dbt cuida das transformações analíticas versionadas.
Conclusão — de zero ao primeiro DAG (com confiança)
Agora você tem um caminho prático para sair do improviso e entrar na orquestração previsível.
Ao longo do guia, você viu o papel de DAGs, tarefas, agendamento, retries, alertas, estrutura de pastas e padrões mínimos de colaboração. Além disso, entendeu por que observabilidade, documentação e reprocessamento seguro são importantes desde o primeiro pipeline.
O próximo passo é prática deliberada. Comece pequeno, monitore as execuções, ajuste o que falhar e evolua para sensores, integrações com warehouse e pipelines de BI.
Próximos 7 dias: plano de ação
- Escolha um caso real, como um relatório diário, e mapeie as etapas ELT.
- Modele o fluxo mínimo com agendamento manual e valide entradas e saídas.
- Adicione observabilidade com tags, owners, descrição no DAG e logs úteis.
- Configure retries, alertas e, quando fizer sentido, SLA.
- Ative um sensor simples para arquivo ou partição.
- Documente o procedimento de reprocessamento.
- Revise com alguém do time: nomenclatura, Variables, Connections e alertas.
Com isso, você transforma um exercício inicial em um pipeline que já nasce com critérios mínimos de operação.
Quer continuar evoluindo? Depois deste guia, mergulhe nos conteúdos práticos da Tekne sobre automação, produtividade analítica e portfólio dentro do cluster Ferramentas & Dev.
Para começar, leia também LLMs no dia a dia do analista: 4 automações rápidas.
