DynamoDB BatchWriteItem en Node.js (AWS SDK v3)

BatchWriteItem inserta o elimina hasta 25 items en una sola solicitud (16 MB en total, 400 KB por item). En AWS SDK v3 envías un BatchWriteItemCommand cuyo RequestItems mezcla entradas PutRequest y DeleteRequest — y debes iterar sobre UnprocessedItems, porque el lote en su conjunto no es atómico.

Code

import {BatchWriteItemCommand, 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: [
    {
      PutRequest: {
        Item: {
          Artist: {S: 'Arturo Sandoval'},
          SongTitle: {S: 'Cubano Chant'},
          AlbumTitle: {S: 'Danzon'},
          Year: {N: '1994'}
        }
      }
    },
    {
      PutRequest: {
        Item: {
          Artist: {S: 'Arturo Sandoval'},
          SongTitle: {S: 'A Mis Abuelos'},
          AlbumTitle: {S: 'Danzon'},
          Year: {N: '1994'}
        }
      }
    },
    {
      DeleteRequest: {
        Key: {Artist: {S: 'Ella Fitzgerald'}, SongTitle: {S: 'Misty'}}
      }
    }
  ]
};

let attempt = 0;

do {
  const response = await client.send(new BatchWriteItemCommand({RequestItems: requestItems}));

  // Writes that were throttled come back in UnprocessedItems — resubmit them
  // with exponential backoff until the map is empty.
  requestItems = response.UnprocessedItems;
  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('Batch written');

Explicación

• RequestItems — un mapa de nombre de tabla → un array de hasta 25 entradas PutRequest/DeleteRequest (una sola solicitud puede abarcar varias tablas). Cada PutRequest.Item necesita la clave primaria completa; cada DeleteRequest.Key es solo la clave.
• No es una transacción — cada inserción/eliminación es atómica individualmente, pero el lote en su conjunto no lo es: algunas escrituras pueden tener éxito mientras otras son limitadas. ¿Necesitas todo o nada? Usa TransactWriteItems.
• UnprocessedItems — el bucle de reintento no es opcional. Las escrituras limitadas vuelven aquí en forma de RequestItems, listas para reenviar; AWS recomienda encarecidamente un retroceso exponencial entre intentos.
• Sin actualizaciones, sin condiciones — BatchWriteItem no puede expresar UpdateItem, ConditionExpression ni ReturnValues; una inserción sobre una clave existente reemplaza silenciosamente el item entero. Las claves duplicadas, mezclar inserción y eliminación sobre el mismo item, más de 25 solicitudes, un item de >400 KB, o más de 16 MB en total, cada uno hace que DynamoDB rechace el lote entero.
• Procesar por lotes ahorra viajes de ida y vuelta, no capacidad: cada inserción/eliminación factura las mismas WCU que facturaría individualmente (una eliminación sobre un item inexistente sigue facturando una WCU).

Hazlo visualmente

¿Prefieres no montar a mano los items en DynamoDB JSON? El DynamoDB Expression Builder construye mapas tipados de valores y copia código ejecutable, y la calculadora de tamaño de item comprueba cada item contra el límite de 400 KB antes de enviarlo.

Para añadir, editar y eliminar items en masa en una interfaz gráfica — sin bucles de reintento que escribir — descarga DynoTable.

Ejemplos relacionados

• Escritura por lotes en DynamoDB en Python — el batch_writer() de boto3 hace el bucle de reintento por ti.
• DynamoDB BatchWriteItem con la AWS CLI — la misma escritura por lotes desde el shell.
• DynamoDB TransactWriteItems en Node.js — cuando las escrituras deben tener éxito o fallar juntas.
• Operaciones por lotes en DynamoDB — límites, fallo parcial y cuándo compensa el procesamiento por lotes.
• "Too many items requested for the BatchWriteItem call" — más de 25 solicitudes de inserción/eliminación en un lote.
• "Provided list of item keys contains duplicates" — dos solicitudes que tocan la misma clave en un lote.

References

• BatchWriteItem — Amazon DynamoDB API Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide
• DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide

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