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.