DynamoDB TransactWriteItems mit der AWS CLI

aws dynamodb transact-write-items gruppiert bis zu 100 Schreibvorgänge in eine Alles-oder-nichts-Operation — entweder committen alle Aktionen, oder keine. Die Aktionen stehen in --transact-items als ein JSON-Array, das Put, Update, Delete und ConditionCheck mischt, jede mit einer optionalen Bedingung.

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

Bei Erfolg gibt der Befehl nichts aus und beendet sich mit 0. Scheitert eine Bedingung, wird die gesamte Transaktion abgebrochen:

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

Erklärung

• --transact-items — bis zu 100 Put / Update / Delete / ConditionCheck-Aktionen, 4 MB aggregiert, Werte in DynamoDB JSON. 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.
• Die Cancellation Reasons stehen in der Fehlermeldung in Aktionsreihenfolge — Codes umfassen ConditionalCheckFailed, TransactionConflict (eine andere Transaktion berührte ein Item mitten im Vorgang — sicher erneut auszuführen), ProvisionedThroughputExceeded und ValidationError; None markiert die unschuldigen Aktionen. Hier scheiterte die Bedingung des ersten Updates (Awards >= 1); die zweite Aktion war in Ordnung.
• ConditionCheck — behauptet eine Bedingung auf einem Item, das die Transaktion nicht verändert, und legt sein Veto gegen die gesamte Transaktion ein, falls sie scheitert.
• --client-request-token — übergib ein festes Token, um Wiederholungen für 10 Minuten idempotent zu machen; ein erneutes Ausführen genau desselben Befehls nach einem Timeout kann die Schreibvorgänge dann nicht zweimal anwenden.
• Kosten — transaktionale Schreibvorgänge berechnen ungefähr das 2× der WCUs von einfachen Schreibvorgängen (prepare + commit). Für Atomizität auf einem einzelnen Item ist ein bedingter Schreibvorgang das günstigere Werkzeug.
• Tipp: Lege das Aktions-Array in einer Datei ab und übergib --transact-items file://transaction.json.

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 lauffertige Befehle.

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

Verwandte Beispiele

• DynamoDB TransactWriteItems in Node.js — dieselbe Transaktion mit AWS SDK v3.
• DynamoDB TransactWriteItems in Python — dieselbe Transaktion mit boto3.
• DynamoDB BatchWriteItem mit der AWS CLI — Massenschreibvorgänge, wenn du keine Atomizität brauchst.
• 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
• transact-write-items — AWS CLI Command 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.