← Notas

Nota técnica

Como tornei o pipeline idempotente

Reexecução sem duplicar pedido: estado, chave de negócio e Silver que não cresce duas vezes.

  • Python
  • Pandas
  • Parquet
6 min de leitura

  1. 01 — Problema

    Segunda execução do mesmo lote duplicava linhas no fato e inflava métricas de volume e perda.

  2. 02 — Hipótese

    Se a chave de negócio do pedido for o contrato de unicidade em Silver, reprocessar Bronze não cria pedido novo.

  3. 03 — Implementação

    Deduplicação em Silver por order_id (último evento vence) e fato Gold com grão explícito de um pedido.

  4. 04 — Resultado

    Replay de Bronze reconstrói Gold sem duplicar o grão, no pipeline local do Delivery Audit.

  5. 05 — Aprendizado

    Idempotência é propriedade do grão e da chave, não do orquestrador. Airflow só dispara de novo; o pipeline tem que saber dizer não.

Retries de orquestração expõem a falta de idempotência. O recorte abaixo está no pipeline do Delivery Audit. Um orquestrador que reexecuta um job não-idempotente apenas automatiza a duplicação.

Problema

primeira execução
       ↓
processa dados
       ↓
segunda execução (retry / backfill)
       ↓
DUPLICAÇÃO

No fato com grão “um pedido”, duas linhas para o mesmo order_id quebram taxa de cancelamento, SLA e qualquer soma de perda. O sintoma parece analytics. A causa é contrato de unicidade ausente.

Hipótese

Se Silver materializa um registro por pedido (último estado conhecido) e Gold não faz append cego, a segunda passagem sobre o mesmo Bronze é replay, não acúmulo.

Implementação

  1. Bronze permanece append-only — histórico da origem.
  2. Silver resolve conflito por order_id (último timestamp da jornada vence).
  3. Gold reconstrói fact_orders a partir de Silver, não empilha sobre a execução anterior.
  4. Flags de auditoria são recalculadas sobre o fato reconstruído.

Isso é idempotência de lote completo. Idempotência incremental (merge por partição de data) é o passo seguinte, típico de DAG Airflow com execution_date.

Resultado

primeira execução
       ↓
processa dados
       ↓
segunda execução
       ↓
detecta estado (chave já vista)
       ↓
não duplica

No pipeline local, reprocessar o mesmo extrato não duplica order_id no fato.

Aprendizado

Colocar retries=3 no operador sem chave de negócio gera incidente. A ferramenta de orquestração não define unicidade. O grão define.

O teste mínimo: executar o lote duas vezes e verificar count(distinct order_id) = count(*).