Intermediate6 min read

DynamoDB Update Expressions: SET, REMOVE, ADD, DELETE

An update expression tells UpdateItem how to change one item: which 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 . 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 + :x and ADD both 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.

ClauseWorks onUse it to
SETAny attributeWrite/overwrite a value or document field
ADDNumber or Set onlyAtomically increment, or union into a set
REMOVEAny attribute or list elementDelete an attribute; drop one list index
DELETESet onlyRemove 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:

Build your request
Generated code
new UpdateItemCommand({
  "TableName": "Articles",
  "Key": {
    "PK": {
      "S": "BLOG#eng"
    },
    "SK": {
      "S": "ARTICLE#launch-notes"
    }
  },
  "UpdateExpression": "SET #upd0 = :updValue0 ADD #upd1 :updValue1",
  "ExpressionAttributeNames": {
    "#upd0": "WordCount",
    "#upd1": "RevisionCount"
  },
  "ExpressionAttributeValues": {
    ":updValue0": {
      "N": "1840"
    },
    ":updValue1": {
      "N": "1"
    }
  }
})

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 + :x or ADD), and check atomic counters before you rely on a count a retry could double.
  • list_append on a missing list. Wrap the target in if_not_exists or the first write fails.
  • Confusing REMOVE and DELETE. REMOVE drops the attribute; DELETE subtracts members from a set. Mixing them deletes more than you meant.
  • Forgetting UpdateItem is an upsert. If the key doesn't exist, it creates the item. Add a ConditionExpression (attribute_exists(PK)) when you mean "update only".
  • Updating many items. UpdateItem takes one key. Query or Scan for the keys and send one UpdateItem per item, or group up to 100 actions in a TransactWriteItems when 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.

A staged edit to the launch-notes article in DynoTable: the per-attribute diff for WordCount and RevisionCount before commit.
A staged edit to the launch-notes article in DynoTable: the per-attribute diff for WordCount and RevisionCount before commit.

By Dmitriy · Updated