How to Batch Write Items in DynamoDB Efficiently

To batch write items in DynamoDB, use the BatchWriteItem API which allows you to put or delete multiple items in one request. You prepare a list of write requests grouped by table and send them together, reducing the number of calls and improving performance.

Syntax

The BatchWriteItem operation accepts a map of table names to lists of write requests. Each write request can be a PutRequest to add an item or a DeleteRequest to remove an item.

• RequestItems: A map where keys are table names and values are arrays of write requests.
• PutRequest: Contains an Item to add.
• DeleteRequest: Contains a Key to delete.

Example structure:

{
  "RequestItems": {
    "TableName": [
      { "PutRequest": { "Item": { ... } } },
      { "DeleteRequest": { "Key": { ... } } }
    ]
  }
}

json

BatchWriteItem({
  RequestItems: {
    "YourTableName": [
      {
        PutRequest: {
          Item: {
            "PrimaryKey": { S: "value1" },
            "Attribute": { S: "data1" }
          }
        }
      },
      {
        DeleteRequest: {
          Key: {
            "PrimaryKey": { S: "value2" }
          }
        }
      }
    ]
  }
})

Example

This example shows how to batch write two items into a DynamoDB table using AWS SDK for JavaScript v3. It puts two new items in one request.

javascript

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

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

async function batchWriteItems() {
  const params = {
    RequestItems: {
      "MyTable": [
        {
          PutRequest: {
            Item: {
              "Id": { S: "101" },
              "Name": { S: "Alice" }
            }
          }
        },
        {
          PutRequest: {
            Item: {
              "Id": { S: "102" },
              "Name": { S: "Bob" }
            }
          }
        }
      ]
    }
  };

  try {
    const command = new BatchWriteItemCommand(params);
    const response = await client.send(command);
    console.log("Batch write successful", response);
  } catch (error) {
    console.error("Error in batch write", error);
  }
}

batchWriteItems();

Output

Batch write successful { UnprocessedItems: {} }

Common Pitfalls

• Exceeding batch size limit: DynamoDB limits batch writes to 25 items or 16 MB per request. Sending more causes errors.
• Ignoring unprocessed items: Sometimes DynamoDB returns unprocessed items due to throttling; you must retry them.
• Mixing tables incorrectly: Each table's write requests must be grouped separately in RequestItems.

Always check UnprocessedItems in the response and retry them to ensure all writes succeed.

javascript

/* Wrong: Sending more than 25 items in one batch */
const params = {
  RequestItems: {
    "MyTable": new Array(30).fill({
      PutRequest: {
        Item: { "Id": { S: "x" } }
      }
    })
  }
};

/* Right: Split into multiple batches of 25 or fewer items */

Quick Reference

Concept	Description
BatchWriteItem	API to write or delete multiple items in one request
RequestItems	Map of table names to arrays of write requests
PutRequest	Request to add an item
DeleteRequest	Request to delete an item by key
Limit	Max 25 items or 16 MB per batch
UnprocessedItems	Items not processed due to throttling, must retry

Key Takeaways

Use BatchWriteItem to efficiently write or delete multiple items in one call.

Limit each batch to 25 items or less to avoid errors.

Always check and retry unprocessed items returned by DynamoDB.

Group write requests by table name inside RequestItems.

BatchWriteItem does not support update operations; use PutRequest or DeleteRequest only.