DynamoDB TransactWriteItems com a AWS CLI

A transação inteira vai para o aws dynamodb transact-write-items como um único array JSON em --transact-items, então as arestas da CLI são a parte interessante: onde o escape de aspas quebra, o que o código de saída significa, e o fato de que a saída de erro padrão descarta justamente o campo de que você precisa para depurar um cancelamento. O que uma transação te dá é o mesmo em todos os SDKs.

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

Uma transação confirmada não imprime nada e sai com 0. Não há corpo de resposta para conferir, então em um script o código de saída é o resultado.

Explicação

--transact-items — até 100 ações Put / Update / Delete / ConditionCheck, 4 MB no agregado, valores em JSON do DynamoDB. As ações podem abranger tabelas na mesma conta e Região, e duas delas não podem mirar o mesmo item.
Três códigos de saída, três falhas diferentes. 0 confirmou. 252 significa que a validação de parâmetros da própria CLI rejeitou a requisição e nada foi enviado. 254 significa que o DynamoDB respondeu e disse não. Vale ramificar por essa distinção: um 252 é um bug no seu JSON, um 254 pode ser uma condição que você esperava que falhasse.

O formato de erro padrão descarta os motivos por ação. A aws-cli v2 imprime o resumo e então te avisa que está retendo o detalhe:

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.

Reexecute o mesmo comando com --cli-error-format json e a estrutura chega intacta, uma entrada por ação, na ordem 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"
        }
    ]
}

Aqui a condição Awards >= 1 da primeira atualização falhou; None marca a segunda ação como inocente, e repare que ela não carrega campo Message nenhum. Todos os demais códigos estão decodificados na página do TransactionCanceledException.

Mirar um item duas vezes não é um cancelamento. Isso falha na validação antes de qualquer tentativa, e é por isso que não há motivos para imprimir:

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

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 — um token fixo torna as reexecuções idempotentes por 10 minutos. Reutilize o mesmo token com qualquer parâmetro alterado e o DynamoDB retorna IdempotentParameterMismatch em vez de aplicar silenciosamente o novo payload.
Mantenha o array em um arquivo. --transact-items file://transaction.json elimina completamente o escape de aspas do shell, e o arquivo dá para diffar.

O 2× é mensurável a partir do shell

Execute a mesma atualização de item único duas vezes, uma dentro de uma transação e outra fora, ambas com --return-consumed-capacity TOTAL. O DynamoDB Local reporta 2.0 unidades de capacidade para a escrita transacional e 1.0 para a comum: a preparação e o commit cobram cada um.

Esse é todo o argumento contra recorrer a uma transação por padrão. Para atomicidade em um único item você já tem uma ferramenta mais barata em uma escrita condicional, que cobra uma vez só. Para precificar uma carga de trabalho que faz isso milhões de vezes, a calculadora de preços do DynamoDB aceita a contagem de escritas dobrada diretamente. Se montar JSON do DynamoDB em um shell é a parte que você quer parar de fazer, o DynoTable edita itens contra uma tabela real e te mostra a expressão que ele gerou.

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 — escritas 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 — todos os códigos de motivo de cancelamento, decodificados.
"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.

Referências

Verificado pela última vez em 2026-07-28 contra a documentação oficial da AWS vinculada acima.