Menu
Amazon DynamoDB
Developer Guide (API Version 2012-08-10)

Modifying Items and Attributes with Update Expressions

To delete an item from a table, use the DeleteItem operation. You must provide the key of the item you want to delete.

To update an existing item in a table, use the UpdateItem operation. You must provide the key of the item you want to update. You must also provide an update expression, indicating the attributes you want to modify and the values you want to assign to them. For more information, see Update Expressions.

The DeleteItem and UpdateItem operations support conditional writes, where you provide a condition expression to indicate the conditions that must be met in order for the operation to succeed. For more information, see Conditional Write Operations.

If DynamoDB modifies an item successfully, it acknowledges this with an HTTP 200 status code (OK). No further data is returned in the reply; however, you can request that the item or its attributes are returned. You can request these as they appeared before or after an update. For more information, see Return Values.

Note

The examples in the following sections are based on the ProductCatalog item from Case Study: A ProductCatalog Item.

Update Expressions

An update expression specifies the attributes you want to modify, along with new values for those attributes. An update expression also specifies how to modify the attributes—for example, setting a scalar value, or deleting elements in a list or a map. It is a free-form string that can contain attribute names, document paths, operators and functions. It also contains keywords that indicate how to modify attributes.

The PutItem, UpdateItem and DeleteItem operations require a primary key value, and will only modify the item with that key. If you want to perform a conditional update, you must provide an update expression and a condition expression. The condition expression specifies the condition(s) that must be met in order for the update to succeed. The following is a syntax summary for update expressions:


update-expression ::=
    SET set-action , ... 
    | REMOVE remove-action , ...  
    | ADD add-action , ... 
    | DELETE delete-action , ...  

An update expression consists of sections. Each section begins with a SET, REMOVE, ADD or DELETE keyword. You can include any of these sections in an update expression in any order. However, each section keyword can appear only once. You can modify multiple attributes at the same time. The following are some examples of update expressions:

  • SET list[0] = :val1

  • REMOVE #m.nestedField1, #m.nestedField2

  • ADD aNumber :val2, anotherNumber :val3

  • DELETE aSet :val4

The following example shows a single update expression with multiple sections:

  • SET list[0] = :val1 REMOVE #m.nestedField1, #m.nestedField2 ADD aNumber :val2, anotherNumber :val3 DELETE aSet :val4

You can use any attribute name in an update expression, provided that the first character is a-z or A-Z and the second character (if present) is a-z, A-Z, or 0-9. If an attribute name does not meet this requirement, you will need to define an expression attribute name as a placeholder. For more information, see Expression Attribute Names.

To specify a literal value in an update expression, you use expression attribute values. For more information, see Expression Attribute Values.

SET

Use the SET action in an update expression to add one or more attributes and values to an item. If any of these attribute already exist, they are replaced by the new values. However, note that you can also use SET to add or subtract from an attribute that is of type Number. To SET multiple attributes, separate them by commas.

In the following syntax summary:


set-action ::=
    path = value

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

The following are some examples of update expressions using the SET action.

  • The following example updates the Brand and Price attributes. The expression attribute value :b is a string and :p is a number.

    SET Brand = :b, Price = :p

  • The following example updates an attribute in the RelatedItems list. The expression attribute value :ri is a number.

    SET RelatedItems[0] = :ri

  • The following example updates some nested map attributes. The expression attribute name #pr is ProductReviews; the attribute values :r1 and :r2 are strings.

    SET #pr.FiveStar[0] = :r1, #pr.FiveStar[1] = :r2

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.

The following example decreases the Price value of an item. The expression attribute value :p is a number.

  • SET Price = Price - :p

To increase the Price, use the + operator instead.

Using SET with List Elements

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 does not already exist, SET will append the new element at the end of the array.

If you add multiple elements in a single SET operation, the elements are sorted in order by element number. For example, consider the following list:

MyNumbers: { ["Zero","One","Two","Three","Four"] }

The list contains elements [0], [1], [2], [3], [4]. Now, let's use the SET action to add two new elements:

set MyNumbers[8]="Eight", MyNumbers[10] = "Ten"

The list now contains elements [0], [1], [2], [3], [4], [5], [6], with the following data at each element:

MyNumbers: { ["Zero","One","Two","Three","Four","Eight","Ten"] }

Note

The new elements are added to the end of the list and will be assigned the next available element numbers.

Functions for Updating Attributes

The SET action supports the following functions:

  • if_not_exists (path, operand) – If the item does not contain an attribute at the specified path, then if_not_exists evaluates to operand; otherwise, it evaluates to path. You can use this function to avoid overwriting an attribute already present in the item.

  • list_append (operand, operand) – This function evaluates to a list with a new element added to it. The new element must be contained in a list, for example to add 2 to a list, the operand would be [2]. You can append the new element to the start or the end of the list by reversing the order of the operands.

