An expression that defines one or more attributes to be updated, the action to be performed on them, and new
value(s) for them.
The following action values are available for UpdateExpression
.
-
SET
- Adds one or more attributes and values to an item. If any of these attribute already
exist, they are replaced by the new values. You can also use SET
to add or subtract from an
attribute that is of type Number. For example: SET myNum = myNum + :val
SET
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 that may already be present in the item.
-
list_append (operand, operand)
- evaluates to a list with a new element added to it. You can
append the new element to the start or the end of the list by reversing the order of the operands.
These function names are case-sensitive.
-
REMOVE
- Removes one or more attributes from an item.
-
ADD
- Adds the specified value to the item, if the attribute does not already exist. If the
attribute does exist, then the behavior of ADD
depends on the data type of the attribute:
-
If the existing attribute is a number, and if Value
is also a number, then Value
is
mathematically added to the existing attribute. If Value
is a negative number, then it is
subtracted from the existing attribute.
If you use ADD
to increment or decrement a number value for an item that doesn't exist before
the update, DynamoDB uses 0
as the initial value.
Similarly, if you use ADD
for an existing item to increment or decrement an attribute value that
doesn't exist before the update, DynamoDB uses 0
as the initial value. For example, suppose that
the item you want to update doesn't have an attribute named itemcount, but you decide to
ADD
the number 3
to this attribute anyway. DynamoDB will create the
itemcount attribute, set its initial value to 0
, and finally add 3
to it.
The result will be a new itemcount attribute in the item, with a value of 3
.
-
If the existing data type is a set and if Value
is also a set, then Value
is added
to the existing set. For example, if the attribute value is the set [1,2]
, and the
ADD
action specified [3]
, then the final attribute value is [1,2,3]
.
An error occurs if an ADD
action is specified for a set attribute and the attribute type
specified does not match the existing set type.
Both sets must have the same primitive data type. For example, if the existing data type is a set of strings,
the Value
must also be a set of strings.
The ADD
action only supports Number and set data types. In addition, ADD
can only
be used on top-level attributes, not nested attributes.
-
DELETE
- Deletes an element from a set.
If a set of values is specified, then those values are subtracted from the old set. For example, if the
attribute value was the set [a,b,c]
and the DELETE
action specifies
[a,c]
, then the final attribute value is [b]
. Specifying an empty set is an error.
The DELETE
action only supports set data types. In addition, DELETE
can only be
used on top-level attributes, not nested attributes.
You can have many actions in a single expression, such as the following:
SET a=:value1, b=:value2 DELETE :value3, :value4, :value5
For more information on update expressions, see Modifying
Items and Attributes in the Amazon DynamoDB Developer Guide.