Filter expressions for the Query operation in DynamoDB
If you need to further refine the Query
results, you can optionally
provide a filter expression. A filter expression determines which
items within the Query
results should be returned to you. All of the other
results are discarded.
A filter expression is applied after a Query
finishes, but before the
results are returned. Therefore, a Query
consumes the same amount of read
capacity, regardless of whether a filter expression is present.
A Query
operation can retrieve a maximum of 1 MB of data.
This limit applies before the filter expression is evaluated.
A filter expression cannot contain partition key or sort key attributes. You need to specify those attributes in the key condition expression, not the filter expression.
The syntax for a filter expression is similar to that of a key condition expression.
Filter expressions can use the same comparators, functions, and logical operators as a
key condition expression. In addition, filter expressions can use the not-equals
operator (<>
), the OR
operator, the
CONTAINS
operator, the IN
operator, the
BEGINS_WITH
operator, the BETWEEN
operator, the
EXISTS
operator, and the SIZE
operator. For more
information, see Key condition expressions for the Query
operation in DynamoDB and Syntax for filter and
condition expressions.
Example
The following AWS CLI example queries the Thread
table for a particular
ForumName
(partition key) and Subject
(sort key). Of
the items that are found, only the most popular discussion threads are
returned—in other words, only those threads with more than a certain number of
Views
.
aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :fn and Subject = :sub" \ --filter-expression "#v >= :num" \ --expression-attribute-names '{"#v": "Views"}' \ --expression-attribute-values file://values.json
The arguments for --expression-attribute-values
are stored in the
values.json
file.
{ ":fn":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"}, ":num":{"N":"3"} }
Note that Views
is a reserved word in DynamoDB (see Reserved words in DynamoDB), so this example uses
#v
as a placeholder. For more information, see Expression attribute names (aliases)
in DynamoDB.
Note
A filter expression removes items from the Query
result set. If
possible, avoid using Query
where you expect to retrieve a large number
of items but also need to discard most of those items.