DynamoDB Query em Java (AWS SDK v2)

Query lê todos os itens que compartilham uma chave de partição, opcionalmente restringindo pela chave de classificação. No AWS SDK for Java 2.x você constrói um QueryRequest com uma keyConditionExpression, e o queryPaginator embutido segue o LastEvaluatedKey por todas as páginas de resultados por você.

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

Explicação

keyConditionExpression — deve incluir uma igualdade na chave de partição (#hashKey = :hashKeyValue) mais no máximo uma condição de chave de classificação (=, <, <=, >, >=, BETWEEN ou begins_with). Os aliases #hashKey/#rangeKey resolvem para Artist/SongTitle via expressionAttributeNames (seguro contra palavras reservadas).
expressionAttributeValues — o mapa :placeholder → AttributeValue tipado.
Paginação — um Query retorna no máximo 1 MB. ddb.queryPaginator(request) retorna um QueryIterable que emite requisições subsequentes de forma preguiçosa enquanto você itera as páginas; cada página QueryResponse carrega uma lista items(). (Fazendo na mão? Alimente lastEvaluatedKey() de volta como .exclusiveStartKey(...) até ele ficar vazio.)
Adicione .scanIndexForward(false) para inverter a ordem da chave de classificação (crescente é o padrão).
Consulte um índice secundário adicionando .indexName("...").
Prefere objetos Java simples? O DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) expõe a mesma query com classes bean anotadas.

Faça visualmente

O DynamoDB Expression Builder monta a key condition e copia código executável, para que você não escreva à mão os mapas de placeholder e valor.

Para executar queries contra tabelas reais numa GUI — formulário de key-condition, grade paginada, copiar como código — baixe o DynoTable.

Exemplos relacionados

DynamoDB Query em Go — a mesma query com o AWS SDK for Go v2.
DynamoDB Scan em Java — quando você não consegue entrar em uma partição pela chave.
Query vs. Scan — por que Query é o padrão certo.
Key condition expressions — todos os operadores válidos de chave de partição/classificação.
"Query condition missed key schema element" — a key condition nomeia o atributo errado ou pula a chave de partição.
"Query key condition not supported" — um operador que a key condition não pode usar, como contains ou uma segunda condição de chave de classificação.

References

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