在 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 條件(=<<=>>=BETWEENbegins_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 Clientsoftware.amazon.awssdk.enhanced.dynamodb)以帶註解的 bean 類別提供相同的查詢。

改用視覺化操作

DynamoDB Expression Builder 會組裝 key condition 並複製可執行的程式碼,讓你不用手寫 placeholder 與 value map。

想在 GUI 中對實際表格執行查詢 — key-condition 表單、分頁格線、複製為程式碼 — 下載 DynoTable

相關範例

References

最後驗證於 2026-07-13,對照上方連結的 AWS 官方文件。

以視覺化方式建構此請求

在免費的 DynamoDB 查詢建構器中組合此操作 — 鍵條件、Filter、Index、Limit、排序方向與分頁迴圈 — 再把它複製成可執行的 SDK v3、CLI 或 boto3 程式。

開啟 DynamoDB 查詢建構器

不必透過主控台就能操作 DynamoDB

DynoTable 是一款快速的 DynamoDB 桌面用戶端 — 瀏覽表格、執行 SQL 風格的查詢,並在本機編輯項目。