DynamoDB Atomic Counters: How ADD Works, and When It Doesn't
An atomic counter is a numeric attribute you bump in place with one UpdateItem
call, with no read first.
What is a DynamoDB atomic counter?
A DynamoDB atomic counter is a numeric attribute you increment in place with a single UpdateItem call using an ADD (or SET x = x + :n) update expression. DynamoDB reads, adds, and writes the value server-side, so concurrent writers serialize without lost updates. It is not idempotent: a retried call increments twice.
- Retries count twice. A network blip plus a retry can double-count. For exact counters under contention, use a token-based transaction or a marker item.
ADDon a missing attribute starts at 0, so the first increment needs no seed write.SET x = x + :nerrors on a missing attribute unless you wrap it inif_not_exists.- Every increment is a full write, billed on the item's size, so a big item makes every bump expensive.
- One counter item is one hot key. Past roughly 1,000 writes per second, shard it.
The problem with read-modify-write
Say you track views on a video. The naive instinct, straight from SQL, is:
GetItem, add one in your app, PutItem the new total back.
Two viewers hit play at once. Both read views = 41. Both write 42. You
counted one view, not two. That's a lost update, and it doesn't show up until
you have traffic.
In SQL you'd dodge it with UPDATE videos SET views = views + 1, pushing the
arithmetic into the database. DynamoDB has the same move, and it's the whole
point of an atomic counter.
Increment in one call
Model a per-video stats item. Partition key VID#<id>, sort key STATS#TOTAL,
with a numeric play_count:
| PK | SK | play_count |
|---|---|---|
| "VID#9f3a" | "STATS#TOTAL" | 41 |
To register a play, send one UpdateItem with an ADD clause:
# UpdateItem
Key PK = "VID#9f3a", SK = "STATS#TOTAL"
UpdateExpression ADD play_count :one
Values :one = 1
DynamoDB reads play_count, adds 1, and writes the result inside a single
server-side operation. There's no window for another writer to slip in. Ten
concurrent plays produce +10, every time. That's what "atomic" buys you.
You can build and copy this exact expression (names, values, and all four clause types) with the DynamoDB Expression Builder.
ADD works even when play_count doesn't exist yet: DynamoDB treats a missing
numeric attribute as 0, so the first play creates it at 1. No separate seed
write. (AWS: Using update expressions)
ADD vs SET +: pick one
Two expressions do the same arithmetic. AWS's update-expression guide says: "In
general, we recommend using SET rather than ADD to ensure idempotent
operations." (AWS: Using update expressions)
That holds for SET to an absolute value, the conditional pattern
below. SET play_count = play_count + :one repeats on a
retry exactly like ADD does.
ADD play_count :one | SET play_count = play_count + :one | |
|---|---|---|
| Missing attr | Creates it, starting at 0 | Errors, needs if_not_exists |
| Data types | Numbers and sets only | Numbers (and more) via SET |
Combine w/ SET | Separate clause | One SET clause, comma-separated |
| Safe to retry | No | No |
If the attribute might not exist and you want SET, guard it:
SET play_count = if_not_exists(play_count, :zero) + :one. With ADD you skip
that, since it seeds from 0.
Write cost of each increment
Each UpdateItem bills 1 write unit per started KB of the item, measured at
the larger of its size before and after the write: a WCU on provisioned
capacity, a write request unit on on-demand.
A 900-byte stats row costs 1 write unit per play, so ten concurrent plays cost 10, not one. Keep counters on small items. Size the row with the item-size calculator and estimate the sustained write cost in the pricing calculator.
The trap: counters aren't idempotent
An atomic counter increments every time UpdateItem runs. (AWS: Working
with items)
Picture a network blip: you send the increment, the connection drops before the response comes back, and you don't know whether it landed. You retry. If the first call did succeed, you've now counted that play twice.
For video views that's fine. A few double-counts in a million plays won't hurt anyone, and tracking website visitors is AWS's own example of an atomic counter. (AWS: Working with items)
It is not fine for anything that must be exact: inventory you can oversell, credits you can double-spend, a balance you can corrupt.
When you need exactness
Two patterns make a retry safe. The token transaction stays exact while other writers hit the same counter. The conditional write needs no transaction, but after a lost response under contention it can't tell you whether to retry.
1. A transaction with a ClientRequestToken. Put the same ADD inside
TransactWriteItems and pass a token derived from the event (the play id).
DynamoDB treats a repeat with the same token within 10 minutes as the same call:
# TransactWriteItems
ClientRequestToken play-7f2c91
Update Key PK = "VID#9f3a", SK = "STATS#TOTAL"
UpdateExpression ADD play_count :one
Values :one = 1
It costs 2 write units per item instead of 1, and no read. The retry is a no-op even when another play landed in between: 41, your play, another play, then your retry with the same token leaves 43.
For dedup beyond 10 minutes, add a Put of a PLAY#<id> marker item guarded by
attribute_not_exists(PK) to the same transaction; a repeat then cancels, and
you treat that cancellation as "already counted".
The marker is a second transactional write, so each play costs 4 write units, and markers pile up. Give each one a TTL attribute set past your longest retry window.
2. A conditional SET to an absolute value. Read the current value, then
write the new one only if nothing moved:
# UpdateItem
Key PK = "VID#9f3a", SK = "STATS#TOTAL"
UpdateExpression SET play_count = :next, last_req = :req
ConditionExpression play_count = :current
Values :next = 42, :current = 41, :req = "play-7f2c91"
A retry of a write that already landed fails the condition and changes nothing
(AWS: Working with items). The catch: a
ConditionalCheckFailedException can also mean another writer moved the value.
Pass ReturnValuesOnConditionCheckFailure: ALL_OLD and the exception carries
the current item. If last_req is your request id, your write landed and you're
done.
If last_req holds another id, you can't tell. Your write may have landed just
before that writer's, so recomputing and retrying can count your play twice: 41,
your lost write to 42, another play to 43, your recomputed retry to 44.
So the conditional write is exact only when nothing else writes the item between
your attempt and your retry. For a contended counter that must be exact, use the
token (or the marker past 10 minutes). For view counts, plain ADD is enough.
Pitfalls
- One hot item. A single counter item is one partition key,
and DynamoDB serves at most 1,000 write units per second for it. Shard the
partition key: write to
PK = "VID#9f3a#<n>"with a randomnfrom 0 to N−1, then read all N items with oneBatchGetItemand sum, retrying anyUnprocessedKeysso a throttled shard isn't silently left out. A shard nobody has written yet is absent from the response; count it as 0. Sharding in depth: hot partitions. - No batch increment in
BatchWriteItem, which is put/delete only.BatchExecuteStatementruns up to 25 PartiQLUPDATE "t" SET n = n + 1 WHERE PK = '…' AND SK = '…'statements per call, each atomic but not the batch. When several counters must move together,TransactWriteItemstakes up to 100 Update actions at double the write cost. ADDis numbers and sets only. It won't touch strings or booleans; that's aSET. See DynamoDB data types for the full attribute model.
Do it in DynoTable
DynoTable does not send blind increments. Bulk edit's Add reads each item, writes the new total, and commits it under a condition that the value hasn't changed.
That is the conditional pattern above, applied to many rows or every item a query matches: a concurrent change makes the item conflict or skip instead of taking a stale total. Running the same Add twice still adds twice.
Open a stats item in the item editor to check the current value. For a sharded
counter, the SQL Workbench can SUM(play_count) across the shard items. Draft
the raw ADD request for your own code in the
DynamoDB Expression Builder.
Next steps
Atomic counters are a write pattern; how you read aggregates back is a modeling
question. See single-table design for keeping
stats items beside their parent, and Query vs Scan
for keeping the rollup off a Scan.
Draft and copy the increment in the DynamoDB Expression Builder, then try DynoTable to inspect your counters and apply guarded bulk updates against your own tables.