Intermediate7 min read

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.
  • ADD on a missing attribute starts at 0, so the first increment needs no seed write. SET x = x + :n errors on a missing attribute unless you wrap it in if_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:

PKSKplay_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 :oneSET play_count = play_count + :one
Missing attrCreates it, starting at 0Errors, needs if_not_exists
Data typesNumbers and sets onlyNumbers (and more) via SET
Combine w/ SETSeparate clauseOne SET clause, comma-separated
Safe to retryNoNo

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 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 . 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 random n from 0 to N−1, then read all N items with one BatchGetItem and sum, retrying any UnprocessedKeys so 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. BatchExecuteStatement runs up to 25 PartiQL UPDATE "t" SET n = n + 1 WHERE PK = '…' AND SK = '…' statements per call, each atomic but not the batch. When several counters must move together, TransactWriteItems takes up to 100 Update actions at double the write cost.
  • ADD is numbers and sets only. It won't touch strings or booleans; that's a SET. 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.

By Dmitriy · Updated