The condition that specifies the key value(s) for items to be retrieved by the Query
action.
The condition must perform an equality test on a single partition key value.
The condition can optionally perform one of several comparison tests on a single sort key value. This allows
Query
to retrieve one item with a given partition key value and sort key value, or several items
that have the same partition key value but different sort key values.
The partition key equality test is required, and must be specified in the following format:
partitionKeyName
= :partitionkeyval
If you also want to provide a condition for the sort key, it must be combined using AND
with the
condition for the sort key. Following is an example, using the = comparison operator for the sort key:
partitionKeyName
=
:partitionkeyval
AND
sortKeyName
=
:sortkeyval
Valid comparisons for the sort key condition are as follows:
-
sortKeyName
=
:sortkeyval
- true if the sort key value is equal to
:sortkeyval
.
-
sortKeyName
<
:sortkeyval
- true if the sort key value is less than
:sortkeyval
.
-
sortKeyName
<=
:sortkeyval
- true if the sort key value is less
than or equal to :sortkeyval
.
-
sortKeyName
>
:sortkeyval
- true if the sort key value is greater
than :sortkeyval
.
-
sortKeyName
>=
:sortkeyval
- true if the sort key value is greater
than or equal to :sortkeyval
.
-
sortKeyName
BETWEEN
:sortkeyval1
AND
:sortkeyval2
- true if the sort key value is greater than or equal to :sortkeyval1
,
and less than or equal to :sortkeyval2
.
-
begins_with (
sortKeyName
, :sortkeyval
)
- true if the
sort key value begins with a particular operand. (You cannot use this function with a sort key that is of
type Number.) Note that the function name begins_with
is case-sensitive.
Use the ExpressionAttributeValues
parameter to replace tokens such as :partitionval
and :sortval
with actual values at runtime.
You can optionally use the ExpressionAttributeNames
parameter to replace the names of the
partition key and sort key with placeholder tokens. This option might be necessary if an attribute name
conflicts with a DynamoDB reserved word. For example, the following KeyConditionExpression
parameter causes an error because Size is a reserved word:
To work around this, define a placeholder (such a #S
) to represent the attribute name
Size. KeyConditionExpression
then is as follows:
For a list of reserved words, see Reserved Words
in the Amazon DynamoDB Developer Guide.
For more information on ExpressionAttributeNames
and ExpressionAttributeValues
, see
Using
Placeholders for Attribute Names and Values in the Amazon DynamoDB Developer Guide.