DynamoDB Update Expressions: SET, REMOVE, ADD, DELETE
An update expression tells UpdateItem how to change one item: which
attributes to write, increment, delete, or fold into a set, named
with four clause keywords.
How do DynamoDB update expressions work?
A DynamoDB update expression tells UpdateItem how to mutate one item using four clauses. SET writes or overwrites an Attribute. ADD atomically increments a number or unions into a set. REMOVE deletes an attribute or one list element. DELETE removes specific members from a set. One call can carry all four at once.
- One item per call. You name the item by its full key; there is no
multi-row
UPDATE … SET … WHERE(the pitfalls below cover updating many). - Arithmetic happens server-side.
SET n = n + :xandADDboth change a number without reading it first, so concurrent writers can't lose an update. - It's an upsert. A key that doesn't exist yet gets created, unless a condition expression stops it.
Coming from SQL, the trap is read-modify-write: read a value, change it in code, write it back. Under concurrency that loses updates; do the change in the expression instead.
Pick the clause by what you're changing
One UpdateItem call can carry all four clauses at once, in any order. Each
keyword appears at most once and takes a comma-separated list of actions.
| Clause | Works on | Use it to |
|---|---|---|
SET | Any attribute | Write/overwrite a value or document field |
ADD | Number or Set only | Atomically increment, or union into a set |
REMOVE | Any attribute or list element | Delete an attribute; drop one list index |
DELETE | Set only | Remove specific members from a set |
ADD on a string and DELETE on a scalar are validation errors that reject the
whole call; change a scalar with SET. Per the
AWS update-expression reference,
ADD is restricted to numbers and sets, and DELETE to sets.
The worked example: a CMS article
One item per article in the CMS table from
expression names and values, keyed by
PK = "BLOG#eng" and SK = "ARTICLE#launch-notes".
It tracks a Revisions
list, a WordCount, a RevisionCount, and a Tags string set. The : names
in each expression are value placeholders, supplied in ExpressionAttributeValues.
SET: write scalars and documents
SET overwrites whatever was there. Append a revision to the list and record
the new word count in the same call:
SET WordCount = :words,
Revisions = list_append(Revisions, :rev),
UpdatedAt = :now
:rev is a one-element list holding the revision map. list_append(Revisions, :rev)
appends to the tail; list_append(:rev, Revisions) prepends. The argument
order is the concatenation order.
There's a footgun in that call: on a brand-new article, Revisions doesn't
exist yet, and list_append on a missing attribute fails with "The provided
expression refers to an attribute that does not exist in the item". Guard it
with if_not_exists:
SET Revisions = list_append(if_not_exists(Revisions, :empty), :rev)
if_not_exists(Revisions, :empty) returns the current list if present, else the
fallback :empty (an empty list []). The first revision and every later one
now use the same expression.
ADD: increment a count atomically
To bump RevisionCount, don't read it, add one in your code, and SET it back.
Two concurrent edits both read 3, both write 4, and you've dropped one.
ADD does the arithmetic server-side:
ADD RevisionCount :one
With :one = 1, this is an atomic counter. Concurrent calls serialize on the
item, so two adds land as +2. Pass a negative number to decrement. If
RevisionCount is absent, ADD treats it as 0 first, so you never need to
seed the counter.
SET RevisionCount = RevisionCount + :one is just as atomic.
AWS's guide
recommends SET over ADD in general "to ensure idempotent operations": a SET
to an absolute value can be retried safely. An increment can't, in either form.
If a timeout makes your SDK retry a call that already landed, the count goes up
twice.
When a double count matters, write the new absolute value with a condition on the one you read. Atomic counters covers that pattern and what each increment costs.
Every UpdateItem bills write units for
the larger of the item's size before and after the update, 1 per KB rounded up.
The DynamoDB expression builder builds
these with typed values and placeholders. The preset below is the launch-notes
article: a SET of WordCount plus an atomic ADD on RevisionCount. Edit it
and watch the UpdateExpression rebuild:
dynamodb-expression-builder is the open-source (MIT) library behind this tool.
REMOVE: drop an attribute or one revision
REMOVE is how you delete an attribute entirely. There's no "set it to null":
that just writes a NULL value. Clear the featured-until date and drop the
third revision in one call:
REMOVE FeaturedUntil, Revisions[2]
Revisions[2] removes the element at index 2 and shifts everything after it
down: index 3 becomes 2, and so on.
If you REMOVE two indices in one
expression, both are evaluated against the original list, so removing [2]
and [3] together drops the third and fourth elements as you'd expect.
DELETE: remove set members
Tags is a string set, so retiring one tag uses DELETE, not REMOVE.
REMOVE Tags would drop the whole set; DELETE subtracts the named members:
DELETE Tags :retired
With :retired = the set {"beta"}, only that member goes.
Two rules bite here: a set can never be empty, so deleting the last member removes the Tags
attribute outright; and the value must be a set type matching the attribute,
so a bare string is a type error. To add a tag, ADD Tags :new unions it in.
Put it together
An "append a revision, adjust the word count, bump the revision count, retire a tag" update is one call across three clauses:
SET Revisions = list_append(if_not_exists(Revisions, :empty), :rev),
WordCount = if_not_exists(WordCount, :zero) + :delta
ADD RevisionCount :one
DELETE Tags :retired
It works on a brand-new article too: if_not_exists seeds the list and the word
count, ADD starts the count at 0, and DELETE on a missing set does nothing.
Without if_not_exists around WordCount, the first call fails on the missing
attribute.
WordCount = … + :delta is arithmetic inside SET, evaluated server-side
against the current value.
Each keyword appears once, so a second ADD action
joins the same clause after a comma (ADD RevisionCount :one, Tags :new). One
call can't touch the same attribute twice, though: adding Tags :new here,
next to DELETE Tags :retired, fails with "Two document paths overlap".
Pitfalls to avoid
- Reading a value, then
SET-ing it back. Read-modify-write loses updates under concurrency. Put the arithmetic in the expression (SET n = n + :xorADD), and check atomic counters before you rely on a count a retry could double. list_appendon a missing list. Wrap the target inif_not_existsor the first write fails.- Confusing
REMOVEandDELETE.REMOVEdrops the attribute;DELETEsubtracts members from a set. Mixing them deletes more than you meant. - Forgetting
UpdateItemis an upsert. If the key doesn't exist, it creates the item. Add aConditionExpression(attribute_exists(PK)) when you mean "update only". - Updating many items.
UpdateItemtakes one key.QueryorScanfor the keys and send oneUpdateItemper item, or group up to 100 actions in aTransactWriteItemswhen they must all apply or none. DynoTable's bulk edit runs Set, Remove and Add across a selection of rows.
To guard these writes, see condition expressions;
for modeling the keys they run against, see
single-table design. Build and copy any
of these in the expression builder, then
try DynoTable to edit an article item and review the per-attribute
diff before it commits as a conditional SET/REMOVE.



