Using DynamoDB TransactWriteItems for Atomic Multi‑Item Updates

Atomic multi‑item writes in DynamoDB

When you need to apply several put, update, delete or condition‑check actions as a single all‑or‑nothing operation, use the TransactWriteItems API. It guarantees that either every action succeeds or none are applied, which simplifies consistency logic in applications that manipulate multiple items.

Worked example (AWS SDK for JavaScript v3)

The following snippet shows a transaction that conditionally increments a counter on one item and sets a status flag on another. Both actions must succeed together.

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

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

const params = {
  TransactItems: [
    {
      Update: {
        TableName: "GameScores",
        Key: { PlayerId: { S: "alice" }, GameId: { S: "g123" } },
        UpdateExpression: "SET Score = Score + :inc",
        ExpressionAttributeValues: { ":inc": { N: "10" } },
        ConditionExpression: "attribute_exists(PlayerId)"
      }
    },
    {
      Put: {
        TableName: "GameMetadata",
        Item: {
          GameId: { S: "g123" },
          LastUpdated: { S: new Date().toISOString() },
          Status: { S: "IN_PROGRESS" }
        },
        ConditionExpression: "attribute_not_exists(GameId)"
      }
    }
  ]
};

try {
  const data = await client.send(new TransactWriteItemsCommand(params));
  console.log("Transaction succeeded", data);
} catch (err) {
  if (err.name === "ConditionalCheckFailedException") {
    console.error("One condition failed – transaction aborted");
  } else if (err.name === "ValidationException") {
    console.error("Request exceeded limits or malformed", err.message);
  } else {
    console.error("Unexpected error", err);
  }
}

Where to run: any environment with AWS SDK v3 installed (Node.js, Lambda, EC2, etc.). The caller must have the IAM permission dynamodb:TransactWriteItems on the target tables; without it the call returns AccessDeniedException.

How the mechanism works

• The request bundles up to 25 individual action objects (Put, Update, Delete, ConditionCheck) into a single HTTP payload.
• DynamoDB validates the payload size (≤ 4 MB) and each item size (≤ 400 KB). If validation passes, it acquires locks on the involved items, applies all changes atomically, then releases the locks.
• If any action fails its condition check or encounters a throttling error, the entire transaction is rolled back and a ConditionalCheckFailedException or ThrottlingException is returned.

Limits and common mistakes

• Item count: More than 25 actions triggers a ValidationException with the message "Transaction cannot exceed 25 items". Split the work into multiple transactions or redesign the data model.
• Payload size: Even with fewer than 25 actions, a large attribute value can push the request over 4 MB, causing the same ValidationException. Measure the serialized JSON size before sending.
• Conditional checks: A failing condition aborts the whole transaction. Design conditions that are independent or use separate ConditionCheck actions to validate pre‑conditions without mutating data.
• Streams impact: If the table has DynamoDB Streams enabled, each action in the transaction generates its own stream record. Downstream consumers may see multiple records for a single logical transaction; consider deduplication or using a transaction ID attribute.
• Retry behavior: AWS SDKs automatically retry throttling errors with exponential backoff. Avoid adding application‑level retries that could double‑count attempts and cause unintended side effects.
• IAM permissions: Missing dynamodb:TransactWriteItems yields AccessDeniedException. Ensure the policy includes the action on the specific table ARN or uses a wildcard with caution.

Practical verification steps

1. Create a test table (e.g., TestTxn) with on‑demand capacity.
2. Insert two sample items using PutItem.
3. Execute a TransactWriteItems request that updates both items conditionally (as in the example).
4. Check the response: either both updates appear in the table or neither does.
5. Monitor CloudWatch metrics UserErrors and ThrottledRequests for the table; they should remain low for a successful transaction.
6. To confirm limits, deliberately send a request with 26 Put actions or a payload > 4 MB and verify that the service returns ValidationException.