DynamoDB BatchGetItem in Node.js (AWS SDK v3)

BatchGetItem holt in einer einzigen Anfrage bis zu 100 Items über ihren Primärschlüssel (maximal 16 MB). In AWS SDK v3 sendest du ein BatchGetItemCommand mit einer RequestItems-Zuordnung von Tabelle → Schlüssel — und du musst über UnprocessedKeys schleifen, denn ein Batch darf legitim nur einen Teil des Angeforderten zurückgeben.

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`);

Erklärung

• RequestItems — eine Zuordnung von Tabellenname → { Keys: [...] }; eine Anfrage kann sich über mehrere Tabellen erstrecken. Jeder Schlüssel muss der vollständige Primärschlüssel sein (Partition + Sortierung bei einem zusammengesetzten Schlüssel). Mehr als 100 Schlüssel, oder derselbe Schlüssel doppelt, scheitert mit einer ValidationException.
• Responses — eine Zuordnung von Tabellenname → die gefundenen Items. Items kommen in keiner bestimmten Reihenfolge zurück, und Schlüssel, die nicht existieren, tauchen einfach nicht auf — ordne Ergebnisse ihren Anfragen anhand ihrer Schlüsselattribute zu.
• UnprocessedKeys — die obige Retry-Schleife ist nicht optional. Überschreitet die Antwort 16 MB, geht der Durchsatz aus, oder überschreitet ein Partitions-Read 1 MB, gibt DynamoDB den Rest hier in RequestItems-Form zurück, bereit zum direkten Wiedereinspeisen. AWS empfiehlt dringend exponentielles Backoff zwischen Wiederholungen — ein sofortiger Retry trifft meist dieselbe Drosselung erneut.
• Konsistenz — Batch-Reads sind standardmäßig letztendlich konsistent; setze ConsistentRead: true pro Tabelle für stark konsistente Reads.
• Pro Tabelle kannst du außerdem ProjectionExpression (mit ExpressionAttributeNames) übergeben, um nur einige Attribute zu holen.
• BatchGetItem kann Items serverseitig parallel abrufen — es spart Round-Trips, nicht Lesekapazität: DynamoDB berechnet jedes Item im Batch als einzelnes GetItem.

Visuell erledigen

Lieber keine DynamoDB-JSON-Schlüsselzuordnungen von Hand zusammenbauen? Der DynamoDB Expression Builder baut typisierte Schlüssel-/Wert-Zuordnungen und kopiert lauffähigen Code, und der Item-Size-Rechner zeigt, wie nah ein Batch an die 16-MB-Grenze kommt.

Um Items tabellenübergreifend in einer GUI zu holen und zu inspizieren — keine Retry-Schleifen zu schreiben — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB BatchGetItem in Python — derselbe Batch-Read mit boto3.
• DynamoDB BatchGetItem mit der AWS CLI — derselbe Batch-Read aus der Shell.
• DynamoDB GetItem in Node.js — der Einzel-Item-Read, den dies bündelt.
• Batch-Operationen in DynamoDB — Limits, Teilfehler und wann sich Batching lohnt.
• "Too many items requested for the BatchGetItem call" — mehr als 100 Schlüssel in einer Anfrage.
• "Provided list of item keys contains duplicates" — derselbe Schlüssel doppelt in einem 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

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.