DynamoDB TransactWriteItems en Node.js (AWS SDK v3)

TransactWriteItems agrupa hasta 100 escrituras en una operación de todo o nada — o se aplican todas las acciones, o ninguna. En AWS SDK v3 envías un TransactWriteItemsCommand cuyo array TransactItems mezcla acciones Put, Update, Delete y ConditionCheck, cada una con una condición 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;
  }
}

Explicación

• TransactItems — hasta 100 acciones Put / Update / Delete / ConditionCheck, 4 MB agregados. Las acciones pueden abarcar tablas (misma cuenta + Región), pero dos acciones no pueden apuntar al mismo item — eso por sí solo cancela la transacción.
• ConditionCheck — afirma una condición sobre un item que la transacción no modifica (p. ej. "la cuenta aún existe") y veta toda la transacción si falla.
• TransactionCanceledException — el único error que manejar. err.CancellationReasons lista un {Code, Message} por acción en orden — los códigos incluyen ConditionalCheckFailed, TransactionConflict (otra transacción tocó un item a mitad de vuelo — seguro de reintentar con retroceso), ProvisionedThroughputExceeded y ValidationError; None marca las acciones inocentes. Pon ReturnValuesOnConditionCheckFailure: 'ALL_OLD' en una acción para obtener los atributos del item perdedor en su motivo.
• ClientRequestToken — pasa uno para hacer la llamada idempotente durante 10 minutos; un reintento del SDK tras un timeout de red no puede entonces aplicar las escrituras dos veces.
• Coste — las escrituras transaccionales consumen dos escrituras subyacentes por item (preparar + confirmar), así que facturan aproximadamente 2× las WCU de una escritura simple. No recurras a las transacciones cuando una escritura condicional sobre un solo item ya te da atomicidad sobre un item.

Hazlo visualmente

Las expresiones de condición y de actualización dentro de cada acción son la parte delicada — el DynamoDB Expression Builder las ensambla con los mapas de nombre/valor y copia código ejecutable.

Para editar items y revisar las expresiones generadas en una interfaz gráfica — descarga DynoTable.

Ejemplos relacionados

• DynamoDB TransactWriteItems en Python — la misma transacción con boto3.
• DynamoDB TransactWriteItems con la AWS CLI — la misma transacción desde el shell.
• Escritura condicional en DynamoDB en Node.js — atomicidad sobre un solo item sin el coste 2×.
• Transacciones de DynamoDB — aislamiento, idempotencia y cuándo valen la pena las transacciones.
• DynamoDB TransactionCanceledException — cada código de motivo de cancelación, descifrado.
• "Too many actions in a TransactWriteItems call" — los límites de 100 acciones y 4 MB de la transacción.
• "Transaction request cannot include multiple operations on one item" — una acción por item, por transacción.

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

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