How to Use FilterExpression in DynamoDB: Syntax and Examples

In DynamoDB, use FilterExpression to specify conditions that filter the results returned by Scan or Query operations after fetching items. It works with expression attribute names and values to safely reference attributes and values in your filter condition.

Syntax

The FilterExpression is a string that contains a condition to filter items returned by Scan or Query. It uses placeholders for attribute names and values to avoid conflicts with reserved words.

• FilterExpression: The condition to filter items, e.g., #status = :statusVal.
• ExpressionAttributeNames: A map of placeholders to actual attribute names, e.g., {"#status": "status"}.
• ExpressionAttributeValues: A map of placeholders to actual values, e.g., {":statusVal": {"S": "active"}}.

plaintext

FilterExpression = "#attr = :val"
ExpressionAttributeNames = {"#attr": "attributeName"}
ExpressionAttributeValues = {":val": {"S": "value"}}

Example

This example shows how to use FilterExpression in a DynamoDB Scan operation to return only items where the status attribute equals active.

python

import boto3

# Create DynamoDB client
client = boto3.client('dynamodb')

response = client.scan(
    TableName='YourTableName',
    FilterExpression='#st = :active',
    ExpressionAttributeNames={
        '#st': 'status'
    },
    ExpressionAttributeValues={
        ':active': {'S': 'active'}
    }
)

items = response.get('Items', [])
print('Filtered items:', items)

Output

Filtered items: [
  {"id": {"S": "123"}, "status": {"S": "active"}},
  {"id": {"S": "456"}, "status": {"S": "active"}}
]

Common Pitfalls

• Not using ExpressionAttributeNames when attribute names are reserved words or contain special characters causes errors.
• Forgetting to use placeholders in FilterExpression leads to syntax errors.
• Expecting FilterExpression to reduce read capacity units: it filters results after reading all matching items, so it does not reduce cost.

plaintext

Wrong:
FilterExpression = "status = 'active'"

Right:
FilterExpression = "#st = :active"
ExpressionAttributeNames = {"#st": "status"}
ExpressionAttributeValues = {":active": {"S": "active"}}

Quick Reference

Term	Description	Example
FilterExpression	Condition to filter returned items	#status = :val
ExpressionAttributeNames	Map placeholders to attribute names	{"#status": "status"}
ExpressionAttributeValues	Map placeholders to values	{":val": {"S": "active"}}
Usage	Used in Scan or Query to filter results after fetching	client.scan(FilterExpression=..., ...)

Key Takeaways

Use FilterExpression to filter items returned by Scan or Query operations in DynamoDB.

Always use ExpressionAttributeNames and ExpressionAttributeValues to safely reference attributes and values.

FilterExpression filters results after reading items, so it does not reduce read capacity usage.

Avoid using reserved words directly in FilterExpression by using placeholders.

Test your FilterExpression syntax carefully to avoid runtime errors.