DynamoDB的Query操作提供了两个容易混淆的条件参数：KeyConditionExpression负责筛选分区键和排序键，FilterExpression负责在结果集上做二次过滤。很多刚接触DynamoDB的开发者会把FilterExpression当成SQL里的WHERE子句来理解，以为加上过滤条件就能减少扫描的数据量，实际上它的执行时机和计费方式都和直觉不一样。本文围绕FilterExpression的用法、原理和常见坑点展开，帮助你写出正确又省钱的查询代码。
FilterExpression的执行原理：为什么它不省容量单位
FilterExpression在DynamoDB内部的执行顺序是这样的：先根据KeyConditionExpression定位到分区，读取该分区内符合条件的所有数据项，然后才对读取到的结果应用FilterExpression，把不满足条件的项丢弃。也就是说，过滤发生在读取之后，而不是读取之前。这意味着无论你的过滤条件多么严格，DynamoDB计费的读取容量单位（RCU）都是按过滤前的数据量来计算的。
举个具体例子，假设某个分区下有1000条数据，你用FilterExpression过滤后只返回10条，但DynamoDB实际读取了1000条数据并按1000条计费。这就是为什么官方文档反复强调FilterExpression不是用来减少成本的手段，它只是减少返回给客户端的数据量，降低网络传输和客户端处理负担。
另外要注意Query默认每次最多返回1MB的数据。这个1MB的限制同样是在应用FilterExpression之前统计的。如果你的分区下符合键条件的数据超过1MB，即使过滤后只剩几条记录，也需要分页继续读取，可能会消耗多次请求。用Limit参数时尤其要小心，Limit限制的是应用过滤表达式之前评估的项目数量，如果设置Limit=10而前10条都被过滤掉了，你会得到空结果和LastEvaluatedKey，必须继续翻页才能拿到真实数据。
FilterExpression与KeyConditionExpression的区别及语法要点
KeyConditionExpression只能作用于分区键和排序键，支持的条件有限：分区键只能用等值判断，排序键支持等值、范围比较、begins_with等。而FilterExpression可以作用于任何非键属性，支持比较运算符（=、<>、<、>、<=、>=）、逻辑运算符（AND、OR、NOT）以及一些函数和操作符，比如attribute_exists、attribute_not_exists、contains、begins_with、size、IN等。
写FilterExpression时强烈建议使用表达式占位符，也就是用#name表示属性名、:value表示属性值，然后通过ExpressionAttributeNames和ExpressionAttributeValues传入实际的名称和值。这样既能避免属性名与DynamoDB保留字冲突，又能防止特殊字符带来的解析问题。下面是一个Python的完整示例：
import boto3
dynamodb = boto3.resource('dynamodb')
table = dynamodb.Table('Orders')
response = table.query(
KeyConditionExpression='#pk = :pk',
FilterExpression='#status = :status AND #amount > :min_amount',
ExpressionAttributeNames={
'#pk': 'user_id',
'#status': 'order_status',
'#amount': 'amount'
},
ExpressionAttributeValues={
':pk': 'user_10086',
':status': 'PAID',
':min_amount': 500
}
)
for item in response['Items']:
print(item['order_id'], item['amount'])
这个例子里order_status、amount等属性名都用了占位符。如果不这样做，而直接写成FilterExpression='order_status = :status'，虽然大部分情况能跑通，但一旦属性名撞上保留字（比如status、size、timestamp都是保留字）就会报错。养成占位符习惯可以彻底规避这类问题。
属性不存在、嵌套文档与集合的过滤技巧
FilterExpression在处理不存在的属性时有一个非常容易踩的坑：如果某个数据项根本没有某个属性，直接用attribute = :value这样的比较表达式会导致整个表达式评估失败，该项会被排除在结果之外。大多数情况下这可能符合预期，但如果你想反过来筛选出属性缺失的记录，就要用attribute_not_exists操作符。例如筛选没有设置邮箱的用户：
response = table.query(
KeyConditionExpression='#pk = :pk',
FilterExpression='attribute_not_exists(#email)',
ExpressionAttributeNames={
'#pk': 'user_id',
'#email': 'email'
},
ExpressionAttributeValues={
':pk': 'user_10086'
}
)
对于嵌套文档结构，FilterExpression支持文档路径写法，用点号逐层访问。比如数据里有一个address对象，想按城市过滤，可以写成#addr.#city = :city，其中#addr映射为address，#city映射为city。注意路径的每一级如果可能与保留字冲突，都要单独定义占位符。
集合类型的过滤也有对应的操作符。判断列表中是否包含某个元素用contains，判断某个值是否在一组候选值里用IN，判断字符串、列表或二进制数据的长度用size。比如过滤标签包含hot的记录：contains(#tags, :tag)；过滤名字长度超过10的记录：size(#name) > :len。需要注意的是IN操作符的值列表是通过:vals传一个列表类型的值实现的，而不是在表达式里直接写逗号分隔的字面量。
PHP SDK中的写法与分页注意事项
用PHP调用DynamoDB时，FilterExpression的写法思路完全一致，只是参数组织方式换成PHP数组。下面是一个AWS SDK for PHP的示例，包含分页处理逻辑：
<?php
require 'vendor/autoload.php';
use Aws\DynamoDb\DynamoDbClient;
$client = new DynamoDbClient([
'region' => 'ap-northeast-1',
'version' => '2012-08-10'
]);
$params = [
'TableName' => 'Orders',
'KeyConditionExpression' => '#pk = :pk',
'FilterExpression' => '#status = :status',
'ExpressionAttributeNames' => [
'#pk' => 'user_id',
'#status' => 'order_status'
],
'ExpressionAttributeValues' => [
':pk' => ['S' => 'user_10086'],
':status' => ['S' => 'PAID']
]
];
$result = $client->query($params);
foreach ($result['Items'] as $item) {
echo $item['order_id']['S'] . PHP_EOL;
}
分页时要检查返回结果里有没有LastEvaluatedKey，有则把它作为下次请求的ExclusiveStartKey继续查询，直到为空。特别提醒，由于FilterExpression会先读后滤，翻页过程中可能会遇到连续多页都被过滤干净的情况，代码逻辑上必须以LastEvaluatedKey为循环终止条件，而不是以当前页是否有数据为条件，否则会漏掉后面页的真实数据。
什么时候该放弃FilterExpression改用二级索引
如果过滤后的结果占原始数据比例很低，说明你把大量RCU浪费在被丢弃的数据上。这种场景下应该重新审视数据建模，考虑创建全局二级索引（GSI）或本地二级索引（LSI），把常用的过滤属性提升为索引的排序键，让KeyConditionExpression直接在索引上完成筛选。例如订单表经常按状态查询，就可以建一个以状态为排序键的GSI，用键条件代替过滤表达式，读取成本会大幅下降。
总结几条实践建议：过滤后保留比例高（比如超过一半）时用FilterExpression没问题；保留比例低时优先设计索引；永远使用占位符写表达式；分页逻辑以LastEvaluatedKey为准；不要指望FilterExpression节省容量消耗。掌握这些原则，Query加FilterExpression的组合就能既正确又经济地服务于业务查询。
DynamoDBFilterExpressionQuery修改时间：2026-09-15 08:22:34