DynamoDB BatchWriteItem in Node.js (AWS SDK v3)

BatchWriteItem puts or deletes up to 25 items in a single request (16 MB total, 400 KB per item). In AWS SDK v3 you send a BatchWriteItemCommand whose RequestItems mixes PutRequest and DeleteRequest entries — and you must loop on UnprocessedItems, because the batch as a whole is not atomic.

Code

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

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

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let requestItems = {
  Music: [
    {
      PutRequest: {
        Item: {
          Artist: {S: 'Arturo Sandoval'},
          SongTitle: {S: 'Cubano Chant'},
          AlbumTitle: {S: 'Danzon'},
          Year: {N: '1994'}
        }
      }
    },
    {
      PutRequest: {
        Item: {
          Artist: {S: 'Arturo Sandoval'},
          SongTitle: {S: 'A Mis Abuelos'},
          AlbumTitle: {S: 'Danzon'},
          Year: {N: '1994'}
        }
      }
    },
    {
      DeleteRequest: {
        Key: {Artist: {S: 'Ella Fitzgerald'}, SongTitle: {S: 'Misty'}}
      }
    }
  ]
};

let attempt = 0;

do {
  const response = await client.send(new BatchWriteItemCommand({RequestItems: requestItems}));

  // Writes that were throttled come back in UnprocessedItems — resubmit them
  // with exponential backoff until the map is empty.
  requestItems = response.UnprocessedItems;
  if (requestItems && Object.keys(requestItems).length > 0) {
    attempt += 1;
    await sleep(Math.min(100 * 2 ** attempt, 5000));
  }
} while (requestItems && Object.keys(requestItems).length > 0);

console.log('Batch written');

Explanation

• RequestItems — a map of table name → an array of up to 25 PutRequest/DeleteRequest entries (one request can span multiple tables). Each PutRequest.Item needs the full primary key; each DeleteRequest.Key is just the key.
• Not a transaction — each put/delete is atomic individually, but the batch as a whole is not: some writes can succeed while others are throttled. Need all-or-nothing? Use TransactWriteItems.
• UnprocessedItems — the retry loop is not optional. Throttled writes come back here in RequestItems form, ready to resubmit; AWS strongly recommends exponential backoff between attempts.
• No updates, no conditions — BatchWriteItem cannot express UpdateItem, ConditionExpression, or ReturnValues; a put on an existing key silently replaces the whole item. Duplicate keys, mixing put+delete on the same item, >25 requests, a >400 KB item, or >16 MB total each cause DynamoDB to reject the entire batch.
• Batching saves round trips, not capacity: every put/delete bills the same WCUs it would individually (a delete on a nonexistent item still bills one WCU).

Do it visually

Prefer not to hand-assemble DynamoDB-JSON items? The DynamoDB Expression Builder builds typed value maps and copies runnable code, and the item size calculator checks each item against the 400 KB cap before you send it.

To bulk-add, edit, and delete items in a GUI — no retry loops to write — download DynoTable.

Related examples

• DynamoDB batch write in Python — boto3's batch_writer() does the retry loop for you.
• DynamoDB BatchWriteItem with the AWS CLI — the same batch write from the shell.
• DynamoDB TransactWriteItems in Node.js — when the writes must succeed or fail together.
• Batch operations in DynamoDB — limits, partial failure, and when batching pays off.
• "Too many items requested for the BatchWriteItem call" — more than 25 put/delete requests in one batch.
• "Provided list of item keys contains duplicates" — two requests touching the same key in one batch.

References

• BatchWriteItem — Amazon DynamoDB API Reference
• Error handling with DynamoDB — 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.