Java(AWS SDK v2)中的 DynamoDB Query
Query 读取共享同一个分区键的每个项目,并可选地按排序键收窄。在 AWS SDK for Java 2.x 中,你用一个 keyConditionExpression 构建 QueryRequest,内置的 queryPaginator 会替你跨每个结果页跟随 LastEvaluatedKey。
Code
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.QueryRequest;
import software.amazon.awssdk.services.dynamodb.model.QueryResponse;
public class QueryExample {
public static void main(String[] args) {
try (DynamoDbClient ddb = DynamoDbClient.builder()
.region(Region.US_EAST_1)
.build()) {
Map<String, String> names = new HashMap<>();
names.put("#hashKey", "Artist");
names.put("#rangeKey", "SongTitle");
Map<String, AttributeValue> values = new HashMap<>();
values.put(":hashKeyValue", AttributeValue.builder().s("Arturo Sandoval").build());
values.put(":rangeKeyValue", AttributeValue.builder().s("C").build());
QueryRequest request = QueryRequest.builder()
.tableName("Music")
.keyConditionExpression(
"#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)")
.expressionAttributeNames(names)
.expressionAttributeValues(values)
.build();
List<Map<String, AttributeValue>> items = new ArrayList<>();
for (QueryResponse page : ddb.queryPaginator(request)) {
items.addAll(page.items());
}
System.out.println("Found " + items.size() + " items");
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
}
}
}说明
keyConditionExpression— 必须包含分区键上的相等条件(#hashKey = :hashKeyValue),外加至多一个排序键条件(=、<、<=、>、>=、BETWEEN或begins_with)。#hashKey/#rangeKey别名通过expressionAttributeNames解析为Artist/SongTitle(保留字安全)。expressionAttributeValues—:placeholder→ 带类型AttributeValue映射。- 分页 — 单次
Query最多返回 1 MB。ddb.queryPaginator(request)返回一个QueryIterable,随着你迭代各页而惰性发起后续请求;每个QueryResponse页携带一个items()列表。(想手动做?把lastEvaluatedKey()作为.exclusiveStartKey(...)送回,直到它为空。) - 加上
.scanIndexForward(false)可反转排序键顺序(升序是默认值)。 - 通过添加
.indexName("...")来查询二级索引。 - 更想用普通 Java 对象?DynamoDB Enhanced Client(
software.amazon.awssdk.enhanced.dynamodb)用带注解的 bean 类暴露同样的查询。
可视化操作
DynamoDB Expression Builder 会组装键条件并复制可运行代码,让你无需手写占位符和值映射。
想在 GUI 中针对真实表运行查询——键条件表单、分页网格、复制为代码——请下载 DynoTable。
相关示例
- Go 中的 DynamoDB Query — 用 AWS SDK for Go v2 完成同样的查询。
- Java 中的 DynamoDB Scan — 当你无法按键落入某个分区时。
- Query vs. Scan — 为什么
Query是正确的默认选择。 - 键条件表达式 — 每个合法的分区/排序键运算符。
- "Query condition missed key schema element" — 键条件命名了错误的属性或跳过了分区键。
- "Query key condition not supported" — 键条件无法使用的运算符,例如 contains 或第二个排序键条件。
References
- Query — Amazon DynamoDB API Reference
- Use Query with an AWS SDK or CLI — Amazon DynamoDB Developer Guide
- DynamoDbClient — AWS SDK for Java 2.x API Reference
- QueryRequest — AWS SDK for Java 2.x API Reference
- Querying tables — Amazon DynamoDB Developer Guide
Last verified 2026-07-13 against the official AWS documentation linked above.