Intermediate5 min read

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_NEW reads back a counter you just incremented, in the same call.
  • ALL_OLD captures 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:

  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, 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:

ReturnValuesReturnsWorks onUse when
NONEnothing (default)Put, Update, Deleteyou don't need the item back
ALL_OLDwhole item, pre-writePut, Update, Deleteauditing, "what did I just replace?"
UPDATED_OLDattributes you touched, pre-writeUpdateyou only log the fields you changed
ALL_NEWwhole item, post-writeUpdatereturning the fresh item to a caller
UPDATED_NEWattributes you touched, post-writeUpdatereading 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.

Reviewing an item's staged change in DynoTable: the old and new values before the update is committed.
Reviewing an item's staged change in DynoTable: the old and new values before the update is committed.

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_*.
  • 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 review each edit as a before/after diff before you commit it.

By Dmitriy · Updated