6.2: Filter Expressions

A filter expression is available for both Query and Scan operations, where you will be receiving multiple items back in a request. The key difference with a filter expression vs. a key condition expression is that a filter expression can be applied on any attribute in the table, not just those in the primary key.

Remember our customers data-set. The partition key is always "CUSTOMERS" and the sort key is "CUSTOMER#{phone_number}". If we want to filter on something like zipcode, we can't do it with key condition expression.


          import { QueryCommand } from "@aws-sdk/lib-dynamodb";
          import ddbDocClient from "@/lib/clients/dynamoDBClient";
          import { dbName } from "@/lib/constants";

          const dbCommand = new QueryCommand({
            TableName: dbName,
            KeyConditionExpression: "#pk_key = :pk_value",
            FilterExpression: "#zip_key = :zip_value",
            ExpressionAttributeNames: {
                "#pk_key": "pk",
                "#zip_key": "zipcode",
            },
            ExpressionAttributeValues: {
                ":pk_value": "CUSTOMERS",
                ":zip_value": "{parsedZipcode.output}",
            },
          });

          const dbResponse = await ddbDocClient.send(dbCommand);

Enter the zipcode and click the "Filter customers" button. All the customers with the zipcode will be fetched from your DynamoDB table.

You can add a new customer here.

Primary KeyAttributes
Partition key: pkSort key: skfirstNamelastNamephoneemailzipcodeshippingAddresses

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.

Challenges of Filter Expressions

When you issue a Query or Scan request to DynamoDB, DynamoDB performs the following actions in order:

1: It reads items matching your Query or Scan from the database using the Key Condition expression.

2: If a filter expression is present, it filters out items from the results that don’t match the filter expression.

3: It returns any remaining items to the client.

The key point to understand is that the Query and Scan operations will return a maximum of 1MB of data, and this limit is applied in step 1, before the filter expression is applied.

Filter expressions are useful for a few limited contexts:

1: Reducing response payload size.

2: Easier application filtering.

3: Better validation around time-to-live (TTL) expiry. When using DynamoDB TTL, AWS states that items are generally deleted within 48 hours of their TTL expiry. This is a wide range! If you’re counting on expiration as a part of your business logic, you could get incorrect results. To help guard against this, you could write a filter expression that removes all items that should have been expired by now, even if they’re not quite expired yet.