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)
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' |
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')
])
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(),
])
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),
])
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'})
])