Multiple operations in a single DynamoDB update expression

DynamoDB supports an UpdateItem operation that modifies an existing or creates a new item. The UpdateItem accepts an UpdateExpression that dictates which operations will occur on the specified item.

In this post, we’ll explore how to perform multiple operations including within a clause/keyword and with multiple clauses/keywords.

What is an update expression

An update expression supports four keywords:

1. SET (modify or add item attributes)
2. REMOVE (deleting attributes from an item)
3. ADD (updating numbers and sets)
4. DELETE (removing elements from a set)

The syntax for an update expression is as follows:

1update-expression ::=
2    [ SET action [, action] ... ]
3    [ REMOVE action [, action] ...]
4    [ ADD action [, action] ... ]
5    [ DELETE action [, action] ...]

As you can view, DynamoDB supports four main clauses that begin with one of the specified operations.

For a detailed explanation of update expressions, please refer to the AWS documentation.

For demonstration purposes, I’m going to create a DynamoDB table named books with a number hash key named id.

1aws dynamodb create-table \
2  --table-name books \
3  --attribute-definitions AttributeName=id,AttributeType=N \
4  --key-schema AttributeName=id,KeyType=HASH \
5  --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

I’ll also add an item to the table:

 1{
 2  "id": {
 3    "N": "1"
 4  },
 5  "title": {
 6    "S": "Iliad"
 7  },
 8  "author": {
 9    "S": "Homer"
10  },
11  "genre": {
12    "S": "Epic Poetry"
13  },
14  "publication_year": {
15    "N": "1488"
16  }
17}

1aws dynamodb put-item \
2    --table-name books \
3    --item file://book.json

How to specify a single keyword in DynamoDB update expression

Let’s showcase a basic use-case of adding an element to an existing item:

1aws dynamodb update-item \
2    --table-name books \
3    --key '{"id":{"N":"1"}}' \
4    --update-expression "SET category = :c" \
5    --expression-attribute-values '{":c":{"S":"Poem"}}'

Now the item has a new category attribute:

1aws dynamodb get-item \
2    --table-name books \
3    --key '{"id":{"N":"1"}}' \
4    --projection-expression "category"

Output:

1{
2  "Item": {
3    "category": {
4      "S": "Poem"
5    }
6  }
7}

How to specify a single keyword with multiple actions in DynamoDB update expression

To showcase mutliple SET operations in a single DynamoDB update expression, we’ll use a comma (,) to separate them.

In the following example, we’re changing the category from poem -> poetry and adding a new element named genre.

1aws dynamodb update-item \
2    --table-name books \
3    --key '{"id":{"N":"1"}}' \
4    --update-expression "SET category = :c, genre = :g" \
5    --expression-attribute-values '{":c":{"S":"poetry"}, ":g":{"S":"Epic poetry"}}' \
6    --return-values UPDATED_NEW

Output:

 1{
 2  "Attributes": {
 3    "category": {
 4      "S": "poetry"
 5    },
 6    "genre": {
 7      "S": "Epic poetry"
 8    }
 9  }
10}

As you see, the update-expression includes a comma between the two operations:

SET category = :c, genre = :g

How to specify multiple keywords with multiple actios in DynamoDB update expression

Lastly, let’s showcase leveraging multiple keywords with their respective actions.

We’re going to perform the following:

1. Set a new string attribute named product_category with a value of poem
2. Remove the category attribute
3. Add 1 to existing checkout_total number or initialize it with the number value of 1
4. Add Trojan War to existing subjects set or initialize it with the first index being string value of Trojan War

1aws dynamodb update-item \
2    --table-name books \
3    --key '{"id":{"N":"1"}}' \
4    --update-expression "SET #pc = :pc REMOVE #c ADD #ct :inc, #s :s" \
5    --expression-attribute-names '{"#s":"subjects","#pc":"product_category","#c":"category","#ct":"checkout_total"}' \
6    --expression-attribute-values '{":s":{"SS":["Trojan War"]},":pc":{"S":"poem"},":inc":{"N":"1"}}' \
7    --return-values UPDATED_NEW

Output:

 1{
 2  "Attributes": {
 3    "checkout_total": {
 4      "N": "1"
 5    },
 6    "subjects": {
 7      "SS": [
 8        "Trojan War"
 9      ]
10    },
11    "product_category": {
12      "S": "poem"
13    }
14  }
15}

It’s important to note that because the ADD operation will continue incrementing and the SET data structure doesn’t allow duplicates, we can rerun the same operation and checkout_total will increase by 1.

For readability, let’s substitute the expression-attribute-names and expression-attribute-values back into the update-expression:

1SET product_category = poem REMOVE category ADD checkout_total 1, subjects ["Trojan War"]

To summarize, using mutliple clauses in a DynamoDB UpdateExpression is supported by simply separating the clauses by keywords.

If you want to perform multiple operations using the same clause, use a comma (,) to separate them.