Idempotency and Backfill: Beginner

Running the same pipeline twice should produce the same result, not double the rows

Running the same pipeline twice should produce the same result, not double the rows

Category

Pipeline Architecture

Difficulty

beginner

Duration

25 minutes

Challenges

0 hands-on challenges

Topics covered: The Retry That Doubled the Rows, Idempotency in One Sentence, Replace, Do Not Append, Why Retries Need Idempotency, Side by Side: Idempotent vs Not

Lesson Sections

1. The Retry That Doubled the Rows (concepts: paIdempotencyProblem)

   Pipelines fail. Networks blink, instances die, upstream APIs return 500s, the warehouse runs out of memory, a credential expires, a Spark executor gets evicted from a spot pool, an S3 bucket policy changes overnight, a DNS record propagates slowly. Failure is not the exception in production data pipelines; it is the background hum. The right response to a failed run is almost always to run it again. The wrong response is to run it again on a pipeline that does not handle being run twice. The wro

2. Idempotency in One Sentence (concepts: paIdempotency)

   Idempotency is one of those words that sounds harder than the idea it names. The mathematical definition is short: an operation is idempotent if applying it twice gives the same result as applying it once. The data engineering definition is even shorter, because the operation in question is always 'run the pipeline.' Running an idempotent pipeline twice produces the same end state as running it once. That is the entire concept. The word entered software engineering through HTTP, where GET, PUT,

3. Replace, Do Not Append (concepts: paPartitionOverwrite, paIdempotency)

   The simplest way to make a pipeline idempotent is to make it replace rather than append. Instead of writing 'add today's orders to the orders table,' the pipeline writes 'set the orders for today to exactly this set of rows.' Set is idempotent; add is not. The change is small and the implications are large, because nearly every batch pipeline can be expressed as a partition replace if the data is partitioned by run date. The mental shift is from thinking about the pipeline as something that cont

4. Why Retries Need Idempotency (concepts: paRetrySafety, paIdempotency)

   Retries are how pipelines survive the noisy reality of distributed systems. A network blip, a brief warehouse contention spike, an upstream rate limit triggered by a sudden traffic surge, a transient AZ outage, a Spark task failing because its executor lost a heartbeat. None of these are bugs; they are weather. A retry the next minute almost always succeeds. Orchestrators ship with retry support built in because retries are that fundamental to operations; turning them off would mean paging a hum

5. Side by Side: Idempotent vs Not (concepts: paIdempotentRefactor, paDeduplication)

   The clearest way to internalize the property is to read two short pipelines side by side. One is non-idempotent. The other does the same job idempotently. The diff is small. The behavioral difference under retry is enormous. The exercise below walks through both, line by line, and names what changes. Reading two side-by-side examples is faster than reading a hundred lines of explanation because the diff is the explanation. The asymmetry is the lesson: idempotency is a small change in code that p