DynamoDB BatchGetItem in Node.js (AWS SDK v3)

BatchGetItem fetches up to 100 items by primary key in a single request (16 MB max). In AWS SDK v3 you send a BatchGetItemCommand with a RequestItems map of table → keys — and you must loop on UnprocessedKeys, because a batch can legally return only part of what you asked for.

Code

import {BatchGetItemCommand, 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: {
    Keys: [
      {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'Cubano Chant'}},
      {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'A Mis Abuelos'}},
      {Artist: {S: 'Ella Fitzgerald'}, SongTitle: {S: 'Misty'}}
    ]
  }
};

const items = [];
let attempt = 0;

do {
  const response = await client.send(new BatchGetItemCommand({RequestItems: requestItems}));
  items.push(...(response.Responses?.Music ?? []));

  // A partial result is NOT an error: throttling, a >16 MB response, or an
  // internal failure returns the leftovers in UnprocessedKeys. Retry them
  // with exponential backoff.
  requestItems = response.UnprocessedKeys;
  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(`Fetched ${items.length} items`);

Explanation

• RequestItems — a map of table name → { Keys: [...] }; one request can span multiple tables. Every key must be the full primary key (partition + sort for a composite key). More than 100 keys, or the same key twice, fails with a ValidationException.
• Responses — a map of table name → the items found. Items come back in no particular order, and keys that don't exist simply don't appear — match results to requests by their key attributes.
• UnprocessedKeys — the retry loop above is not optional. If the response passes 16 MB, throughput runs out, or a partition read passes 1 MB, DynamoDB returns the remainder here in RequestItems form, ready to feed straight back in. AWS strongly recommends exponential backoff between retries — an immediate retry tends to re-hit the same throttle.
• Consistency — batch reads are eventually consistent by default; set ConsistentRead: true per table for strongly consistent reads.
• Per table you can also pass ProjectionExpression (with ExpressionAttributeNames) to fetch only some attributes.
• BatchGetItem may retrieve items in parallel server-side — it saves round trips, not read capacity: DynamoDB bills each item in the batch as an individual GetItem.

Do it visually

Prefer not to hand-assemble DynamoDB-JSON key maps? The DynamoDB Expression Builder builds typed key/value maps and copies runnable code, and the item size calculator shows how close a batch gets to the 16 MB ceiling.

To fetch and inspect items across tables in a GUI — no retry loops to write — download DynoTable.

Related examples

• DynamoDB BatchGetItem in Python — the same batch read with boto3.
• DynamoDB BatchGetItem with the AWS CLI — the same batch read from the shell.
• DynamoDB GetItem in Node.js — the single-item read this batches.
• Batch operations in DynamoDB — limits, partial failure, and when batching pays off.
• "Too many items requested for the BatchGetItem call" — more than 100 keys in one request.
• "Provided list of item keys contains duplicates" — the same key twice in one batch.

References

• BatchGetItem — 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.