Skip to content

Commit caa8f68

Browse files
ikonstikonst
authored
Improve docs for conditional, update expressions (#1141)
1 parent b3330a4 commit caa8f68

File tree

3 files changed

+211
-81
lines changed

3 files changed

+211
-81
lines changed

‎docs/conditional.rst

+67-49
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,17 @@
33
Conditional Operations
44
======================
55

6-
Some DynamoDB operations (UpdateItem, PutItem, DeleteItem) support the inclusion of conditions. The user can supply a condition to be
7-
evaluated by DynamoDB before the operation is performed. See the `official documentation <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.ConditionalUpdate>`_
6+
Some DynamoDB operations support the inclusion of conditions. The user can supply a condition to be
7+
evaluated by DynamoDB before an item is modified (with save, update and delete) or before an item is included
8+
in the result (with query and scan). See the `official documentation <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.ConditionalUpdate>`_
89
for more details.
910

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

1213
.. code-block:: python
1314
1415
from pynamodb.models import Model
15-
from pynamodb.attributes import (
16-
UnicodeAttribute, NumberAttribute
17-
)
16+
from pynamodb.attributes import UnicodeAttribute, NumberAttribute
1817
1918
2019
class Thread(Model):
@@ -24,6 +23,9 @@ Suppose that you have defined a `Thread` Model for the examples below.
2423
forum_name = UnicodeAttribute(hash_key=True)
2524
subject = UnicodeAttribute(range_key=True)
2625
views = NumberAttribute(default=0)
26+
authors = ListAttribute()
27+
properties = MapAttribute()
28+
2729
2830
.. _conditions:
2931

@@ -36,61 +38,78 @@ See the `comparison operator and function reference <https://docs.aws.amazon.com
3638
for more details.
3739

3840
.. csv-table::
39-
:header: DynamoDB Condition, PynamoDB Syntax, Example
40-
41-
=, ==, Thread.forum_name == 'Some Forum'
42-
<>, !=, Thread.forum_name != 'Some Forum'
43-
<, <, Thread.views < 10
44-
<=, <=, Thread.views <= 10
45-
>, >, Thread.views > 10
46-
>=, >=, Thread.views >= 10
47-
BETWEEN, "between( `lower` , `upper` )", "Thread.views.between(1, 5)"
48-
IN, is_in( `*values` ), "Thread.subject.is_in('Subject', 'Other Subject')"
49-
attribute_exists ( `path` ), exists(), Thread.forum_name.exists()
50-
attribute_not_exists ( `path` ), does_not_exist(), Thread.forum_name.does_not_exist()
51-
"attribute_type ( `path` , `type` )", is_type(), Thread.forum_name.is_type()
52-
"begins_with ( `path` , `substr` )", startswith( `prefix` ), Thread.subject.startswith('Example')
53-
"contains ( `path` , `operand` )", contains( `item` ), Thread.subject.contains('foobar')
54-
size ( `path`), size( `attribute` ), size(Thread.subject) == 10
55-
AND, &, (Thread.views > 1) & (Thread.views < 5)
56-
OR, \|, (Thread.views < 1) | (Thread.views > 5)
57-
NOT, ~, ~Thread.subject.contains('foobar')
58-
59-
Conditions expressions using nested list and map attributes can be created with Python's item operator ``[]``:
41+
:header: DynamoDB Condition, PynamoDB Syntax, Attribute Types, Example
42+
43+
=, ==, Any, :code:`Thread.forum_name == 'Some Forum'`
44+
<>, !=, Any, :code:`Thread.forum_name != 'Some Forum'`
45+
<, <, "Binary, Number, String", :code:`Thread.views < 10`
46+
<=, <=, "Binary, Number, String", :code:`Thread.views <= 10`
47+
>, >, "Binary, Number, String", :code:`Thread.views > 10`
48+
>=, >=, "Binary, Number, String", :code:`Thread.views >= 10`
49+
BETWEEN, "between( `lower` , `upper` )", "Binary, Number, String", ":code:`Thread.views.between(1, 5)`"
50+
IN, is_in( `*values` ), "Binary, Number, String", ":code:`Thread.subject.is_in('Subject', 'Other Subject')`"
51+
attribute_exists ( `path` ), exists(), Any, :code:`Thread.forum_name.exists()`
52+
attribute_not_exists ( `path` ), does_not_exist(), Any, :code:`Thread.forum_name.does_not_exist()`
53+
"attribute_type ( `path` , `type` )", is_type(), Any, :code:`Thread.forum_name.is_type()`
54+
"begins_with ( `path` , `substr` )", startswith( `prefix` ), String, :code:`Thread.subject.startswith('Example')`
55+
"contains ( `path` , `operand` )", contains( `item` ), "Set, String", :code:`Thread.subject.contains('foobar')`
56+
size ( `path` ), size( `attribute` ), "Binary, List, Map, Set, String", :code:`size(Thread.subject) == 10`
57+
AND, &, Any, :code:`(Thread.views > 1) & (Thread.views < 5)`
58+
OR, \|, Any, :code:`(Thread.views < 1) | (Thread.views > 5)`
59+
NOT, ~, Any, :code:`~Thread.subject.contains('foobar')`
60+
61+
Conditions expressions using nested list and map attributes can be created with Python's item operator ``[]``.
6062

6163
.. code-block:: python
6264
63-
from pynamodb.models import Model
64-
from pynamodb.attributes import (
65-
ListAttribute, MapAttribute, UnicodeAttribute
66-
)
67-
68-
class Container(Model):
69-
class Meta:
70-
table_name = 'Container'
65+
# Query for threads where 'properties' map contains key 'emoji'
66+
Thread.query(..., filter_condition=Thread.properties['emoji'].exists())
7167
72-
name = UnicodeAttribute(hash_key = True)
73-
my_map = MapAttribute()
74-
my_list = ListAttribute()
68+
# Query for threads where the first author's name contains "John"
69+
Thread.authors[0].contains("John")
7570
76-
print(Container.my_map['foo'].exists() | Container.my_list[0].contains('bar'))
77-
78-
79-
Conditions can be composited using & (AND) and | (OR) operators. For the & (AND) operator, the left-hand side
71+
Conditions can be composited using ``&`` (AND) and ``|`` (OR) operators. For the ``&`` (AND) operator, the left-hand side
8072
operand can be ``None`` to allow easier chaining of filter conditions:
8173

8274
.. code-block:: python
8375
8476
condition = None
8577
86-
if query.name:
87-
condition &= Person.name == query.name
78+
if request.subject:
79+
condition &= Thread.subject.contains(request.subject)
80+
81+
if request.min_views:
82+
condition &= Thread.views >= min_views
83+
84+
results = Thread.query(..., filter_condition=condition)
85+
86+
Conditioning on keys
87+
^^^^^^^^^^^^^^^^^^^^
88+
89+
When writing to a table (save, update, delete), an ``exists()`` condition on a key attribute
90+
ensures that the item already exists (under the given key) in the table before the operation.
91+
For example, a `save` or `update` would update an existing item, but fail if the item
92+
does not exist.
93+
94+
Correspondingly, a ``does_not_exist()`` condition on a key ensures that the item
95+
does not exist. For example, a `save` with such a condition ensures that it's not
96+
overwriting an existing item.
97+
98+
For models with a range key, conditioning ``exists()`` on either the hash key
99+
or the range key has the same effect. There is no way to condition on _some_ item
100+
existing with the given hash key. For example:
101+
102+
.. code-block:: python
88103
89-
if query.age:
90-
condition &= Person.age == query.age
104+
thread = Thread('DynamoDB', 'Using conditions')
91105
92-
results = Person.query(..., filter_condition=condition)
106+
# This will fail if the item ('DynamoDB', 'Using conditions') does not exist,
107+
# even if the item ('DynamoDB', 'Using update expressions') does.
108+
thread.save(condition=Thread.forum_name.exists())
93109
110+
# This will fail if the item ('DynamoDB', 'Using conditions') does not exist,
111+
# even if the item ('S3', 'Using conditions') does.
112+
thread.save(condition=Thread.subject.exists())
94113
95114
96115
Conditional Model.save
@@ -139,6 +158,5 @@ You can check for conditional operation failures by inspecting the cause of the
139158
try:
140159
thread_item.save(Thread.forum_name.exists())
141160
except PutError as e:
142-
if isinstance(e.cause, ClientError):
143-
code = e.cause.response['Error'].get('Code')
144-
print(code == "ConditionalCheckFailedException")
161+
if e.cause_response_code = "ConditionalCheckFailedException":
162+
raise ThreadDidNotExistError()

‎docs/updates.rst

+126-12
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ Suppose that you have defined a `Thread` Model for the examples below.
2020
table_name = 'Thread'
2121
2222
forum_name = UnicodeAttribute(hash_key=True)
23-
subjects = UnicodeSetAttribute(default=dict)
23+
subjects = UnicodeSetAttribute(default=set)
24+
author = UnicodeAttribute(null=True)
2425
views = NumberAttribute(default=0)
2526
notes = ListAttribute(default=list)
2627
@@ -34,14 +35,127 @@ PynamoDB supports creating update expressions from attributes using a mix of bui
3435
Any value provided will be serialized using the serializer defined for that attribute.
3536

3637
.. csv-table::
37-
:header: DynamoDB Action / Operator, PynamoDB Syntax, Example
38-
39-
SET, set( `value` ), Thread.views.set(10)
40-
REMOVE, remove(), Thread.notes[0].remove()
41-
ADD, add( `value` ), "Thread.subjects.add({'A New Subject', 'Another New Subject'})"
42-
DELETE, delete( `value` ), Thread.subjects.delete({'An Old Subject'})
43-
`attr_or_value_1` \+ `attr_or_value_2`, `attr_or_value_1` \+ `attr_or_value_2`, Thread.views + 5
44-
`attr_or_value_1` \- `attr_or_value_2`, `attr_or_value_1` \- `attr_or_value_2`, 5 - Thread.views
45-
"list_append( `attr` , `value` )", append( `value` ), Thread.notes.append(['my last note'])
46-
"list_append( `value` , `attr` )", prepend( `value` ), Thread.notes.prepend(['my first note'])
47-
"if_not_exists( `attr`, `value` )", `attr` | `value`, Thread.forum_name | 'Default Forum Name'
38+
:header: DynamoDB Action / Operator, PynamoDB Syntax, Attribute Types, Example
39+
40+
SET, set( `value` ), Any, :code:`Thread.views.set(10)`
41+
REMOVE, remove(), "Any", :code:`Thread.notes.remove()`
42+
REMOVE, remove(), "Element of List", :code:`Thread.notes[0].remove()`
43+
ADD, add( `number` ), "Number", ":code:`Thread.views.add(1)`"
44+
ADD, add( `set` ), "Set", ":code:`Thread.subjects.add({'A New Subject', 'Another New Subject'})`"
45+
DELETE, delete( `set` ), "Set", :code:`Thread.subjects.delete({'An Old Subject'})`
46+
47+
The following expressions and functions can only be used in the context of the above actions:
48+
49+
.. csv-table::
50+
:header: DynamoDB Action / Operator, PynamoDB Syntax, Attribute Types, Example
51+
52+
`attr_or_value_1` \+ `attr_or_value_2`, `attr_or_value_1` \+ `attr_or_value_2`, "Number", :code:`Thread.views + 5`
53+
`attr_or_value_1` \- `attr_or_value_2`, `attr_or_value_1` \- `attr_or_value_2`, "Number", :code:`5 - Thread.views`
54+
"list_append( `attr` , `value` )", append( `value` ), "List", :code:`Thread.notes.append(['my last note'])`
55+
"list_append( `value` , `attr` )", prepend( `value` ), "List", :code:`Thread.notes.prepend(['my first note'])`
56+
"if_not_exists( `attr`, `value` )", `attr` | `value`, Any, :code:`Thread.forum_name | 'Default Forum Name'`
57+
58+
``set`` action
59+
""""""""""""""
60+
61+
The ``set`` action is the simplest action as it overwrites any previously stored value:
62+
63+
.. code-block:: python
64+
65+
thread.update(actions=[
66+
Thread.views.set(10),
67+
])
68+
assert thread.views == 10
69+
70+
It can reference existing values (from this or other attributes) for arithmetics and concatenation:
71+
72+
.. code-block:: python
73+
74+
# Increment views by 5
75+
thread.update(actions=[
76+
Thread.views.set(Thread.views + 5)
77+
])
78+
79+
# Append 2 notes
80+
thread.update(actions=[
81+
Thread.notes.set(
82+
Thread.notes.append([
83+
'my last note',
84+
'p.s. no, really, this is my last note',
85+
]),
86+
)
87+
])
88+
89+
# Prepend a note
90+
thread.update(actions=[
91+
Thread.notes.set(
92+
Thread.notes.prepend([
93+
'my first note',
94+
]),
95+
)
96+
])
97+
98+
# Set author to John Doe unless there's already one
99+
thread.update(actions=[
100+
Thread.author.set(Thread.author | 'John Doe')
101+
])
102+
103+
``remove`` action
104+
^^^^^^^^^^^^^^^^^
105+
106+
The ``remove`` action unsets attributes:
107+
108+
.. code-block:: python
109+
110+
thread.update(actions=[
111+
Thread.views.remove(),
112+
])
113+
assert thread.views == 0 # default value
114+
115+
It can also be used to remove elements from a list attribute:
116+
117+
.. code-block:: python
118+
119+
# Remove the first note
120+
thread.update(actions=[
121+
Thread.notes[0].remove(),
122+
])
123+
124+
125+
``add`` action
126+
^^^^^^^^^^^^^^
127+
128+
Applying to (binary, number and string) set attributes, the ``add`` action adds elements to the set:
129+
130+
.. code-block:: python
131+
132+
# Add the subjects 'A New Subject' and 'Another New Subject'
133+
thread.update(actions=[
134+
Thread.subjects.add({'A New Subject', 'Another New Subject'})
135+
])
136+
137+
Applying to number attributes, the ``add`` action increments or decrements the number
138+
and is equivalent to a ``set`` action:
139+
140+
.. code-block:: python
141+
142+
# Increment views by 5
143+
thread.update(actions=[
144+
Thread.views.add(5),
145+
])
146+
# Also increment views by 5
147+
thread.update(actions=[
148+
Thread.views.set(Thread.views + 5),
149+
])
150+
151+
``delete`` action
152+
^^^^^^^^^^^^^^^^^
153+
154+
For set attributes, the ``delete`` action is the opposite of the ``add`` action:
155+
156+
.. code-block:: python
157+
158+
# Delete the subject 'An Old Subject'
159+
thread.update(actions=[
160+
Thread.subjects.delete({'An Old Subject'})
161+
])

0 commit comments

Comments
 (0)