DynamoDB TransactWriteItems with the AWS CLI

aws dynamodb transact-write-items groups up to 100 writes into one all-or-nothing operation — either every action commits, or none do. The actions go in --transact-items as a JSON array mixing Put, Update, Delete, and ConditionCheck, each with an optional condition.

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

On success the command prints nothing and exits 0. If any condition fails, the whole transaction cancels:

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

Explanation

• --transact-items — up to 100 Put / Update / Delete / ConditionCheck actions, 4 MB aggregate, values in DynamoDB JSON. Actions can span tables (same account + Region), but no two actions may target the same item — that alone cancels the transaction.
• The cancellation reasons ride in the error message in action order — codes include ConditionalCheckFailed, TransactionConflict (another transaction touched an item mid-flight — safe to re-run), ProvisionedThroughputExceeded, and ValidationError; None marks the innocent actions. Here the first update's condition (Awards >= 1) failed; the second action was fine.
• ConditionCheck — asserts a condition on an item the transaction does not modify and vetoes the whole transaction if it fails.
• --client-request-token — pass a fixed token to make re-runs idempotent for 10 minutes; re-running the exact command after a timeout then can't apply the writes twice.
• Cost — transactional writes bill roughly 2× the WCUs of plain writes (prepare + commit). For atomicity on a single item, a conditional write is the cheaper tool.
• Tip: keep the action array in a file and pass --transact-items file://transaction.json.

Do it visually

The condition and update expressions inside each action are the fiddly part — the DynamoDB Expression Builder assembles them with the name/value maps and copies ready-to-run commands.

To edit items and review the generated expressions in a GUI — download DynoTable.

Related examples

• DynamoDB TransactWriteItems in Node.js — the same transaction with AWS SDK v3.
• DynamoDB TransactWriteItems in Python — the same transaction with boto3.
• DynamoDB BatchWriteItem with the AWS CLI — bulk writes when you don't need atomicity.
• DynamoDB transactions — isolation, idempotency, and when transactions are worth it.
• DynamoDB TransactionCanceledException — every cancellation-reason code, decoded.
• "Too many actions in a TransactWriteItems call" — the 100-action and 4 MB transaction limits.
• "Transaction request cannot include multiple operations on one item" — one action per item, per transaction.

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

Last verified 2026-07-13 against the official AWS documentation linked above.