DynamoDB TransactWriteItems com a AWS CLI

aws dynamodb transact-write-items agrupa até 100 gravações em uma única operação tudo-ou-nada — ou toda ação é confirmada, ou nenhuma é. As ações vão em --transact-items como um array JSON misturando Put, Update, Delete e ConditionCheck, cada uma com uma condição opcional.

Code

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

Em caso de sucesso o comando não imprime nada e sai com 0. Se qualquer condição falhar, a transação inteira é cancelada:

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

Explicação

--transact-items — até 100 ações Put / Update / Delete / ConditionCheck, 4 MB agregados, valores em DynamoDB JSON. As ações podem abranger tabelas (mesma conta + Region), mas nenhuma dupla de ações pode mirar o mesmo item — isso sozinho cancela a transação.
As razões de cancelamento vêm na mensagem de erro em ordem de ação — os códigos incluem ConditionalCheckFailed, TransactionConflict (outra transação tocou um item no meio do caminho — seguro reexecutar), ProvisionedThroughputExceeded e ValidationError; None marca as ações inocentes. Aqui a condição do primeiro update (Awards >= 1) falhou; a segunda ação estava correta.
ConditionCheck — afirma uma condição sobre um item que a transação não modifica e veta a transação inteira se ela falhar.
--client-request-token — passe um token fixo para tornar as reexecuções idempotentes por 10 minutos; reexecutar o comando exato após um timeout então não pode aplicar as gravações duas vezes.
Custo — gravações transacionais cobram aproximadamente 2× as WCUs de gravações simples (preparar + confirmar). Para atomicidade em um único item, uma gravação condicional é a ferramenta mais barata.
Dica: mantenha o array de ações em um arquivo e passe --transact-items file://transaction.json.

Faça visualmente

As condition e update expressions dentro de cada ação são a parte chata — o DynamoDB Expression Builder as monta com os mapas de nome/valor e copia comandos prontos para executar.

Para editar itens e revisar as expressões geradas numa GUI — baixe o DynoTable.

Exemplos relacionados

DynamoDB TransactWriteItems em Node.js — a mesma transação com o AWS SDK v3.
DynamoDB TransactWriteItems em Python — a mesma transação com boto3.
DynamoDB BatchWriteItem com a AWS CLI — gravações em massa quando você não precisa de atomicidade.
Transações do DynamoDB — isolamento, idempotência e quando as transações valem a pena.
DynamoDB TransactionCanceledException — cada código de razão de cancelamento, decodificado.
"Too many actions in a TransactWriteItems call" — os limites de 100 ações e 4 MB da transação.
"Transaction request cannot include multiple operations on one item" — uma ação por item, por transação.

References

Última verificação em 2026-07-13 contra a documentação oficial da AWS vinculada acima.