DynamoDB PutItem con la AWS CLI

aws dynamodb put-item escribe un Item entero y reemplaza cualquier Item existente con la misma clave principal (acciones sobre Items explica en qué se diferencia de update-item). La aportación propia de la CLI al problema es el shell: --item toma DynamoDB JSON como un único argumento entrecomillado, y cada valor de atributo va tipado.

Código

aws dynamodb put-item \
  --table-name 'Music' \
  --item '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"},"AlbumTitle":{"S":"Danzon"},"Year":{"N":"1994"},"Awards":{"N":"0"}}' \
  --condition-expression 'attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)' \
  --expression-attribute-names '{"#cond0":"Artist","#cond1":"SongTitle"}'

Si todo va bien el comando no imprime nada y sale con 0. Si el Item ya existe, la condición falla:

An error occurred (ConditionalCheckFailedException) when calling the PutItem operation:
The conditional request failed

Explicación

El silencio y el código de salida 0 son la única señal de éxito. put-item no imprime JSON salvo que pidas --return-values, así que un script que busque la confirmación en stdout con grep no se disparará nunca. Comprueba $?. Ejecutar el comando de arriba dos veces con aws-cli/2.36.9 dio:

first run:   (no output)                exit 0
second run:  aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed
             exit 254

254 es «el servicio ha dicho que no», no «la CLI se ha roto». La AWS CLI reserva 252/253 para sus propios problemas de sintaxis y configuración y 255 para todo lo demás, así que una ConditionalCheckFailedException, una ValidationException y una limitación aterrizan todas en el mismo 254. Si tu script necesita distinguir un fallo de condición esperado de un fallo real, analiza el nombre del error, no el código de salida. Fíjate también en que 2.36.9 antepone al mensaje aws: [ERROR]: , cosa que las versiones anteriores no hacían; una expresión regular anclada en ^An error occurred dejará de coincidir en silencio tras actualizar la CLI.

Una escritura condicional fallida te cuesta igual. La condición la evalúa el servicio después de haber localizado el Item, y AWS es explícito: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (consultado el 2026-07-28). Un bucle de reintentos alrededor de un put de solo creación factura cada intento. Para hacerte una idea, --return-consumed-capacity TOTAL en un put correcto de un Item de ~15 KB informó de "CapacityUnits": 15. Las escrituras se redondean a 1 KB, no a los 4 KB que usan las lecturas.

--return-values-on-condition-check-failure funciona, pero la CLI esconde la respuesta. Esta es la opción que te dice qué Item bloqueó la escritura, sin una segunda lectura. Añádela y 2.36.9 imprime:

aws: [ERROR]: An error occurred (ConditionalCheckFailedException) when calling the PutItem operation: The conditional request failed

Additional error details:
Item: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

El Item está en la respuesta todo el tiempo; el formateador de errores por defecto se niega a renderizarlo. Añade --cli-error-format json para obtenerlo. (--return-values ALL_OLD es el primo incondicional y solo se dispara cuando la operación tiene éxito; ReturnValues cubre las cinco opciones.)

El entrecomillado es la otra mitad del trabajo. El argumento --item es un único token de shell que contiene JSON que contiene números entrecomillados ({"N": "1994"}, nunca 1994). Cualquier cosa con un apóstrofo dentro, y cualquier Item que pase de unos cientos de bytes, es más fácil como --item file://song.json. --cli-input-json file://request.json va más allá y toma la petición entera, expresión de condición incluida, que además es la forma que puedes revisar en un diff.

Los alias no son decoración opcional. #cond0/#cond1 se resuelven a Artist/SongTitle a través de --expression-attribute-names. Escribir los nombres en línea funciona hasta que uno de ellos choca con una palabra reservada, momento en el que el comando falla por un nombre que no habías tocado.

Hazlo visualmente

Teclear a mano el JSON tipado de --item es donde mueren la mayoría de estos comandos. El conversor de DynamoDB JSON gratuito toma JSON normal y devuelve la forma {"S": …} / {"N": …} que quiere la opción, lista para guardar como payload de file://.

Para añadir y editar Items contra tus propias tablas — un formulario por atributo, selectores de tipo, copiar el resultado de vuelta como comando de la CLI — descarga DynoTable.

Guías relacionadas

Expresiones de condición de DynamoDB — attribute_not_exists, bloqueo optimista y más.
Tipos de datos de DynamoDB — cómo se escribe cada tipo de atributo en DynamoDB JSON.
DynamoDB ConditionalCheckFailedException — lo que lanza la condición de solo creación cuando el Item ya existe.
DynamoDB ValidationException — el cajón de sastre para un Item o una expresión mal formados.

Referencias

Reproducido el 2026-07-28 con aws-cli/2.36.9 contra DynamoDB Local (amazon/dynamodb-local) en el puerto 9000. Los códigos de salida, el texto del error y la lectura de capacidad son salida capturada. La afirmación sobre la capacidad de una escritura fallida se cita de la documentación de AWS en lugar de medirse: DynamoDB Local no devuelve ConsumedCapacity en la ruta de fallo de condición.