GetItem do DynamoDB em Java (AWS SDK v2)

O AWS SDK for Java 2.x modela um item como um Map<String, AttributeValue> montado através de builders imutáveis. Duas de suas convenções diferem da maioria dos outros SDKs: números são tipados como strings, e coleções de resposta nunca são nulas.

A requisição em si precisa da chave primária completa, como em qualquer outro lugar.

Código

import java.util.HashMap;
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.GetItemRequest;

public class GetItemExample {
    public static void main(String[] args) {
        try (DynamoDbClient ddb = DynamoDbClient.builder()
                .region(Region.US_EAST_1)
                .build()) {

            Map<String, AttributeValue> key = new HashMap<>();
            key.put("Artist", AttributeValue.builder().s("Arturo Sandoval").build());
            key.put("SongTitle", AttributeValue.builder().s("Cubano Chant").build());

            Map<String, String> names = new HashMap<>();
            names.put("#proj0", "Artist");
            names.put("#proj1", "SongTitle");
            names.put("#proj2", "AlbumTitle");
            names.put("#proj3", "Year");

            GetItemRequest request = GetItemRequest.builder()
                    .tableName("Music")
                    .key(key)
                    .projectionExpression("#proj0, #proj1, #proj2, #proj3")
                    .expressionAttributeNames(names)
                    .build();

            Map<String, AttributeValue> item = ddb.getItem(request).item();
            if (item.isEmpty()) {
                System.out.println("Item not found");
            } else {
                System.out.println(item);
            }
        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
        }
    }
}

Explicação

n() recebe uma String — AttributeValue.builder().n(1994) não compila. O Javadoc dá o motivo: "Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries." Então é n("1994"), e o parse na volta é responsabilidade sua.
item() nunca retorna null — uma busca sem resultado produz um mapa vazio, então isEmpty() é o teste. Para separar "o serviço não retornou nada" de "o serviço retornou um mapa vazio", chame hasItem(); o SDK constrói coleções vazias automaticamente e hasItem() é a única coisa que enxerga através disso.
O mapa que ele devolve é imutável — o Javadoc é explícito: modificá-lo lança UnsupportedOperationException. Copie para um HashMap primeiro se você pretende editar.
Nada valida o mapa de aliases localmente — expressionAttributeNames é um Map<String, String> comum. #proj3 é obrigatório aqui porque Year é uma palavra reservada, e um alias que você declara mas nunca referencia é um erro próprio no lado do serviço: "Value provided in ExpressionAttributeNames unused in expressions".
Um cliente para a aplicação inteira — a AWS afirma isso claramente: "Service clients in the AWS SDK for Java 2.x are thread-safe." O bloco try-with-resources serve para um main de uma única execução; em um serviço de longa duração, construa o cliente na inicialização e nunca o feche a cada requisição.
.consistentRead(true) dobra o custo de leitura e é rejeitado em um GSI. Se os mapas de AttributeValue ficarem cansativos, o DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) mapeia itens para beans anotados por cima dessas mesmas chamadas de baixo nível.

Faça isso visualmente

Se esta leitura cobra 0,5 ou 1 unidade de capacidade depende de o item caber ou não dentro de 4 KB. A calculadora de tamanho de item mede um item colado contra esse limite.

O DynoTable mostra os mesmos itens como linhas comuns, e exporta a consulta por trás da grade como um programa Java construído a partir desses builders. Baixe o DynoTable.

Exemplos relacionados

GetItem do DynamoDB em Go — a mesma leitura com o AWS SDK for Go v2.
Query do DynamoDB em Java — leia uma partição inteira em vez de um único item.
Como funcionam as chaves de partição do DynamoDB — por que o GetItem precisa da chave completa.
DynamoDB ResourceNotFoundException — o primeiro erro habitual aqui: nome de tabela ou região errados.
"The provided key element does not match the schema" — a chave que você passa não corresponde ao schema de chave da tabela.

Referências

Verificado pela última vez em 2026-07-28 contra a documentação oficial da AWS vinculada acima.