DynamoDB TransactWriteItems in Node.js (AWS SDK v3)

TransactWriteItems gruppiert bis zu 100 Schreibvorgänge in eine Alles-oder-nichts-Operation — entweder committen alle Aktionen, oder keine. In AWS SDK v3 sendest du ein TransactWriteItemsCommand, dessen TransactItems-Array Put-, Update-, Delete- und ConditionCheck-Aktionen mischt, jede mit einer optionalen Bedingung.

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;
  }
}

Erklärung

• TransactItems — bis zu 100 Put / Update / Delete / ConditionCheck-Aktionen, 4 MB aggregiert. Aktionen können sich über Tabellen erstrecken (gleiches Konto + gleiche Region), aber keine zwei Aktionen dürfen dasselbe Item betreffen — das allein bricht die Transaktion ab.
• ConditionCheck — behauptet eine Bedingung auf einem Item, das die Transaktion nicht verändert (z. B. "das Konto existiert noch"), und legt sein Veto gegen die gesamte Transaktion ein, falls sie scheitert.
• TransactionCanceledException — der einzige Fehler, den man behandeln muss. err.CancellationReasons listet ein {Code, Message} pro Aktion in Reihenfolge — Codes umfassen ConditionalCheckFailed, TransactionConflict (eine andere Transaktion berührte ein Item mitten im Vorgang — sicher mit Backoff zu wiederholen), ProvisionedThroughputExceeded und ValidationError; None markiert die unschuldigen Aktionen. Setze ReturnValuesOnConditionCheckFailure: 'ALL_OLD' auf eine Aktion, um die Attribute des verlierenden Items in ihrem Reason zu bekommen.
• ClientRequestToken — übergib eines, um den Aufruf für 10 Minuten idempotent zu machen; ein SDK-Retry nach einem Netzwerk-Timeout kann die Schreibvorgänge dann nicht zweimal anwenden.
• Kosten — transaktionale Schreibvorgänge verbrauchen zwei zugrunde liegende Schreibvorgänge pro Item (prepare + commit), berechnen also ungefähr das 2× der WCUs eines einfachen Schreibvorgangs. Greif nicht zu Transaktionen, wenn ein einzelner bedingter Schreibvorgang dir bereits Atomizität auf einem Item gibt.

Visuell erledigen

Die Bedingungs- und Update-Ausdrücke innerhalb jeder Aktion sind der knifflige Teil — der DynamoDB Expression Builder setzt sie mit den Name-/Wert-Zuordnungen zusammen und kopiert lauffähigen Code.

Um Items zu bearbeiten und die generierten Ausdrücke in einer GUI zu überprüfen — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB TransactWriteItems in Python — dieselbe Transaktion mit boto3.
• DynamoDB TransactWriteItems mit der AWS CLI — dieselbe Transaktion aus der Shell.
• DynamoDB Conditional Write in Node.js — Einzel-Item-Atomizität ohne die 2×-Kosten.
• DynamoDB-Transaktionen — Isolation, Idempotenz und wann Transaktionen sich lohnen.
• DynamoDB TransactionCanceledException — jeder Cancellation-Reason-Code, entschlüsselt.
• "Too many actions in a TransactWriteItems call" — die 100-Aktionen- und 4-MB-Transaktionslimits.
• "Transaction request cannot include multiple operations on one item" — eine Aktion pro Item, pro Transaktion.

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

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.