在 Java(AWS SDK v2)中使用 DynamoDB Scan

Scan 逐頁讀取表格或索引中的每一個項目,然後可選擇以 FilterExpression 丟棄列。在 AWS SDK for Java 2.x 中,你建構一個 ScanRequest 並讓內建的 scanPaginator 追蹤 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.ScanRequest;
import software.amazon.awssdk.services.dynamodb.model.ScanResponse;

public class ScanExample {
    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("#filter0", "Year");

            Map<String, AttributeValue> values = new HashMap<>();
            values.put(":filterValue0", AttributeValue.builder().n("2010").build());

            ScanRequest request = ScanRequest.builder()
                    .tableName("Music")
                    .filterExpression("#filter0 >= :filterValue0")
                    .expressionAttributeNames(names)
                    .expressionAttributeValues(values)
                    .build();

            List<Map<String, AttributeValue>> items = new ArrayList<>();
            for (ScanResponse page : ddb.scanPaginator(request)) {
                items.addAll(page.items());
            }
            System.out.println("Matched " + items.size() + " items");
        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
        }
    }
}

說明

  • filterExpression — 在伺服器端於讀取之後套用。它縮小的是回應,而成本:無論是否過濾,你都要為每個被掃描的項目付費。
  • expressionAttributeNames — 被過濾的屬性以別名表示(#filter0Year),讓像 Year 這樣的保留字保持安全。
  • 分頁 — 每個 Scan 頁在過濾 之前 最多讀取 1 MB,因此當表格仍有符合項目時,一個過濾後的頁可能回傳空的。ddb.scanPaginator(request) 回傳一個 ScanIterable,會持續請求各頁直到 LastEvaluatedKey 耗盡 — 絕不要停在第一頁。
  • 加上 .limit(...) 可限制每頁掃描的項目數(過濾前)— 它不限制回傳的項目數。
  • 對大型的全表 scan,以 .segment(...) / .totalSegments(...) 把工作分散到各 worker(一個平行 scan)。
  • 偏好 Query Scan 讀取整個表格;除了極小的表格以外,它又慢又貴。

改用視覺化操作

手動組裝 filter?DynamoDB Expression Builder 會建立 FilterExpression 與 name/value map 並複製可執行的程式碼。

想在 GUI 中探索表格 — 具備過濾、分頁的結果格線與複製為程式碼 — 下載 DynoTable,別再從指令稿盲目地 scan。

相關範例

References

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

以視覺化方式建構此請求

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

開啟 DynamoDB 查詢建構器

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

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