Filter expressions for the Query operation in DynamoDB (original) (raw)

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, theCONTAINS operator, the IN operator, theBEGINS_WITH operator, the BETWEEN operator, theEXISTS 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 particularForumName (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 ofViews.

aws dynamodb query \
    --table-name Thread \
    --key-condition-expression "ForumName = :fn and Subject begins_with :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 thevalues.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.