DynamoDB ReturnValues: Get the Old or New Item
By default a DynamoDB write returns nothing but success. ReturnValues asks
the write itself to hand back the item, as it was before or as it is after.
What does ReturnValues do in DynamoDB?
ReturnValues tells a DynamoDB write to hand back the item as part of the same call, so you skip a second GetItem and the race it creates. PutItem and DeleteItem accept NONE or ALL_OLD; UpdateItem accepts all five (NONE, ALL_OLD, UPDATED_OLD, ALL_NEW, UPDATED_NEW), returning old or new values atomically.
UPDATED_NEWreads back a counter you just incremented, in the same call.ALL_OLDcaptures the before-image for an audit log from the write itself, as it was at write time.- No read units are consumed for the returned attributes.
- When a condition fails, a second parameter,
ReturnValuesOnConditionCheckFailure, returns the current item inside the exception.
The problem: you need the value you just overwrote
Say you run a support desk and an agent changes a ticket's status from open to
pending. Your audit log needs to record what the status was before the change.
Without ReturnValues you'd:
GetItemto read the current status,UpdateItemto set the new one.
Between steps 1 and 2 another agent could change the status, and your audit log records a stale "before" value. It's also two calls for one logical operation.
ReturnValues collapses it into a single atomic UpdateItem that returns the old
status as it actually was at write time.
The five options, and when to use each
The choice is what slice of the item and which side of the write you need:
ReturnValues | Returns | Works on | Use when |
|---|---|---|---|
NONE | nothing (default) | Put, Update, Delete | you don't need the item back |
ALL_OLD | whole item, pre-write | Put, Update, Delete | auditing, "what did I just replace?" |
UPDATED_OLD | attributes you touched, pre-write | Update | you only log the fields you changed |
ALL_NEW | whole item, post-write | Update | returning the fresh item to a caller |
UPDATED_NEW | attributes you touched, post-write | Update | reading back a counter you just incremented |
"Touched" means every attribute named in the update expression, even one whose
value didn't change. A SET status = :s to the value it already had still
returns status.
For the support-ticket audit, ALL_OLD (or UPDATED_OLD if
you only log the status field) captures the pre-change state atomically.
Note the asymmetry: PutItem and DeleteItem only support NONE and
ALL_OLD. There's no "new" value to return for a delete, and a put's new value
is what you sent. AWS documents
the exact matrix.
Read back a counter with UPDATED_NEW
Increment a version attribute with an
update expression and read the new value in
the same call:
UpdateItem PK=TICKET#8842
UpdateExpression: ADD version :one
ExpressionAttributeValues: {":one": {"N": "1"}}
ReturnValues: UPDATED_NEW
→ Attributes.version.N == "41" (was 40)You receive only the attributes you touched, not the full item, which suits a
large item whose caller needs one number. More on counters, and why a retried
ADD counts twice: atomic counters.
Get the item when a condition fails
ReturnValues and condition expressions
compose on the same call. Increment retryCount only while below a cap, and
return the new count. The attribute_not_exists half lets the first call through,
since a comparison against a missing attribute is false:
UpdateItem PK=JOB#1
ConditionExpression: attribute_not_exists(retryCount) OR retryCount < :max
UpdateExpression: ADD retryCount :one
ExpressionAttributeValues: {":one": {"N": "1"}, ":max": {"N": "3"}}
ReturnValues: UPDATED_NEW
ReturnValuesOnConditionCheckFailure: ALL_OLD
→ 1st call: Attributes.retryCount.N == "1"
→ 3rd call: Attributes.retryCount.N == "3"
→ 4th call: ConditionalCheckFailedException with Item.retryCount.N == "3"ReturnValues only fills a successful response. When the condition fails you
get a ConditionalCheckFailedException.
With ReturnValuesOnConditionCheckFailure: ALL_OLD, the exception carries the
item as it is now (in the JavaScript SDK v3, on err.Item). It accepts only ALL_OLD
or NONE, and costs no read units.
Use it for optimistic-locking retries: you get the current version without a
GetItem, recompute, and resend. Don't echo it back to an untrusted client; the
uniqueness guide covers that case.
Deletes and puts
DeleteItem with ReturnValues: ALL_OLD is how you implement "pop and return"
semantics on a queue item: the deleted item comes back in Attributes. There is
no ALL_NEW on delete because the item no longer exists.
PutItem with ALL_OLD returns the previous item when you overwrite an existing
key, which is useful for swap workflows. When the key did not exist, the
response omits Attributes.
Capacity note
Returned attributes are free: AWS says "No read capacity units are consumed." The write bills as usual, on the larger of the item's size before and after the update, in 1 KB units, however many attributes come back.
If you were tempted to GetItem then UpdateItem to log the old value, you
paid for a read plus a write. On a 2 KB item at 500 updates per second, the
strongly consistent read you drop is 1 RCU each: 500 RCU per second.
An eventually consistent read would cost half (250 RCU per second), but it can return a stale "before" value, the very problem you started with.
See the before and after in DynoTable
Assemble the UpdateItem and its update expression in the
DynamoDB Expression Builder. It emits the
SET/ADD clause plus the attribute-name and value maps.
In DynoTable, stage an attribute change in the item editor and open the Side-by-side diff in Pending changes: old and new values next to each other before you commit.
The old side is the item as DynoTable loaded it, and the commit is conditional, so it conflicts if someone changed the item in between. After the commit, Copy as JSON from the grid for test fixtures.

Pitfalls + next steps
- Don't
GetItem-then-write to read around a change. It's a round trip and a race; useReturnValues. UPDATED_*returns only touched attributes. If you need the whole item, useALL_*.ReturnValuesis not a substitute for a condition. To guard a write, add a condition expression; to read back its effect, useReturnValues. They compose.- Related: update expressions, atomic counters.
Want to make edits and see the before/after without scripting two calls? Download DynoTable and review each edit as a before/after diff before you commit it.


