DynamoDB BatchWriteItem con la AWS CLI

aws dynamodb batch-write-item escribe o elimina hasta 25 elementos en un solo comando. Desde el shell tiene dos aristas que los SDK suavizan: cada valor es JSON de DynamoDB que hay que entrecomillar correctamente, y la CLI no tiene ningún mecanismo para vaciar UnprocessedItems. Los límites y el modelo de fallo parcial están en operaciones por lotes en DynamoDB.

Código

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"}}}}
    ]
  }'

Ejecutado contra DynamoDB Local 3.3.0, eso imprime, entero:

{
    "UnprocessedItems": {}
}

Explicación

Un mapa de pendientes vacío es la única señal de éxito que obtienes. El comando imprime UnprocessedItems y nada más, así que un script que solo compruebe el estado de salida dará por buena una escritura hecha a medias. Analiza el mapa; jq -e '.UnprocessedItems | length == 0' es toda la comprobación.
No hay ningún flag para vaciarlo. aws dynamodb query help ofrece --starting-token, --max-items y --page-size. aws dynamodb batch-write-item help no ofrece ninguno, porque UnprocessedItems no es un cursor de paginación. Reenviarlo es un bucle de shell con un sleep, y ya viene con la forma de --request-items.
--condition-expression y --return-values no se aceptan aquí, y eso es cosa de la API, no de la CLI: las condiciones no pueden asociarse a peticiones individuales de escritura y borrado. Cada PutRequest reemplaza el elemento almacenado entero, así que un lote construido a partir de una carga parcial elimina los atributos que dejó fuera.
Usa file://, no JSON en línea. --request-items file://writes.json quita el entrecomillado del shell de la lista de cosas que pueden ir mal, lo que importa porque la mayor parte de lo que va mal en este comando es el entrecomillado.
Una sola entrada mala cuesta las 25. Una tabla inexistente, una clave que no coincide con el esquema, un elemento de más de 400 KB, más de 16 MB en total, una clave de partición de más de 2048 bytes o una clave de ordenación de más de 1024 bytes rechazan el lote entero en lugar de la entrada culpable.

Qué imprime el comando, incluidos los rechazos

Añade --return-consumed-capacity TOTAL al bloque de arriba y DynamoDB Local 3.3.0 responde:

{
    "UnprocessedItems": {},
    "ConsumedCapacity": [
        {
            "TableName": "Music",
            "CapacityUnits": 3.0
        }
    ]
}

Tres unidades por dos escrituras y un borrado: el lote compró un viaje de ida y vuelta, no un descuento. Cada entrada se factura como el PutItem o el DeleteItem individual que representa, redondeado a 1 KB.

Ejecuta el borrado una segunda vez, cuando Ella Fitzgerald / Misty ya no está, y DynamoDB Local informa de 2.0 unidades para ese único DeleteRequest. La referencia de BatchWriteItem (consultada el 2026-07-28) dice que un borrado sobre un elemento inexistente consume una unidad de capacidad de escritura, y un delete-item suelto contra el mismo motor local sí informa de 1.0. Trata las cifras de capacidad locales como orientativas. Lo que sobrevive en cualquier caso es que un borrado que no encuentra nada se factura igual.

Dos peticiones que el servicio rechaza de plano, en stderr, estado de salida 254:

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Too many items requested for the BatchWriteItem call
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Provided list of item keys contains duplicates

La segunda merece que la mires con calma. La produjeron un PutRequest y un DeleteRequest sobre la misma clave, no dos escrituras. DynamoDB cuenta cualquier segunda operación sobre un elemento dentro de un lote como un duplicado, así que «borra la fila vieja y escribe la nueva» falla como lote único aunque las dos entradas no se parezcan en nada.

Montar esos mapas de valores entre comillas simples es donde se va el tiempo. El DynamoDB Expression Builder genera mapas tipados y copia un comando ejecutable, así que un fallo es al menos un fallo real y no una contrabarra perdida.

Para cargar en masa o vaciar elementos desde CSV o JSON sin escapar nada, descarga DynoTable.

Ejemplos relacionados

DynamoDB BatchWriteItem en Node.js — la misma escritura por lotes con AWS SDK v3.
Escritura por lotes en DynamoDB con Python — el batch_writer() de boto3 hace el bucle de reintentos por ti.
DynamoDB PutItem con la AWS CLI — la escritura de un solo elemento que esto agrupa.
Operaciones por lotes en DynamoDB — límites, fallos parciales y cuándo compensa agrupar.
"Too many items requested for the BatchWriteItem call" — más de 25 peticiones de escritura o borrado en un lote.
"Provided list of item keys contains duplicates" — dos peticiones tocando la misma clave en un lote.

Referencias

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