DynamoDB BatchWriteItem in Node.js (AWS SDK v3)

BatchWriteItem legt in einer einzigen Anfrage bis zu 25 Items an oder löscht sie (16 MB gesamt, 400 KB pro Item). In AWS SDK v3 sendest du ein BatchWriteItemCommand, dessen RequestItems PutRequest- und DeleteRequest-Einträge mischt — und du musst über UnprocessedItems schleifen, denn der Batch als Ganzes ist nicht atomar.

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

Erklärung

• RequestItems — eine Zuordnung von Tabellenname → ein Array aus bis zu 25 PutRequest/DeleteRequest-Einträgen (eine Anfrage kann sich über mehrere Tabellen erstrecken). Jedes PutRequest.Item braucht den vollständigen Primärschlüssel; jeder DeleteRequest.Key ist nur der Schlüssel.
• Keine Transaktion — jeder Put/Delete ist einzeln atomar, aber der Batch als Ganzes nicht: manche Schreibvorgänge können erfolgreich sein, während andere gedrosselt werden. Brauchst du Alles-oder-nichts? Nutze TransactWriteItems.
• UnprocessedItems — die Retry-Schleife ist nicht optional. Gedrosselte Schreibvorgänge kommen hier in RequestItems-Form zurück, bereit zum erneuten Absenden; AWS empfiehlt dringend exponentielles Backoff zwischen den Versuchen.
• Keine Updates, keine Bedingungen — BatchWriteItem kann kein UpdateItem, keine ConditionExpression und keine ReturnValues ausdrücken; ein Put auf einen existierenden Schlüssel ersetzt stillschweigend das gesamte Item. Doppelte Schlüssel, das Mischen von Put+Delete auf demselben Item, mehr als 25 Anfragen, ein Item über 400 KB, oder über 16 MB gesamt lassen DynamoDB jeweils den gesamten Batch ablehnen.
• Batching spart Round-Trips, nicht Kapazität: jeder Put/Delete berechnet dieselben WCUs wie einzeln (ein Delete auf einem nicht existierenden Item berechnet immer noch eine WCU).

Visuell erledigen

Lieber keine DynamoDB-JSON-Items von Hand zusammenbauen? Der DynamoDB Expression Builder baut typisierte Wertzuordnungen und kopiert lauffähigen Code, und der Item-Size-Rechner prüft jedes Item gegen die 400-KB-Grenze, bevor du es sendest.

Um Items in großen Mengen in einer GUI hinzuzufügen, zu bearbeiten und zu löschen — keine Retry-Schleifen zu schreiben — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB Batch-Write in Python — boto3s batch_writer() übernimmt die Retry-Schleife für dich.
• DynamoDB BatchWriteItem mit der AWS CLI — derselbe Batch-Write aus der Shell.
• DynamoDB TransactWriteItems in Node.js — wenn die Schreibvorgänge gemeinsam gelingen oder scheitern müssen.
• Batch-Operationen in DynamoDB — Limits, Teilfehler und wann sich Batching lohnt.
• "Too many items requested for the BatchWriteItem call" — mehr als 25 Put/Delete-Anfragen in einem Batch.
• "Provided list of item keys contains duplicates" — zwei Anfragen, die denselben Schlüssel in einem Batch berühren.

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

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