Using update expressions in DynamoDB - Amazon DynamoDB
SET — modifying or adding item attributesREMOVE — deleting attributes from an itemADD — updating numbers and setsDELETE — removing elements from a setUsing multiple update expressions

Using update expressions in DynamoDB

The UpdateItem operation updates an existing item, or adds a new item to the table if it does not already exist. You must provide the key of the item that you want to update. You must also provide an update expression, indicating the attributes that you want to modify and the values that you want to assign to them.

An update expression specifies how UpdateItem will modify the attributes of an item—for example, setting a scalar value or removing elements from a list or a map.

The following is a syntax summary for update expressions.

update-expression ::=
    [ SET action [, action] ... ]
    [ REMOVE action [, action] ...]
    [ ADD action [, action] ... ]
    [ DELETE action [, action] ...]

An update expression consists of one or more clauses. Each clause begins with a SET, REMOVE, ADD, or DELETE keyword. You can include any of these clauses in an update expression, in any order. However, each action keyword can appear only once.

Within each clause, there are one or more actions separated by commas. Each action represents a data modification.

The examples in this section are based on the ProductCatalog item shown in Using projection expressions in DynamoDB.

The topics below cover some different use cases for the SET action.

SET — modifying or adding item attributes

Use the SET action in an update expression to add one or more attributes to an item. If any of these attributes already exists, they are overwritten by the new values. If you want to avoid overwriting an existing attribute, you can use SET with the if_not_exists function. The if_not_exists function is specific to the SET action and can only be used in an update expression.

When you use SET to update a list element, the contents of that element are replaced with the new data that you specify. If the element doesn't already exist, SET appends the new element at the end of the list.

If you add multiple elements in a single SET operation, the elements are sorted in order by element number.

You can also use SET to add or subtract from an attribute that is of type Number. To perform multiple SET actions, separate them with commas.

In the following syntax summary:

  • The path element is the document path to the item.

  • An operand element can be either a document path to an item or a function.

set-action ::=
    path = value

value ::=
    operand
    | operand '+' operand
    | operand '-' operand

operand ::=
    path | function

function ::=
    if_not_exists (path)

If the item does not contain an attribute at the specified path, if_not_exists evaluates to value. Otherwise, it evaluates to path.

The following PutItem operation creates a sample item that the examples refer to.

aws dynamodb put-item \
    --table-name ProductCatalog \
    --item file://item.json

The arguments for --item are stored in the item.json file. (For simplicity, only a few item attributes are used.)

{
    "Id": {"N": "789"},
    "ProductCategory": {"S": "Home Improvement"},
    "Price": {"N": "52"},
    "InStock": {"BOOL": true},
    "Brand": {"S": "Acme"}
}

Modifying attributes

Example

Update the ProductCategory and Price attributes.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET ProductCategory = :c, Price = :p" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

The arguments for --expression-attribute-values are stored in the values.json file.

{
    ":c": { "S": "Hardware" },
    ":p": { "N": "60" }
}
Note

In the UpdateItem operation, --return-values ALL_NEW causes DynamoDB to return the item as it appears after the update.

Adding lists and maps

Example

Add a new list and a new map.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems = :ri, ProductReviews = :pr" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

The arguments for --expression-attribute-values are stored in the values.json file.

{
    ":ri": {
        "L": [
            { "S": "Hammer" }
        ]
    },
    ":pr": {
        "M": {
            "FiveStar": {
                "L": [
                    { "S": "Best product ever!" }
                ]
            }
        }
    }
}

Adding elements to a list

Example

Add a new attribute to the RelatedItems list. (Remember that list elements are zero-based, so [0] represents the first element in the list, [1] represents the second, and so on.)

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems[1] = :ri" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

The arguments for --expression-attribute-values are stored in the values.json file.

{
    ":ri": { "S": "Nails" }
}
Note

When you use SET to update a list element, the contents of that element are replaced with the new data that you specify. If the element doesn't already exist, SET appends the new element at the end of the list.

If you add multiple elements in a single SET operation, the elements are sorted in order by element number.

Adding nested map attributes

Example

Add some nested map attributes.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #pr.#5star[1] = :r5, #pr.#3star = :r3" \
    --expression-attribute-names file://names.json \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW

The arguments for --expression-attribute-names are stored in the names.json file.

{
    "#pr": "ProductReviews",
    "#5star": "FiveStar",
    "#3star": "ThreeStar"
}

The arguments for --expression-attribute-values are stored in the values.json file.

{
    ":r5": { "S": "Very happy with my purchase" },
    ":r3": {
        "L": [
            { "S": "Just OK - not that great" }
        ]
    }
}

Incrementing and decrementing numeric attributes

You can add to or subtract from an existing numeric attribute. To do this, use the + (plus) and - (minus) operators.

Example

Decrease the Price of an item.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = Price - :p" \
    --expression-attribute-values '{":p": {"N":"15"}}' \
    --return-values ALL_NEW

To increase the Price, you would use the + operator in the update expression.

Appending elements to a list

You can add elements to the end of a list. To do this, use SET with the list_append function. (The function name is case sensitive.) The list_append function is specific to the SET action and can only be used in an update expression. The syntax is as follows.

  • list_append (list1, list2)

The function takes two lists as input and appends all elements from list2 to list1.

Example

