How to Use TransactGetItems in DynamoDB for Atomic Reads

Use TransactGetItems in DynamoDB to read multiple items atomically from one or more tables in a single request. You provide an array of Get operations specifying the table and key for each item, and DynamoDB returns all requested items together or none if any fail.

Syntax

The TransactGetItems operation requires an array of Get objects, each specifying the TableName and Key of the item to retrieve. The request looks like this:

• TransactItems: An array of objects, each with a Get field.
• Get: Contains TableName and Key to identify the item.

DynamoDB returns all items atomically, ensuring consistency.

json

TransactGetItems({
  TransactItems: [
    {
      Get: {
        TableName: 'Table1',
        Key: { 'PrimaryKey': { S: 'KeyValue1' } }
      }
    },
    {
      Get: {
        TableName: 'Table2',
        Key: { 'PrimaryKey': { S: 'KeyValue2' } }
      }
    }
  ]
})

Example

This example shows how to use the AWS SDK for JavaScript (v3) to perform a TransactGetItems request that reads two items from two different tables atomically.

javascript

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

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

async function run() {
  const params = {
    TransactItems: [
      {
        Get: {
          TableName: "Users",
          Key: { "UserId": { S: "user123" } }
        }
      },
      {
        Get: {
          TableName: "Orders",
          Key: { "OrderId": { S: "order456" } }
        }
      }
    ]
  };

  try {
    const command = new TransactGetItemsCommand(params);
    const data = await client.send(command);
    console.log("TransactGetItems succeeded:", JSON.stringify(data.Responses, null, 2));
  } catch (err) {
    console.error("Error", err);
  }
}

run();

Output

{
  "Responses": [
    {
      "Item": {
        "UserId": { "S": "user123" },
        "Name": { "S": "Alice" },
        "Email": { "S": "[e-mail]" }
      }
    },
    {
      "Item": {
        "OrderId": { "S": "order456" },
        "Amount": { "N": "250" },
        "Status": { "S": "Shipped" }
      }
    }
  ]
}

Common Pitfalls

• Not specifying the Key correctly for each item causes the request to fail.
• Trying to read more than 25 items in one TransactGetItems call is not allowed; the limit is 25.
• Assuming partial success: TransactGetItems is atomic, so if any item is missing or the request fails, no items are returned.
• Using inconsistent key types or missing attributes in Key leads to errors.

json

/* Wrong: Missing Key attribute */
TransactGetItems({
  TransactItems: [
    {
      Get: {
        TableName: 'Users'
        // Key missing here
      }
    }
  ]
});

/* Correct: Include Key with proper attribute types */
TransactGetItems({
  TransactItems: [
    {
      Get: {
        TableName: 'Users',
        Key: { 'UserId': { S: 'user123' } }
      }
    }
  ]
});

Quick Reference

TransactGetItems Limits and Tips:

• Maximum 25 items per request.
• All items must be from DynamoDB tables in the same AWS account and region.
• Atomic read: either all items are returned or none.
• Use for consistent reads across multiple tables or items.

Feature	Details
Max Items	25 per request
Atomicity	All or none returned
Use Case	Consistent reads across multiple items/tables
Region/Account	Same AWS region and account
Key Requirement	Must specify full primary key for each item

Key Takeaways

Use TransactGetItems to atomically read multiple items from one or more tables in a single request.

Each item must be identified by its full primary key in the TransactItems array.

TransactGetItems returns all requested items together or none if any fail, ensuring consistency.

You can request up to 25 items per TransactGetItems call.

Common errors come from missing keys or exceeding item limits.