在 Java(AWS SDK v2)中使用 DynamoDB Query
Query 讀取共用同一個 partition key 的每一個項目,並可選擇以 sort key 縮小範圍。在 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— 必須包含對 partition key 的相等條件(#hashKey = :hashKeyValue),加上至多一個 sort-key 條件(=、<、<=、>、>=、BETWEEN或begins_with)。#hashKey/#rangeKey別名透過expressionAttributeNames解析為Artist/SongTitle(保留字安全)。expressionAttributeValues—:placeholder→ 帶型別AttributeValue的 map。- 分頁 — 單次
Query最多回傳 1 MB。ddb.queryPaginator(request)回傳一個QueryIterable,會在你迭代各頁時延遲地發出後續請求;每個QueryResponse頁都帶有一個items()list。(要自己手動處理?把lastEvaluatedKey()餵回作為.exclusiveStartKey(...),直到它為空。) - 加上
.scanIndexForward(false)可反轉 sort-key 順序(預設為遞增)。 - 加上
.indexName("...")可查詢 secondary index。 - 偏好單純的 Java 物件?DynamoDB Enhanced Client(
software.amazon.awssdk.enhanced.dynamodb)以帶註解的 bean 類別提供相同的查詢。
改用視覺化操作
DynamoDB Expression Builder 會組裝 key condition 並複製可執行的程式碼,讓你不用手寫 placeholder 與 value map。
想在 GUI 中對實際表格執行查詢 — key-condition 表單、分頁格線、複製為程式碼 — 下載 DynoTable。
相關範例
- 在 Go 中使用 DynamoDB Query — 以 AWS SDK for Go v2 執行相同的查詢。
- 在 Java 中使用 DynamoDB Scan — 當你無法以 key 切入某個 partition 時。
- Query vs. Scan — 為什麼
Query是正確的預設。 - Key condition 運算式 — 每個合法的 partition/sort-key 運算子。
- "Query condition missed key schema element" — key condition 指名了錯誤的屬性,或略過了 partition key。
- "Query key condition not supported" — key condition 無法使用的運算子,例如 contains 或第二個 sort-key 條件。
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
最後驗證於 2026-07-13,對照上方連結的 AWS 官方文件。