Important

These function names are case-sensitive.

The following are some examples of using the SET action with these functions.

  • If the attribute already exists, the following example does nothing; otherwise it sets the attribute to a default value.

    SET Price = if_not_exists(Price, 100)

  • The following example adds a new element to the FiveStar review list. The expression attribute name #pr is ProductReviews; the attribute value :r is a one-element list. If the list previously had two elements, [0] and [1], then the new element will be [2].

    SET #pr.FiveStar = list_append(#pr.FiveStar, :r)

  • The following example adds another element to the FiveStar review list, but this time the element will be appended to the start of the list at [0]. All of the other elements in the list will be shifted by one.

    SET #pr.FiveStar = list_append(:r, #pr.FiveStar)

REMOVE

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

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


remove-action ::=
    path

The following is an example of an update expression using the REMOVE action. Several attributes are removed from the item:

  • REMOVE Title, RelatedItems[2], Pictures.RearView

Using REMOVE with List Elements

When you remove an existing list element, the remaining elements are shifted. For example, consider the following list:

  • MyNumbers: { ["Zero","One","Two","Three","Four"] }

The list contains elements [0], [1], [2], [3], and [4]. Now, let's use the REMOVE action to remove two of the elements:

  • REMOVE MyNumbers[1], MyNumbers[3]

The remaining elements are shifted to the right, resulting in a list with elements [0], [1], and [2], with the following data at each element:

  • MyNumbers: { ["Zero","Two","Four"] }

Note

If you use REMOVE to delete a nonexistent item past the last element of the list, nothing happens: There is no data to be deleted. For example, the following expression has no effect on the MyNumbers list:

  • REMOVE MyNumbers[11]

ADD

Important

The ADD action only supports Number and set data types. In general, we recommend using SET rather than ADD.

Use the ADD action in an update expression to do either of the following:

  • If the attribute does not already exist, add the new attribute and its value(s) to the item.

  • If the attribute already exists, then 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, then the value is mathematically added to the existing attribute. (If the value is a negative number, then it is subtracted from the existing attribute.)

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

To perform multiple ADD operations, separate them by 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 following are some examples of update expressions using the add action.

  • The following example increments a number. The expression attribute value :n is a number, and this value will be added to Price.

    ADD Price :n

  • The following example adds one or more values to the Color set. The expression attribute value :c is a string set.

    ADD Color :c

DELETE

Important

The DELETE action only supports set data types.

Use the DELETE action in an update expression to delete an element from a set. To perform multiple DELETE operations, separate them by 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 value element is the element(s) in the set that you want to delete.


delete-action ::=
    path value 
			

The following example deletes an element from the Color set using the DELETE action. The expression attribute value :c is a string set.

DELETE Color :c

Conditional Write Operations

To perform a conditional delete, use a DeleteItem operation with a condition expression. The condition expression must evaluate to true in order for the operation to succeed; otherwise, the operation fails.

Suppose that you want to delete an item, but only if there are no related items. You can use the following expression to do this:

  • Condition expression: attribute_not_exists(RelatedItems)

To perform a conditional update, use an UpdateItem operation with an update expression and a condition expression. The condition expression must evaluate to true in order for the operation to succeed; otherwise, the operation fails.

Suppose that you want to increase the price of an item by a certain amount, defined as :amt, but only if the result does not exceed a maximum price. You can do this by calculating the highest current price that would permit the increase, subtracting the increase :amt from the maximum. Define the result as :limit, and then use the following conditional expression:

  • Condition expression: Price <= :limit)

  • Update expression: SET Price = Price + :amt

Now suppose you want to set a front view picture for an item, but only if that item doesn't already have such a picture—you want to avoid overwriting any existing element. You can use the following expressions to do this:

  • Update expression: SET Pictures.FrontView = :myURL

    (Assume that :myURL is the location of a picture of the item, such as http://example.com/picture.jpg.)

  • Condition expression: attribute_not_exists(Pictures.FrontView)

Return Values

When you perform a DeleteItem or UpdateItem operation, DynamoDB can optionally return some or all of the item in the response. To do this, you set the ReturnValues parameter. The default value for ReturnValues is NONE, so no data will be returned. You can change this behavior as described below.

Deleting an Item

In a DeleteItem operation, you can set ReturnValues to ALL_OLD. Doing this will cause DynamoDB to return the entire item, as it appeared before the delete operation occurred.

Updating an Item

In an UpdateItem operation, you can set ReturnValues to one of the following:

  • ALL_OLD – The entire item is returned, as it appeared before the update occurred.

  • ALL_NEW – The entire item is returned, as it appears after the update.

  • UPDATED_OLD – Only the value(s) that you updated are returned, as they appear before the update occurred.

  • UPDATED_NEW – Only the value(s) that you updated are returned, as they appear after the update.