Update Operations

The UpdateItem DynamoDB operations allows you to create or modify attributes of an item using an update expression. See the official documentation for more details.

Suppose that you have defined a Thread Model for the examples below.

from pynamodb.models import Model
from pynamodb.attributes import (
    ListAttribute, UnicodeAttribute, UnicodeSetAttribute, NumberAttribute
)


class Thread(Model):
    class Meta:
        table_name = 'Thread'

    forum_name = UnicodeAttribute(hash_key=True)
    subjects = UnicodeSetAttribute(default=set)
    author = UnicodeAttribute(null=True)
    views = NumberAttribute(default=0)
    notes = ListAttribute(default=list)

Update Expressions

PynamoDB supports creating update expressions from attributes using a mix of built-in operators and method calls. Any value provided will be serialized using the serializer defined for that attribute.

DynamoDB Action / Operator

PynamoDB Syntax

Attribute Types

Example

SET

set( value )

Any

Thread.views.set(10)

REMOVE

remove()

Any

Thread.notes.remove()

REMOVE

remove()

Element of List

Thread.notes[0].remove()

ADD

add( number )

Number

Thread.views.add(1)

ADD

add( set )

Set

Thread.subjects.add({'A New Subject', 'Another New Subject'})

DELETE

delete( set )

Set

Thread.subjects.delete({'An Old Subject'})

The following expressions and functions can only be used in the context of the above actions:

DynamoDB Action / Operator

PynamoDB Syntax

Attribute Types

Example

attr_or_value_1 + attr_or_value_2

attr_or_value_1 + attr_or_value_2

Number

Thread.views + 5

attr_or_value_1 - attr_or_value_2

attr_or_value_1 - attr_or_value_2

Number

5 - Thread.views

list_append( attr , value )

append( value )

List

Thread.notes.append(['my last note'])

list_append( value , attr )

prepend( value )

List

Thread.notes.prepend(['my first note'])

if_not_exists( attr, value )

attr | value

Any

Thread.forum_name | 'Default Forum Name'

set action

The set action is the simplest action as it overwrites any previously stored value:

thread.update(actions=[
    Thread.views.set(10),
])
assert thread.views == 10

It can reference existing values (from this or other attributes) for arithmetics and concatenation:

# Increment views by 5
thread.update(actions=[
    Thread.views.set(Thread.views + 5)
])

# Append 2 notes
thread.update(actions=[
    Thread.notes.set(
        Thread.notes.append([
            'my last note',
            'p.s. no, really, this is my last note',
        ]),
    )
])

# Prepend a note
thread.update(actions=[
    Thread.notes.set(
        Thread.notes.prepend([
            'my first note',
        ]),
    )
])

# Set author to John Doe unless there's already one
thread.update(actions=[
    Thread.author.set(Thread.author | 'John Doe')
])

remove action

The remove action unsets attributes:

thread.update(actions=[
    Thread.views.remove(),
])
assert thread.views == 0  # default value

It can also be used to remove elements from a list attribute:

# Remove the first note
thread.update(actions=[
    Thread.notes[0].remove(),
])

add action

Applying to (binary, number and string) set attributes, the add action adds elements to the set:

# Add the subjects 'A New Subject' and 'Another New Subject'
thread.update(actions=[
    Thread.subjects.add({'A New Subject', 'Another New Subject'})
])

Applying to number attributes, the add action increments or decrements the number and is equivalent to a set action:

# Increment views by 5
thread.update(actions=[
    Thread.views.add(5),
])
# Also increment views by 5
thread.update(actions=[
    Thread.views.set(Thread.views + 5),
])

delete action

For set attributes, the delete action is the opposite of the add action:

# Delete the subject 'An Old Subject'
thread.update(actions=[
    Thread.subjects.delete({'An Old Subject'})
])