DynamoDB BatchWriteItem con la AWS CLI

aws dynamodb batch-write-item inserta o elimina hasta 25 items en un solo comando (16 MB en total, 400 KB por item). Las escrituras van en --request-items como un mapa de tabla → entradas PutRequest/DeleteRequest en DynamoDB JSON — y debes comprobar UnprocessedItems en la salida, porque el lote en su conjunto no es atómico.

Code

aws dynamodb batch-write-item \
  --request-items '{
    "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"}}}}
    ]
  }'

Cuando todo se aplica, el mapa de pendientes de la salida está vacío:

{
    "UnprocessedItems": {}
}

Explicación

• --request-items — un mapa de nombre de tabla → un array de hasta 25 entradas PutRequest/DeleteRequest (un solo comando puede abarcar varias tablas). Cada PutRequest.Item necesita la clave primaria completa; cada DeleteRequest.Key es solo la clave. Los valores son DynamoDB JSON — los números son cadenas bajo N.
• No es una transacción — cada inserción/eliminación es atómica individualmente, pero el lote en su conjunto no lo es. ¿Necesitas todo o nada? Usa transact-write-items.
• UnprocessedItems — la CLI no reintenta automáticamente un lote parcial. Si el mapa no está vacío (la limitación (throttling) es la causa habitual), vuelve a ejecutar el comando con ese mapa exacto como --request-items — ya está en la forma correcta — aplicando un retroceso (backoff) entre intentos.
• Sin actualizaciones, sin condiciones — batch-write-item no puede expresar update-item, --condition-expression ni --return-values; una inserción sobre una clave existente reemplaza silenciosamente el item entero. Las claves duplicadas, una 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.
• Consejo: guarda el mapa en un archivo y pásalo con --request-items file://writes.json — poner entre comillas del shell 25 items en línea es una tortura.

Hazlo visualmente

Escribir a mano DynamoDB JSON anidado entre comillas del shell es propenso a errores. El DynamoDB Expression Builder construye mapas tipados de valores y copia comandos de CLI listos para ejecutar, y la calculadora de tamaño de item comprueba cada item contra el límite de 400 KB.

Para añadir, editar y eliminar items en masa en una interfaz gráfica — importación CSV/JSON en lugar de escapar JSON — descarga DynoTable.

Ejemplos relacionados

• DynamoDB BatchWriteItem en Node.js — la misma escritura por lotes con AWS SDK v3.
• Escritura por lotes en DynamoDB en Python — el batch_writer() de boto3 hace el bucle de reintento por ti.
• DynamoDB PutItem con la AWS CLI — la escritura 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 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
• batch-write-item — AWS CLI Command Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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