DynamoDB: Bulk Insert (Guide w/ Code Examples)

BatchWriteCommand accepts complete items to put and complete keys to delete. This example writes two key-only sample items and retries unprocessed operations; each put replaces any existing item with that key.

Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb, use an ES module on a supported Node.js runtime, and configure an AWS Region and credentials. The examples use an existing Orders table with String keys pk and sk unless an index or timestamp key is described.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, BatchWriteCommand } from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

const writes = ["ORDER#001", "ORDER#002"].map(sk => ({
  PutRequest: { Item: { pk: "CUSTOMER#123", sk } },
}));
let pending = { Orders: writes };
for (let attempt = 0; Object.keys(pending).length > 0; attempt++) {
  if (attempt === 8) throw new Error("Batch write incomplete: persist pending writes for retry");
  if (attempt > 0) await new Promise(resolve => setTimeout(resolve, Math.random() * Math.min(5000, 100 * 2 ** attempt)));
  const result = await ddb.send(new BatchWriteCommand({ RequestItems: pending }));
  pending = result.UnprocessedItems ?? {};
}

Chunk larger inputs into at most 25 operations per request and respect the payload limit. Batch writes do not support partial updates, conditions or all-or-nothing execution.

Reference: AWS BatchWriteItem API. For related access patterns, see DynamoDB query examples.