DynamoDB Update Expressions
An update expression tells DynamoDB exactly how to change an existing item. Your application sends a short instruction, and DynamoDB applies the change on the server in one atomic step. The application never has to read the item, edit it locally, and write the whole item back.
Why Update Expressions Matter
Picture the scoreboard at a cricket ground. When a batter hits a four, a helper walks up and adds 4 to the displayed total. The helper never erases the board and rewrites every number. Update expressions work the same way. You describe the change (add 4), and DynamoDB handles the rest.
Three benefits come with this approach:
- Network traffic drops because you send only the change, not the whole item.
- Two users who update the same item at the same moment never overwrite each other.
- Read capacity stays untouched because the update needs no read first.
The UpdateItem Operation
UpdateItem is the API call that carries an update expression. The call needs the table name, the primary key of the target item, and the expression itself. When the item does not exist, DynamoDB creates it. Developers call this behavior an upsert (update plus insert).
UpdateItem on table Products
Key: { "ProductID": { "S": "P100" } }
UpdateExpression: "SET Price = :newPrice"
ExpressionAttributeValues: { ":newPrice": { "N": "499" } }
You cannot change the primary key attributes with UpdateItem. To change a key, delete the item and write a new one.
The Four Clauses
An update expression contains one or more clauses. Each clause appears at most once in a single expression.
| Clause | Purpose | Sample |
|---|---|---|
| SET | Adds or replaces an attribute value | SET Price = :p |
| REMOVE | Deletes an attribute from the item | REMOVE Discount |
| ADD | Adds a number or adds elements to a set | ADD Views :one |
| DELETE | Removes elements from a set | DELETE Colors :c |
SET Clause
SET handles most updates. It supports arithmetic, so you can raise or lower a number directly.
SET Stock = Stock - :qty SET Views = Views + :one
Two helper functions make SET more powerful. The function if_not_exists writes a default value only when the attribute is missing. The function list_append adds new elements to the end of a list.
SET Views = if_not_exists(Views, :zero) + :one SET Tags = list_append(Tags, :newTags)
REMOVE Clause
REMOVE deletes one or more attributes. It also deletes a list element by position.
REMOVE Discount, Tags[0]
ADD and DELETE Clauses
ADD increases a number or inserts values into a set. DELETE takes values out of a set. SET handles number arithmetic well, so ADD matters most for set operations.
Placeholders for Names and Values
DynamoDB expressions use placeholders instead of raw values. A placeholder that starts with a colon, such as :qty, stands for a value. A placeholder that starts with a hash, such as #n, stands for an attribute name.
Name placeholders solve a specific problem. DynamoDB reserves hundreds of words, including Name, Status, and Size. An attribute with a reserved name needs a placeholder.
UpdateExpression: "SET #s = :newStatus"
ExpressionAttributeNames: { "#s": "Status" }
ExpressionAttributeValues: { ":newStatus": { "S": "SHIPPED" } }
Combining Clauses in One Request
A single request can carry several changes. Separate actions inside a clause with commas, and separate clauses with spaces.
SET Price = :p, Stock = Stock - :qty REMOVE OldTag
DynamoDB applies every action in the request together. Either all of them succeed or none of them do.
Diagram: Atomic Counter vs Read-Modify-Write
WITH UPDATE EXPRESSION (safe) Views = 100 User A sends: SET Views = Views + 1 → DynamoDB applies → 101 User B sends: SET Views = Views + 1 → DynamoDB applies → 102 Final value: 102 ✓ WITHOUT UPDATE EXPRESSION (unsafe) User A reads Views = 100 User B reads Views = 100 User A writes 101 User B writes 101 Final value: 101 ✗ (one update lost)
Choosing What DynamoDB Returns
The ReturnValues setting controls the response from UpdateItem.
| Setting | Result |
|---|---|
| NONE | Returns nothing (default) |
| ALL_OLD | Returns the whole item before the update |
| ALL_NEW | Returns the whole item after the update |
| UPDATED_OLD | Returns only the changed attributes, old values |
| UPDATED_NEW | Returns only the changed attributes, new values |
Protecting Updates with Conditions
A ConditionExpression adds a safety check to the update. DynamoDB applies the change only when the condition is true. A stock counter benefits from this guard.
UpdateExpression: "SET Stock = Stock - :qty" ConditionExpression: "Stock >= :qty"
An order for 5 units fails when only 3 units remain. The stock never drops below zero.
Common Mistakes
- Using the same clause twice in one expression causes an error.
- Touching the same attribute in two different actions causes an error.
- Forgetting a name placeholder for a reserved word causes a validation error.
- Applying SET arithmetic to an attribute that does not exist fails unless you wrap it in
if_not_exists.
Summary
- An update expression changes an item on the server without a read first.
- SET, REMOVE, ADD, and DELETE cover every kind of change.
- Placeholders starting with a colon hold values, and placeholders starting with a hash hold names.
- Update expressions create safe counters because DynamoDB applies each change atomically.
- A ConditionExpression guards the update against invalid states.