DynamoDB Scan em Java (AWS SDK v2)

Scan lê todos os itens de uma tabela ou índice, página por página, e então opcionalmente descarta linhas com uma FilterExpression. No AWS SDK for Java 2.x você constrói um ScanRequest e deixa o scanPaginator embutido seguir o LastEvaluatedKey até a tabela inteira ser lida.

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());
        }
    }
}

Explicação

filterExpression — aplicada depois da leitura, no servidor. Ela encolhe a resposta mas não o custo: você paga para ler cada item varrido, filtrado ou não.
expressionAttributeNames — o atributo filtrado recebe um alias (#filter0 → Year), o que mantém palavras reservadas como Year seguras.
Paginação — cada página do Scan lê no máximo 1 MB antes de filtrar, então uma página filtrada pode voltar vazia enquanto a tabela ainda tem correspondências. ddb.scanPaginator(request) retorna um ScanIterable que continua requisitando páginas até o LastEvaluatedKey se esgotar — nunca pare na primeira página.
Adicione .limit(...) para limitar itens varridos por página (pré-filtro) — ele não limita os itens retornados.
Para um scan grande de tabela inteira, divida o trabalho entre workers com .segment(...) / .totalSegments(...) (um parallel scan).
Prefira Query. Scan lê a tabela inteira; em qualquer coisa que não seja uma tabela minúscula, é lento e caro.

Faça visualmente

Montando um filtro na mão? O DynamoDB Expression Builder constrói a FilterExpression + mapas de nome/valor e copia código executável.

Para explorar tabelas numa GUI — com grades de resultados filtradas e paginadas e copiar como código — baixe o DynoTable, em vez de fazer scan às cegas a partir de um script.

Exemplos relacionados

DynamoDB Scan em Go — o mesmo scan com o AWS SDK for Go v2.
DynamoDB Query em Java — a leitura mais barata que você geralmente deveria usar.
Query vs. Scan — quando (raramente) um Scan se justifica.
Por que meu DynamoDB Scan é lento e caro? — o modelo de custo e como evitá-lo.
DynamoDB ProvisionedThroughputExceededException — o que um scan de tabela inteira faz à capacidade de uma tabela provisionada.
DynamoDB ThrottlingException — o outro throttle, e como o backoff exponencial lida com ele.

References

Última verificação em 2026-07-13 contra a documentação oficial da AWS vinculada acima.