DynamoDB TransactWriteItems em Node.js (AWS SDK v3)

TransactWriteItems agrupa até 100 gravações em uma única operação tudo-ou-nada — ou toda ação é confirmada, ou nenhuma é. No AWS SDK v3 você envia um TransactWriteItemsCommand cujo array TransactItems mistura ações Put, Update, Delete e ConditionCheck, cada uma com uma condição opcional.

Code

import {DynamoDBClient, TransactWriteItemsCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

// Move one award between two songs — atomically. If the first song has no
// award to give, NEITHER update happens.
const command = new TransactWriteItemsCommand({
  TransactItems: [
    {
      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'}}
      }
    }
  ]
});

try {
  await client.send(command);
  console.log('Transaction committed');
} catch (err) {
  if (err.name === 'TransactionCanceledException') {
    // One reason per action, in TransactItems order. 'None' means that action
    // was fine — some OTHER action sank the transaction.
    const codes = (err.CancellationReasons ?? []).map((r) => r.Code);
    console.log('Transaction canceled:', codes); // e.g. ['ConditionalCheckFailed', 'None']
  } else {
    throw err;
  }
}

Explicação

• TransactItems — até 100 ações Put / Update / Delete / ConditionCheck, 4 MB agregados. 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.
• ConditionCheck — afirma uma condição sobre um item que a transação não modifica (por exemplo, "a conta ainda existe") e veta a transação inteira se ela falhar.
• TransactionCanceledException — o único erro a tratar. err.CancellationReasons lista um {Code, Message} por ação em ordem — os códigos incluem ConditionalCheckFailed, TransactionConflict (outra transação tocou um item no meio do caminho — seguro para retry com backoff), ProvisionedThroughputExceeded e ValidationError; None marca as ações inocentes. Defina ReturnValuesOnConditionCheckFailure: 'ALL_OLD' em uma ação para obter os atributos do item perdedor na sua razão.
• ClientRequestToken — passe um para tornar a chamada idempotente por 10 minutos; um retry do SDK após um timeout de rede então não pode aplicar as gravações duas vezes.
• Custo — gravações transacionais consomem duas gravações subjacentes por item (preparar + confirmar), então cobram aproximadamente 2× as WCUs de uma gravação simples. Não recorra a transações quando uma gravação condicional de item único já lhe dá atomicidade em um item.

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 código executável.

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

Exemplos relacionados

• DynamoDB TransactWriteItems em Python — a mesma transação com boto3.
• DynamoDB TransactWriteItems com a AWS CLI — a mesma transação a partir do shell.
• Gravação condicional no DynamoDB em Node.js — atomicidade de item único sem o custo de 2×.
• 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

• TransactWriteItems — Amazon DynamoDB API Reference
• Amazon DynamoDB transactions: how it works — Amazon DynamoDB Developer Guide
• DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide

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