DynamoDB ReturnValues: Get the Old or New Item

By default a DynamoDB write returns nothing but success. But you often need the data around the write — the value before you changed it, or the fresh value after. The naive fix is a second GetItem, which is an extra round trip and a race: someone else can write in between. DynamoDB avoids both with the ReturnValues parameter, which hands back the old or new item atomically as part of the write itself.

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.

• ReturnValues returns the item as part of the write — no second read, no race.
• NONE (default) — return nothing.
• ALL_OLD — the entire item as it was before the write.
• UPDATED_OLD — only the attributes the update changed, before values.
• ALL_NEW — the entire item after the write.
• UPDATED_NEW — only the changed attributes, after values.
• PutItem/DeleteItem accept only NONE or ALL_OLD; UpdateItem accepts all five.

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:

1. GetItem to read the current status,
2. UpdateItem to set the new one.

Between steps 1 and 2 another agent could change the status — now your audit log records a stale "before" value. Worse, it's 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

UpdateItem supports the full set; the choice is what slice of the item and which side of the write you need:

UPDATED_NEW is the everyday hero: increment a counter with an update expression and read the new total back in the same call, no race. 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 just what you sent. Only UpdateItem, which mutates in place, offers all five. AWS documents the exact matrix.

Writing the update in DynoTable

Assemble the UpdateItem and its update expression visually with the DynamoDB expression builder — it emits the SET/ADD clause plus the attribute-name and value maps. In the app, DynoTable shows the resulting item after a staged write is committed, so you see the new state directly.

Pitfalls + next steps

• Don't GetItem-then-write to read around a change — it's a round trip and a race; use ReturnValues.
• UPDATED_* returns only touched attributes — if you need the whole item, use ALL_*.
• PutItem/DeleteItem can't return new values — only NONE/ALL_OLD.
• ReturnValues is not a substitute for a condition — to guard a write, add a condition expression; to read back its effect, use ReturnValues. They compose.
• Related: update expressions, atomic counters.

Want to make edits and see the before/after without scripting two calls? Download DynoTable and edit your items directly.

Atomic counter with UPDATED_NEW

Inventory systems increment a version or stock field on every write. The pattern is one UpdateItem with ADD stock :inc and ReturnValues: UPDATED_NEW:

UpdateItem  PK=SKU#8842
  UpdateExpression: ADD stock :one
  ExpressionAttributeValues: {":one": {"N": "1"}}
  ReturnValues: UPDATED_NEW
→ Attributes.stock.N == "41"   (was 40)

You receive only the changed attribute map, not the full item — ideal when the item is large but the caller needs the new counter. For audit trails that must capture every field before change, switch to ALL_OLD.

The write still bills as an UpdateItem on the item's size; ReturnValues does not add a separate read charge — DynamoDB already loaded the item to apply the update.

Capacity note

Returning attributes does not double the WCU cost of the write itself. You pay for the write based on the item size before and after the update per AWS rules, independent of how many attributes appear in the response payload.

If you were tempted to GetItem then UpdateItem to log the old value, you paid for a read plus a write. ReturnValues: ALL_OLD on the update removes the read entirely — on a 2 KB item at 500 updates per second that saves roughly 250 eventually-consistent RCU per second.

Compose with condition expressions

ReturnValues and condition expressions compose on the same call. Example: increment retryCount only while below a cap, and return the new count:

ConditionExpression: retryCount < :max
UpdateExpression: ADD retryCount :one
ReturnValues: UPDATED_NEW

If the condition fails, DynamoDB returns ConditionalCheckFailedException and no attribute payload — distinct from a successful update with an empty UPDATED_NEW when nothing changed.

Use the expression builder to generate the UpdateExpression, condition, and marshalled value maps together.

Decision guide

Deletes and puts

DeleteItem with ReturnValues: ALL_OLD is how you implement "pop and return" semantics on a queue item — the deleted row 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 — useful for swap workflows. When the key did not exist, the response omits Attributes.

Verify in DynoTable

Stage an attribute change in the item editor: the review pane shows old and new values side by side before commit — the same information UPDATED_OLD and UPDATED_NEW would return, without writing a script. After commit, copy the row as JSON for test fixtures via the grid's export actions.