DynamoDB GetItem em Node.js (AWS SDK v3)

O AWS SDK v3 te dá dois jeitos de ler um item: GetItemCommand em um DynamoDBClient, que fala o formato do protocolo ({S: '...'}), ou GetCommand em um DynamoDBDocumentClient, que aceita e devolve JavaScript puro.

O exemplo usa o client de baixo nível. Esses invólucros são a cara real da codificação de attribute values no protocolo, e o que as mensagens de erro citam de volta para você. De qualquer forma, a requisição precisa da chave primária completa.

Código

import {DynamoDBClient, GetItemCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const command = new GetItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  ProjectionExpression: '#proj0, #proj1, #proj2, #proj3',
  ExpressionAttributeNames: {
    '#proj0': 'Artist',
    '#proj1': 'SongTitle',
    '#proj2': 'AlbumTitle',
    '#proj3': 'Year'
  }
});

const response = await client.send(command);

if (!response.Item) {
  console.log('Item not found');
} else {
  console.log(response.Item);
}

Explicação

send(command), não client.getItem() — DynamoDBClient expõe apenas send. A classe agregada DynamoDB do mesmo pacote tem sim um método getItem se você quiser chamadas no estilo do SDK v2, ao preço de puxar todos os comandos para dentro do seu bundle.
Um item não encontrado é undefined, não um erro — response.Item simplesmente não existe, e a chamada é resolvida mesmo assim. response.$metadata sempre chega, então a veracidade da própria resposta não te diz nada.
unmarshall escolhe o tipo numérico pela magnitude — um {N: …} dentro da faixa de inteiros seguros volta como number, qualquer coisa fora dela como BigInt, e um não inteiro grande lança can't be converted to BigInt. Passe {wrapNumbers: true} para o unmarshall do @aws-sdk/util-dynamodb e todo número chega como NumberValue, deixando a conversão por sua conta.
Os aliases #proj são estruturais — Year está na lista de palavras reservadas da AWS, então uma ProjectionExpression que o nomeia diretamente é rejeitada. Criar alias para todo nome, como acima, é o padrão seguro. Isso enxuga a resposta, não o custo da leitura (por quê).
ConsumedCapacity é opcional — adicione ReturnConsumedCapacity: 'TOTAL' e a resposta informa quanto esta leitura custou de fato: 0,5 unidade de capacidade para uma leitura com consistência eventual de um item abaixo de 4 KB, 1,0 assim que você adiciona ConsistentRead: true (a contrapartida).
Eleve o client — construa o DynamoDBClient uma única vez no escopo do módulo. Criar um por requisição, ou dentro de um handler Lambda, joga fora o pool de conexões e as credenciais resolvidas a cada chamada.

Faça isso visualmente

O DynoTable mostra itens como linhas comuns em vez de mapas de attribute values, e exporta a consulta por trás da grade como um programa executável do SDK v3. Baixe o DynoTable.

Guias relacionados

Query vs. Scan — quando um único GetItem ganha de uma Query.
Como funcionam as chaves de partição do DynamoDB — por que o GetItem precisa da chave completa.
DynamoDB ResourceNotFoundException — o primeiro erro de sempre 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.