DynamoDB GetItem en Node.js (AWS SDK v3)

AWS SDK v3 te da dos formas de leer un elemento: GetItemCommand sobre un DynamoDBClient, que habla el formato de red ({S: '...'}), o GetCommand sobre un DynamoDBDocumentClient, que acepta y devuelve JavaScript plano.

El ejemplo usa el cliente de bajo nivel. Esos envoltorios son el aspecto real de la codificación de valores de atributo en la red, y lo que los mensajes de error te citan de vuelta. En cualquiera de los dos casos la petición necesita la clave principal 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);
}

Explicación

send(command), no client.getItem() — DynamoDBClient solo expone send. La clase agregada DynamoDB del mismo paquete sí tiene un método getItem si quieres llamadas al estilo del SDK v2, al precio de arrastrar todos los comandos a tu bundle.
Un fallo es undefined, no un error — response.Item simplemente no está, y la llamada se resuelve igual. response.$metadata llega siempre, así que la veracidad de la respuesta en sí no te dice nada.
unmarshall elige el tipo numérico según la magnitud — un {N: …} dentro del rango de enteros seguros vuelve como number, cualquier cosa fuera de él como BigInt, y un no entero grande lanza can't be converted to BigInt. Pasa {wrapNumbers: true} a unmarshall de @aws-sdk/util-dynamodb y cada número llega como un NumberValue, de modo que la conversión la decides tú.
Los alias #proj son imprescindibles — Year está en la lista de palabras reservadas de AWS, así que una ProjectionExpression que lo nombre directamente es rechazada. Poner alias a todos los nombres, como arriba, es lo seguro por defecto. Recorta la respuesta, no el coste de la lectura (por qué).
ConsumedCapacity es opcional — añade ReturnConsumedCapacity: 'TOTAL' y la respuesta informa de lo que realmente costó esta lectura: 0,5 unidades de capacidad para una lectura eventualmente consistente de un elemento de menos de 4 KB, 1,0 en cuanto añades ConsistentRead: true (el compromiso).
Saca el cliente fuera — construye DynamoDBClient una sola vez a nivel de módulo. Crear uno por petición, o dentro de un handler de Lambda, tira a la basura el pool de conexiones y las credenciales resueltas en cada llamada.

Hazlo visualmente

DynoTable muestra los elementos como filas normales en lugar de mapas de valores de atributo, y exporta la consulta que hay detrás de la cuadrícula como un programa ejecutable del SDK v3. Descarga DynoTable.

Guías relacionadas

Query frente a Scan — cuándo un solo GetItem gana a un Query.
Cómo funcionan las claves de partición de DynamoDB — por qué GetItem necesita la clave completa.
DynamoDB ResourceNotFoundException — el primer error habitual aquí: nombre de tabla o región equivocados.
"The provided key element does not match the schema" — la clave que pasas no coincide con el esquema de clave de la tabla.

Referencias

Verificado por última vez el 2026-07-28 contra la documentación oficial de AWS enlazada arriba.