In Adding elements to a list, you create the RelatedItems list and populate it with two elements: Hammer and Nails. Now you append two more elements to the end of RelatedItems.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #ri = list_append(#ri, :vals)" \
    --expression-attribute-names '{"#ri": "RelatedItems"}' \
    --expression-attribute-values file://values.json  \
    --return-values ALL_NEW

The arguments for --expression-attribute-values are stored in the values.json file.

{
    ":vals": {
        "L": [
            { "S": "Screwdriver" },
            {"S": "Hacksaw" }
        ]
    }
}

Finally, you append one more element to the beginning of RelatedItems. To do this, swap the order of the list_append elements. (Remember that list_append takes two lists as input and appends the second list to the first.)

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #ri = list_append(:vals, #ri)" \
    --expression-attribute-names '{"#ri": "RelatedItems"}' \
    --expression-attribute-values '{":vals": {"L": [ { "S": "Chisel" }]}}' \
    --return-values ALL_NEW

The resulting RelatedItems attribute now contains five elements, in the following order: Chisel, Hammer, Nails, Screwdriver, Hacksaw.

Preventing overwrites of an existing attribute

Example

Set the Price of an item, but only if the item does not already have a Price attribute. (If Price already exists, nothing happens.)

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = if_not_exists(Price, :p)" \
    --expression-attribute-values '{":p": {"N": "100"}}' \
    --return-values ALL_NEW

REMOVE — deleting attributes from an item

Use the REMOVE action in an update expression to remove one or more attributes from an item in Amazon DynamoDB. To perform multiple REMOVE actions, separate them with commas.

The following is a syntax summary for REMOVE in an update expression. The only operand is the document path for the attribute that you want to remove.

remove-action ::=
    path
Example

Remove some attributes from an item. (If the attributes don't exist, nothing happens.)

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "REMOVE Brand, InStock, QuantityOnHand" \
    --return-values ALL_NEW

Removing elements from a list

You can use REMOVE to delete individual elements from a list.

Example

In Appending elements to a list, you modify a list attribute (RelatedItems) so that it contained five elements:

  • [0]—Chisel

  • [1]—Hammer

  • [2]—Nails

  • [3]—Screwdriver

  • [4]—Hacksaw

The following AWS Command Line Interface (AWS CLI) example deletes Hammer and Nails from the list.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \
    --return-values ALL_NEW

After Hammer and Nails are removed, the remaining elements are shifted. The list now contains the following:

  • [0]—Chisel

  • [1]—Screwdriver

  • [2]—Hacksaw

ADD — updating numbers and sets

Note

In general, we recommend using SET rather than ADD.

Use the ADD action in an update expression to add a new attribute and its values to an item.

If the attribute already exists, the behavior of ADD depends on the attribute's data type:

  • If the attribute is a number, and the value you are adding is also a number, the value is mathematically added to the existing attribute. (If the value is a negative number, it is subtracted from the existing attribute.)

  • If the attribute is a set, and the value you are adding is also a set, the value is appended to the existing set.

Note

The ADD action supports only number and set data types.

To perform multiple ADD actions, separate them with commas.

In the following syntax summary:

  • The path element is the document path to an attribute. The attribute must be either a Number or a set data type.

  • The value element is a number that you want to add to the attribute (for Number data types), or a set to append to the attribute (for set types).

add-action ::=
    path value

The topics below cover some different use cases for the ADD action.

Adding a number

Assume that the QuantityOnHand attribute does not exist. The following AWS CLI example sets QuantityOnHand to 5.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD QuantityOnHand :q" \
    --expression-attribute-values '{":q": {"N": "5"}}' \
    --return-values ALL_NEW

Now that QuantityOnHand exists, you can rerun the example to increment QuantityOnHand by 5 each time.

Adding elements to a set

Assume that the Color attribute does not exist. The following AWS CLI example sets Color to a string set with two elements.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD Color :c" \
    --expression-attribute-values '{":c": {"SS":["Orange", "Purple"]}}' \
    --return-values ALL_NEW

Now that Color exists, you can add more elements to it.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD Color :c" \
    --expression-attribute-values '{":c": {"SS":["Yellow", "Green", "Blue"]}}' \
    --return-values ALL_NEW

DELETE — removing elements from a set

Important

The DELETE action supports only Set data types.

Use the DELETE action in an update expression to remove one or more elements from a set. To perform multiple DELETE actions, separate them with commas.

In the following syntax summary:

  • The path element is the document path to an attribute. The attribute must be a set data type.

  • The subset is one or more elements that you want to delete from path. You must specify subset as a set type.

delete-action ::=
    path subset
Example

In Adding elements to a set, you create the Color string set. This example removes some of the elements from that set.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "DELETE Color :p" \
    --expression-attribute-values '{":p": {"SS": ["Yellow", "Purple"]}}' \
    --return-values ALL_NEW

Using multiple update expressions

You can use multiple update expressions in a single statement.

If you want to modify an attribute's value and completely remove another attribute, you could use a SET and a REMOVE action in a single statement. This operation would reduce the Price value to 15 while also removing the InStock attribute from the item.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = Price - :p REMOVE InStock" \
    --expression-attribute-values '{":p": {"N":"15"}}' \
    --return-values ALL_NEW

If you want to add to a list while also changing another attribute's value, you could use two SET actions in a single statement. This operation would add "Nails" to the RelatedItems list attribute and also set the Price value to 21.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems[1] = :newValue, Price = :newPrice" \
    --expression-attribute-values '{":newValue": {"S":"Nails"}, ":newPrice": {"N":"21"}}'  \
    --return-values ALL_NEW