DynamoDB GetItem em Java (AWS SDK v2)

GetItem lê um único item pela sua chave primária completa. No AWS SDK for Java 2.x você constrói um GetItemRequest e chama getItem em um DynamoDbClient; cada valor de chave é um AttributeValue construído com o builder tipado (.s(...) para strings, .n(...) para números).

Code

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

Prefere objetos Java simples em vez de mapas de AttributeValue? O DynamoDB Enhanced Client (software.amazon.awssdk.enhanced.dynamodb) mapeia itens para classes bean anotadas sobre as mesmas chamadas de baixo nível.

Explicação

tableName — a tabela de onde ler.
key — deve incluir todos os atributos da chave primária: apenas a chave de partição para uma chave simples, ou chave de partição e chave de classificação para uma chave composta. GetItem não aceita uma chave parcial.
projectionExpression — opcional; limita quais atributos retornam (economiza banda, não o custo de leitura). Cada atributo projetado recebe um alias (#proj0…#proj3) via expressionAttributeNames, o que mantém palavras reservadas como Year seguras.
item() — quando nenhum item corresponde, a resposta carrega um mapa vazio (nunca null); verifique isEmpty() antes de usá-lo.
Por padrão as leituras têm consistência eventual. Adicione .consistentRead(true) para uma leitura com consistência forte (custa 2× as RCU, apenas na tabela base).
O client é AutoCloseable — o bloco try-with-resources libera suas conexões HTTP.

Faça visualmente

Montando a projeção ou uma leitura condicional na mão? Use o DynamoDB Expression Builder gratuito para montar a expressão e copiar os valores exatos de ProjectionExpression / ExpressionAttributeNames.

Para navegar em tabelas e executar GetItem numa GUI — formulário de chave, grade de resultados, cópia em um clique do código gerado — baixe o DynoTable.

Exemplos relacionados

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

References

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