Escritura condicional en DynamoDB con la AWS CLI

Una escritura condicional adjunta una --condition-expression a put-item, update-item o delete-item: DynamoDB la evalúa contra el item actual y aplica la escritura solo si se cumple — atómicamente, sin una carrera de lectura-modificación-escritura. Es la primitiva de bloqueo optimista de DynamoDB. Este ejemplo protege una actualización con una comprobación de versión.

Code

aws dynamodb update-item \
  --table-name 'Music' \
  --key '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"}}' \
  --update-expression 'SET #upd0 = :updValue0, #version = :newVersion' \
  --condition-expression 'attribute_exists(#cond0) AND #version = :expectedVersion' \
  --expression-attribute-names '{"#upd0":"Genre","#version":"Version","#cond0":"Artist"}' \
  --expression-attribute-values '{":updValue0":{"S":"Latin Jazz"},":expectedVersion":{"N":"7"},":newVersion":{"N":"8"}}'

Al tener éxito, el comando no imprime nada y sale con 0. Si otro escritor llegó primero, la condición falla:

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

Explicación

--condition-expression — comprobada contra el item almacenado atómicamente con la escritura. Funciones disponibles: attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, más comparadores (=, <>, <, >, <=, >=, BETWEEN, IN) y AND/OR/NOT.
Los dos idiomas de caballo de batalla:
- attribute_exists(#key) en una actualización = "solo actualizar, nunca crear". Sin ella, update-item sobre una clave inexistente crea silenciosamente el item (el bug del upsert accidental).
- attribute_not_exists(#key) en una inserción = "solo crear, nunca sobrescribir" — mostrado en la página de PutItem.
Bloqueo optimista — lee el item (versión 7), luego escribe con #version = :expectedVersion mientras lo subes a 8. Dos escritores concurrentes no pueden ganar ambos; el perdedor sale con código distinto de cero con ConditionalCheckFailedException, vuelve a leer y reintenta sobre la nueva versión.
--return-values-on-condition-check-failure ALL_OLD — pide a DynamoDB que adjunte el item actual al fallo (valores válidos ALL_OLD | NONE; no consume capacidad de lectura). Los SDK exponen ese item en la excepción; la salida de error por defecto de la CLI imprime solo el mensaje, así que los scripts suelen volver a leer con get-item tras un fallo.
Una escritura condicional fallida sigue facturando el intento de escritura — no uses condiciones como una sonda de existencia gratuita.

Hazlo visualmente

Las expresiones de condición son exactamente lo que construye el DynamoDB Expression Builder — elige la función, obtén la expresión + los mapas de nombre/valor como un comando de CLI listo para ejecutar.

Para editar items con expresiones generadas y revisables en lugar de marcadores de posición entre comillas del shell — descarga DynoTable.

Ejemplos relacionados

Escritura condicional en DynamoDB en Node.js — el mismo bloqueo optimista con AWS SDK v3.
Escritura condicional en DynamoDB en Python — el mismo bloqueo optimista con boto3.
DynamoDB PutItem con la AWS CLI — la inserción de solo crear con attribute_not_exists.
Expresiones de condición de DynamoDB — cada función, con patrones.
Entender ReturnValues — qué te da cada opción de retorno.
DynamoDB ConditionalCheckFailedException — cuándo la comprobación fallida es esperada y cómo manejarla de forma barata.

References

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