DynamoDB BatchGetItem en Node.js (AWS SDK v3)

BatchGetItem obtiene hasta 100 items por clave primaria en una sola solicitud (16 MB máximo). En AWS SDK v3 envías un BatchGetItemCommand con un mapa RequestItems de tabla → claves — y debes iterar sobre UnprocessedKeys, porque un lote puede legítimamente devolver solo una parte de lo que pediste.

Code

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

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

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let requestItems = {
  Music: {
    Keys: [
      {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'Cubano Chant'}},
      {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'A Mis Abuelos'}},
      {Artist: {S: 'Ella Fitzgerald'}, SongTitle: {S: 'Misty'}}
    ]
  }
};

const items = [];
let attempt = 0;

do {
  const response = await client.send(new BatchGetItemCommand({RequestItems: requestItems}));
  items.push(...(response.Responses?.Music ?? []));

  // A partial result is NOT an error: throttling, a >16 MB response, or an
  // internal failure returns the leftovers in UnprocessedKeys. Retry them
  // with exponential backoff.
  requestItems = response.UnprocessedKeys;
  if (requestItems && Object.keys(requestItems).length > 0) {
    attempt += 1;
    await sleep(Math.min(100 * 2 ** attempt, 5000));
  }
} while (requestItems && Object.keys(requestItems).length > 0);

console.log(`Fetched ${items.length} items`);

Explicación

RequestItems — un mapa de nombre de tabla → { Keys: [...] }; una sola solicitud puede abarcar varias tablas. Cada clave debe ser la clave primaria completa (partición + ordenación para una clave compuesta). Más de 100 claves, o la misma clave dos veces, falla con una ValidationException.
Responses — un mapa de nombre de tabla → los items encontrados. Los items vuelven sin ningún orden concreto, y las claves que no existen simplemente no aparecen — empareja los resultados con las solicitudes por sus atributos de clave.
UnprocessedKeys — el bucle de reintento anterior no es opcional. Si la respuesta supera los 16 MB, se agota el rendimiento o una lectura de partición supera 1 MB, DynamoDB devuelve el resto aquí en forma de RequestItems, listo para volver a introducirlo directamente. AWS recomienda encarecidamente un retroceso exponencial entre reintentos — un reintento inmediato tiende a chocar con la misma limitación.
Consistencia — las lecturas por lotes son con consistencia eventual por defecto; pon ConsistentRead: true por tabla para lecturas con consistencia fuerte.
Por tabla también puedes pasar ProjectionExpression (con ExpressionAttributeNames) para obtener solo algunos atributos.
BatchGetItem puede recuperar items en paralelo en el servidor — ahorra viajes de ida y vuelta, no capacidad de lectura: DynamoDB factura cada item del lote como un GetItem individual.

Hazlo visualmente

¿Prefieres no montar a mano los mapas de claves en DynamoDB JSON? El DynamoDB Expression Builder construye mapas tipados de clave/valor y copia código ejecutable, y la calculadora de tamaño de item muestra lo cerca que queda un lote del techo de 16 MB.

Para obtener e inspeccionar items entre tablas en una interfaz gráfica — sin bucles de reintento que escribir — descarga DynoTable.

Ejemplos relacionados

DynamoDB BatchGetItem en Python — la misma lectura por lotes con boto3.
DynamoDB BatchGetItem con la AWS CLI — la misma lectura por lotes desde el shell.
DynamoDB GetItem en Node.js — la lectura de un único item que esto agrupa por lotes.
Operaciones por lotes en DynamoDB — límites, fallo parcial y cuándo compensa el procesamiento por lotes.
"Too many items requested for the BatchGetItem call" — más de 100 claves en una sola solicitud.
"Provided list of item keys contains duplicates" — la misma clave dos veces en un lote.

References

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