Condition and filter expressions, operators, and functions in DynamoDB
To manipulate data in an DynamoDB table, you use the PutItem
, UpdateItem
, and
DeleteItem
operations. For these data manipulation operations, you can specify a condition
expression to determine which items should be modified. If the condition expression
evaluates to true, the operation succeeds. Otherwise, the operation fails.
This section covers the built-in functions and keywords for writing filter expressions and condition expressions in Amazon DynamoDB. For more detailed information on functions and programming with DynamoDB, see Programming with DynamoDB and the Amazon SDKs and the DynamoDB API Reference.
Topics
Syntax for filter and condition expressions
In the following syntax summary, an operand
can be the
following:
-
A top-level attribute name, such as
Id
,Title
,Description
, orProductCategory
-
A document path that references a nested attribute
condition-expression ::=
operand
comparatoroperand
|operand
BETWEENoperand
ANDoperand
|operand
IN (operand
(','operand
(, ...) )) | function |condition
ANDcondition
|condition
ORcondition
| NOTcondition
| (condition
) comparator ::= = | <> | < | <= | > | >= function ::= attribute_exists (path
) | attribute_not_exists (path
) | attribute_type (path
,type
) | begins_with (path
,substr
) | contains (path
,operand
) | size (path
)
Making comparisons
Use these comparators to compare an operand against a single value:
-
– True ifa
=b
a
is equal tob
. -
– True ifa
<>b
a
is not equal tob
. -
– True ifa
<b
a
is less thanb
. -
– True ifa
<=b
a
is less than or equal tob
. -
– True ifa
>b
a
is greater thanb
. -
– True ifa
>=b
a
is greater than or equal tob
.
Use the BETWEEN
and IN
keywords to compare an operand
against a range of values or an enumerated list of values:
-
– True ifa
BETWEENb
ANDc
a
is greater than or equal tob
, and less than or equal toc
. -
– True ifa
IN (b
,c
,d
)a
is equal to any value in the list—for example, any ofb
,c
, ord
. The list can contain up to 100 values, separated by commas.
Functions
Use the following functions to determine whether an attribute exists in an item, or to evaluate the value of an attribute. These function names are case sensitive. For a nested attribute, you must provide its full document path.
Function | Description |
---|---|
|
True if the item contains the attribute specified by
Example: Check whether an item in the
|
|
True if the attribute specified by Example: Check whether an item has a
|
|
True if the attribute at the specified path is of a particular
data type. The
You must use an expression attribute value for the
Example: Check whether the
You must use an expression attribute value for the
|
|
True if the attribute specified by Example: Check whether the first few characters of the front view
picture URL are
The expression attribute value |
|
True if the attribute specified by
If the attribute specified by The path and the operand must be distinct. That is, Example: Check whether the
The expression attribute value Example: Check whether the product is available in red.
The expression attribute value |
|
Returns a number that represents an attribute's size. The
following are valid data types for use with
If the attribute is of type Example: Check whether the string
If the attribute is of type Example: Suppose that the
If the attribute is a Example: Check whether the product is available in more than one
color. The expression attribute value
If the attribute is of type Example: Check whether the number of
|
Logical evaluations
Use the AND
, OR
, and NOT
keywords to perform
logical evaluations. In the following list, a
and
b
represent conditions to be evaluated.
-
– True ifa
ANDb
a
andb
are both true. -
– True if eithera
ORb
a
orb
(or both) are true. -
NOT
– True ifa
a
is false. False ifa
is true.
The following is a code example of AND in an operation.
dynamodb-local (*)> select * from exprtest where a > 3 and a <
5;
Parentheses
Use parentheses to change the precedence of a logical evaluation. For example, suppose
that conditions a
and b
are true,
and that condition c
is false. The following expression
evaluates to true:
-
a
ORb
ANDc
However, if you enclose a condition in parentheses, it is evaluated first. For example, the following evaluates to false:
-
(
a
ORb
) ANDc
Note
You can nest parentheses in an expression. The innermost ones are evaluated first.
The following is a code example with parentheses in a logical evaluation.
dynamodb-local (*)> select * from exprtest where attribute_type(b, string) or
( a = 5 and c = “coffee”);
Precedence in conditions
DynamoDB evaluates conditions from left to right using the following precedence rules:
-
= <> < <= > >=
-
IN
-
BETWEEN
-
attribute_exists attribute_not_exists begins_with contains
-
Parentheses
-
NOT
-
AND
-
OR