The Set clause may be used to add new attributes to an item, update existing attributes, add/update list elements, add/update map attributes, and add or subtract numerical values. See the low-level DynamoDB documentation for more details on the underlying features and capabilities.

Adding or updating attributes and elements

The simplest form of update involves setting a specific attribute/element to a specific value using the [] operator or the set method. The value passed may be a literal value such as 42 or an attribute reference such as attr["bar"].

For example:

set {
    attr["foo"] = "hello"                // Set the attribute `foo` to the value `"hello"`
    attr["bar"]["baz"] = listOf(1, 2, 3) // Set `bar`'s entry `baz` to the value `[1, 2, 3]`
    attr["qux"][0] = attr["nox"]         // Set `qux`'s first element to the value of the attribute `nox`
}

If the targeted attribute/element already exists, it will be replaced. If it does not exist, it will be added.

Adding and subtracting numerical values

Set updates may derive their desired value by adding to or subtracting from an existing numerical attribute using the + operator (or plus method) and the - operator (or the minus method):

set {
    attr["foo"] = attr["bar"] + 100 // Set the attribute `foo` to the value of attribute `bar` plus `100`
    attr["baz"] = attr["qux"] - 10  // Set the attribute `baz` to the value of attribute `qux` minus `10`
    attr["nox"] = attr["nox"] + 1   // Increment the numerical value of attribute `nox` by `1`
}

The last update in the preceding example increments the value of nox by setting nox to its current value plus 1. This expression can be simplified by using the += operator (or plusAssign method) or -= operator (or minusAssign method):

set {
    attr["foo"] += 42 // Increments the attribute `foo` by `42`
    attr["bar"] -= 84 // Decrements the attribute `bar` by `84`
}

Conditional updates

Update expressions support setting an attribute value only if it does not already exist to prevent overwriting data by using the orElse method:

set {
    attr["foo"] = attr["foo"] orElse "hello" // Sets the attribute `foo` to `"hello"` unless `foo` already exists
}

Appending lists

Update expressions may form a value by appending a list value to another list value using the appending method:

set {
    attr["foo"] = attr["foo"] appending listOf(1, 2, 3) // Appends the value [1, 2, 3] to the value of `foo`
    attr["bar"] = listOf(4, 5, 6) appending attr["bar"] // Prepends the value [4, 5, 6] to the value of `bar`
}

See also