DynamoDB TransactWriteItems con la AWS CLI

La transacción entera va a aws dynamodb transact-write-items como un único array JSON en --transact-items, así que lo interesante son las aristas de la CLI: dónde se rompe el entrecomillado, qué significa el código de salida y el hecho de que la salida de error por defecto se deja fuera el campo que necesitas para depurar una cancelación. Lo que te aporta una transacción es igual en todos los SDK.

Código

aws dynamodb transact-write-items \
  --transact-items '[
    {
      "Update": {
        "TableName": "Music",
        "Key": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
        "UpdateExpression": "SET #upd0 = #upd0 - :one",
        "ConditionExpression": "#upd0 >= :one",
        "ExpressionAttributeNames": {"#upd0": "Awards"},
        "ExpressionAttributeValues": {":one": {"N": "1"}}
      }
    },
    {
      "Update": {
        "TableName": "Music",
        "Key": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
        "UpdateExpression": "SET #upd0 = if_not_exists(#upd0, :zero) + :one",
        "ExpressionAttributeNames": {"#upd0": "Awards"},
        "ExpressionAttributeValues": {":one": {"N": "1"}, ":zero": {"N": "0"}}
      }
    }
  ]'

Una transacción confirmada no imprime nada y sale con 0. No hay cuerpo de respuesta que comprobar, así que en un script el código de salida es el resultado.

Explicación

--transact-items — hasta 100 acciones Put / Update / Delete / ConditionCheck, 4 MB en total, valores en JSON de DynamoDB. Las acciones pueden abarcar tablas de la misma cuenta y región, y ninguna de ellas puede apuntar al mismo elemento.
Tres códigos de salida, tres fallos distintos. 0 confirmada. 252 significa que la validación de parámetros de la propia CLI rechazó la petición y no se envió nada. 254 significa que DynamoDB respondió y dijo que no. Esa distinción merece una rama: un 252 es un bug en tu JSON, un 254 puede ser una condición que esperabas que fallase.

El formato de error por defecto se deja fuera los motivos por acción. aws-cli v2 imprime el resumen y luego te dice que se está guardando el detalle:

aws: [ERROR]: An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

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

Reejecuta el mismo comando con --cli-error-format json y la estructura llega intacta, una entrada por acción, en el orden de --transact-items:

{
    "Message": "Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]",
    "Code": "TransactionCanceledException",
    "CancellationReasons": [
        {
            "Code": "ConditionalCheckFailed",
            "Message": "The conditional request failed"
        },
        {
            "Code": "None"
        }
    ]
}

Aquí falló la condición Awards >= 1 de la primera actualización; None marca la segunda acción como inocente, y fíjate en que no lleva ningún campo Message. Todos los demás códigos están descifrados en la página de TransactionCanceledException.

Apuntar dos veces al mismo elemento no es una cancelación. Falla en la validación antes de intentar nada, y por eso no hay motivos que imprimir:

aws: [ERROR]: An error occurred (ValidationException) when calling the TransactWriteItems operation: Transaction request cannot include multiple operations on one item

ConditionCheck — comprueba una condición sobre un elemento que la transacción no modifica, y veta la transacción entera si falla.
--client-request-token — un token fijo hace idempotentes las reejecuciones durante 10 minutos. Reutiliza el mismo token con cualquier parámetro cambiado y DynamoDB devuelve IdempotentParameterMismatch en lugar de aplicar la nueva carga en silencio.
Guarda el array en un archivo. --transact-items file://transaction.json evita por completo el entrecomillado del shell, y el archivo se puede diffear.

El 2× se puede medir desde el shell

Ejecuta la misma actualización de un solo elemento dos veces, una dentro de una transacción y otra fuera, ambas con --return-consumed-capacity TOTAL. DynamoDB Local informa de 2.0 unidades de capacidad para la escritura transaccional y 1.0 para la normal: la preparación y la confirmación facturan cada una.

Ese es todo el argumento contra recurrir a una transacción por defecto. Para atomicidad sobre un solo elemento ya tienes una herramienta más barata en una escritura condicional, que factura una vez. Para poner precio a una carga que hace esto millones de veces, la calculadora de precios de DynamoDB acepta directamente el número de escrituras duplicado. Si montar JSON de DynamoDB en un shell es la parte que quieres dejar de hacer, DynoTable edita elementos contra una tabla real y te enseña la expresión que generó.

Ejemplos relacionados

DynamoDB TransactWriteItems en Node.js — la misma transacción con AWS SDK v3.
DynamoDB TransactWriteItems en Python — la misma transacción con boto3.
DynamoDB BatchWriteItem con la AWS CLI — escrituras masivas cuando no necesitas atomicidad.
Transacciones en DynamoDB — aislamiento, idempotencia y cuándo compensan las transacciones.
DynamoDB TransactionCanceledException — todos los códigos de motivo de cancelación, descifrados.
"Too many actions in a TransactWriteItems call" — los límites de 100 acciones y 4 MB por transacción.
"Transaction request cannot include multiple operations on one item" — una acción por elemento y por transacción.

Referencias

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