A DSL interface providing support for creating "low-level" DynamoDB update expressions. The methods and properties in this interface specify how a matching item should be modified in an UpdateItem operation.

For example:

update {
    set {
        attr["foo"] = 42
    }
}

This example creates an expression which will set the attribute foo to the value 42.

(Non-)Relationship to schema

The expressions formed by UpdateDsl are referred to as "low-level" update expressions. This is because they are not restricted by or adherent to any defined ItemSchema. Instead, they are a DSL convenience layer over literal DynamoDB expression strings and expression attribute value maps. As such they provide minimal type correctness and may allow you to form expressions which are invalid given the shape of your data, such as attributes which don't exist, comparisons with mismatched data types, etc.

Attributes

Every update expression contains at least one attribute. Attributes are referenced by attribute paths, analogous to document paths in DynamoDB. Attribute paths consist of one or more elements, which are either names (e.g., of a top-level attribute or a nested key in a map attribute) or indices (i.e., into a list). The first (and often only) element of an attribute path is a name.

Getting a top-level attribute

All attribute paths start with a top-level attribute expression, created by the attr function:

attr["foo"] // References the top-level attribute "foo"

Note, the attribute foo may not exist for a given item or for an entire table.

Nesting

Sometimes values are nested inside other attributes like lists and maps. Update expressions can operate on those nested values by forming a more detailed attribute path using the [] operator or get functions on a path.

For example, consider an item structure such as:

{
    "foo": "Hello",
    "bar": {
        "baz": [
            "Yay",
            null,
            42,
            true
        ]
    }
}

The value "Yay" can be referenced with the following DSL syntax:

attr["bar"]["baz"][0]

That is, in the top-level attribute bar, in the value keyed by baz, the element at index 0.

Clauses

An update expression consists of at least one of the following clauses:

• Set: modify or add item attributes

• Remove: delete item attributes

• Add: update numbers and sets

• Delete: remove elements from sets

Each of these clauses may contain one or more updates (for instance, setting multiple attribute values at once, deleting multiple elements from a set, etc.).

These clauses may be specified in any order. If a given clause is repeated multiple times within an update block, the last one overrides the previous ones.

See the documentation for the Set, Remove, Add, and Delete interfaces for more details about each clause.