Exactly-Once Delivery Is a Spectrum, Not a Checkbox: Part 1 | by Dani Palma | Jun, 2026 | MediumSitemapOpen in appSign up<br>Sign in

Medium Logo

Get app<br>Write

Search

Sign up<br>Sign in

Exactly-Once Delivery Is a Spectrum, Not a Checkbox: Part 1

Dani Palma

10 min read·<br>Just now

Listen

Share

Press enter or click to view image in full size

“Exactly once” is one of the most overloaded phrases in data infrastructure.<br>A source can say it emits every change once.<br>Kafka can claim to support exactly-once semantics.<br>Flink can say it checkpoints state exactly once.<br>BigQuery and Snowflake can say they support exactly-once streaming writes.<br>A lakehouse table can say commits are atomic.<br>All of those statements can be true, but your dashboard can still double-count revenue.<br>The reason is simple: exactly once is not one guarantee. It is a chain of guarantees. The chain crosses the source database, the capture connector, the transport layer, the stream processor, the destination connector, the destination storage engine, and finally the business operation you care about.<br>This series of articles provides a practical model for exploring exactly-once guarantees and how much failure they tolerate.<br>We will start with the first two links in the chain: source guarantees and transport guarantees. Then we will move into stream processing, where input progress and processing state have to recover together. From there, we will get to the place where correctness becomes truly visible: materialization into a table, file, index, lakehouse, warehouse, or external API.<br>The duplicate no one owns<br>Let’s kick off with a common pipeline:<br>Postgres -> CDC connector -> Kafka -> stream job -> warehouse<br>Now imagine a customer places an order:<br>INSERT INTO orders (id, customer_id, amount, status)<br>VALUES (123, 42, 100.00, 'paid');The source database commits the transaction, then the CDC connector reads the write-ahead log, and Kafka accepts the record. On the other side, a worker reads it and writes it to a warehouse table.<br>Then this happens:<br>t1 worker reads order_id = 123<br>t2 worker writes order_id = 123 to destination<br>t3 destination commit succeeds<br>t4 worker crashes before saving its checkpoint<br>t5 worker restarts from old checkpoint<br>t6 worker reads order_id = 123 again<br>t7 worker writes order_id = 123 againDo you see the issue? No component “lost” data or necessarily violated its own contract. But, the source replayed from a safe position and the worker retried after a crash. After all that, the destination accepted a valid write.<br>But the business effect happened twice, so if the destination table is append-only, you now have this:<br>order_id | amount | source_lsn<br>- - - - -+ - - - - + - - - - - -<br>123 | 100.00 | 0/16B6C50<br>123 | 100.00 | 0/16B6C50If a dashboard runs this:<br>SELECT SUM(amount) AS revenue<br>FROM orders;the answer is obviously wrong.<br>This sneaky bug lives in the gap between delivery and effect .<br>Delivery asks: did the event arrive?<br>Effect asks: did the durable state change exactly once?<br>Those are very different questions.<br>Exactly-once is scoped<br>Every “exactly-once” claim has a scope.<br>Kafka’s idempotent producer prevents producer retries from creating duplicate log entries in a Kafka partition, and Kafka transactions can atomically send records to multiple partitions and topics. But Kafka’s own producer documentation also says application-level resends cannot be deduplicated by producer idempotence, and idempotence is guaranteed only within a producer session.<br>Postgres logical replication slots normally emit each change once, but after a crash a slot can return to an earlier LSN and resend recent changes. The Postgres documentation explicitly says logical decoding clients are responsible for avoiding bad effects from handling the same message more than once.<br>BigQuery Storage Write API supports exactly-once semantics through stream offsets, but that guarantee is scoped to messages with the same offset within a write stream when the client provides offsets. The default stream is at-least-once.<br>Snowpipe Streaming uses channels and offset tokens to support recovery without duplicate ingestion, but its docs also make clear that offset tokens are user-defined identifiers and the external system must use them to track progress correctly.<br>Those might seem like contradictions, but they are, in fact, scoped guarantees.<br>A useful pipeline model looks like this:<br>Press enter or click to view image in full size

“Exactly once” can apply at any of those boundaries, but keep in mind that it rarely applies to all of them automatically.<br>The spectrum<br>Think of delivery guarantees as a spectrum.<br>Press enter or click to view image in full size

A pipeline with at-least-once transport and a truly idempotent destination write can be more correct than a pipeline with Kafka transactions and a non-idempotent warehouse append.<br>The weakest link will define the actual guarantee.<br>Five guarantees hiding behind one phrase<br>When someone says “exactly once,” ask which of these...