Skip to content
codeyourself.
All field guides

A streaming checkpoint is progress, not your whole recovery plan.

Reason about restarts, replay and side effects before claiming reliable streaming.

WHAT YOU’LL TAKE AWAY

Track what was read and what was committed.

Treat external side effects as a separate correctness boundary.

Test restart behavior with a realistic failure scenario.

Begin at the failure boundary

A stream is not reliable merely because it keeps running. You need to know which source records have been read, which results were committed and what happens if processing stops between those two events. Checkpointing helps a streaming engine retain progress and state across restarts, but it is not a universal backup for every external action your code performs.

Imagine a pipeline reading purchase events, calculating a summary and notifying another service. A crash can happen before reading, during transformation, after writing a result or after sending a notification. Each location has a different replay consequence. Draw those boundaries before choosing a recovery test.

Distinguish engine state from side effects

In Structured Streaming, a checkpoint location stores information used for recovery. Its contents and compatibility rules belong to the engine's documented contract. Do not casually delete or reuse a checkpoint as a troubleshooting shortcut: doing so can change replay behavior or conflict with the query's state and source history.

External effects need a separate argument. If a batch writes to a destination with weaker retry semantics, the job can repeat a write after an ambiguous failure. An HTTP call is an especially clear example: the destination may have applied it even when the client never saw the response. A restart cannot infer the outcome from the missing response alone.

Design replay-safe operations

Use stable event or business identifiers. Where the destination supports it, record a processed identifier transactionally with the effect, or use a correctly scoped idempotency key. The same key should represent the same intended operation; a fresh random key on every retry defeats deduplication.

Do not assume a batch ID is globally unique across all jobs and all checkpoint histories. Scope any deduplication scheme to the actual pipeline and its lifecycle. Decide how long identifiers remain valid and how a rebuild or replay is distinguished from a duplicate.

Create a small recovery experiment

Start with a finite, known event sequence. For example, use event IDs 101 through 110 with known totals. Run the pipeline, stop it after a controlled processing boundary, and restart using the intended checkpoint. Compare final rows, duplicate effects and aggregate totals to your expected result. Test both a clean restart and a failure where the destination committed but the caller did not receive confirmation.

Record the source, checkpoint location, query version, sink behavior and failure point. Without these details, a successful restart demonstration may prove only that a process can start again. It does not establish that business outcomes are correct.

Keep capacity and correctness separate

A browser lakehouse flow model can show a queue growing when ingestion outruns processing and draining when spare capacity returns. It does not create Spark tasks, maintain a real checkpoint or implement Delta transaction semantics. Use it to practice capacity reasoning, then validate correctness and performance in an appropriately configured real environment before making production guarantees.

A good review ends with three answers: what progress is durable, which operations can repeat, and how the destination makes repetition safe. Those answers are more useful than an unqualified “exactly-once” label.

PAUSE. THINK. EXPLAIN.

Check your understanding

A job sends an external HTTP request and crashes before recording completion. What can go wrong when it resumes?

Reveal the reasoning

The request may be sent again even if the first one succeeded. Give the destination a stable idempotency key and reconcile ambiguous outcomes; a stream checkpoint alone does not make an arbitrary external API exactly-once.

Sources & further reading

Created with AI assistance. Examples are educational; verify platform-specific behavior against the linked documentation. Found something unclear? Contact us.

FROM UNDERSTANDING TO DOING

Make the next step a small one.

Create a Free account for six coding challenges and five starter labs. Advanced labs and Architecture Studio are Pro features.

Start free practice
Save your own workPractice with browser fixturesClear Free & Pro accessSQL practice uses local DuckDB fixtures. System-design simulations model assumptions; they do not provision real cloud services.