DynamoDB BatchWriteItem en Node.js (AWS SDK v3)

BatchWriteItem insère ou supprime jusqu'à 25 éléments en une seule requête (16 Mo au total, 400 Ko par élément). Dans l'AWS SDK v3 tu envoies un BatchWriteItemCommand dont le RequestItems mélange des entrées PutRequest et DeleteRequest — et tu dois boucler sur UnprocessedItems, car le lot dans son ensemble n'est pas atomique.

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

Explication

• RequestItems — une carte nom de table → un tableau de jusqu'à 25 entrées PutRequest/DeleteRequest (une requête peut couvrir plusieurs tables). Chaque PutRequest.Item a besoin de la clé primaire complète ; chaque DeleteRequest.Key n'est que la clé.
• Pas une transaction — chaque insertion/suppression est atomique individuellement, mais le lot dans son ensemble ne l'est pas : certaines écritures peuvent réussir tandis que d'autres sont limitées. Besoin de tout-ou-rien ? Utilise TransactWriteItems.
• UnprocessedItems — la boucle de relance n'est pas optionnelle. Les écritures limitées reviennent ici au format RequestItems, prêtes à être resoumises ; AWS recommande fortement un backoff exponentiel entre les tentatives.
• Pas de mises à jour, pas de conditions — BatchWriteItem ne peut pas exprimer UpdateItem, ConditionExpression, ni ReturnValues ; une insertion sur une clé existante remplace silencieusement l'élément entier. Des clés en double, le mélange insertion+suppression sur le même élément, >25 requêtes, un élément >400 Ko, ou >16 Mo au total font chacun que DynamoDB rejette le lot entier.
• Le regroupement en lot économise des allers-retours, pas de la capacité : chaque insertion/suppression facture les mêmes WCU qu'elle le ferait individuellement (une suppression sur un élément inexistant facture quand même un WCU).

À faire visuellement

Tu préfères ne pas assembler à la main des éléments en DynamoDB JSON ? Le DynamoDB Expression Builder construit des cartes de valeurs typées et copie du code exécutable, et le calculateur de taille d'élément vérifie chaque élément par rapport au plafond de 400 Ko avant l'envoi.

Pour ajouter, éditer et supprimer des éléments en masse dans une interface graphique — aucune boucle de relance à écrire — télécharge DynoTable.

Exemples liés

• Écriture par lot DynamoDB en Python — le batch_writer() de boto3 fait la boucle de relance pour toi.
• DynamoDB BatchWriteItem avec l'AWS CLI — la même écriture par lot depuis le shell.
• DynamoDB TransactWriteItems en Node.js — quand les écritures doivent réussir ou échouer ensemble.
• Opérations par lot dans DynamoDB — limites, échec partiel, et quand le regroupement en lot est payant.
• "Too many items requested for the BatchWriteItem call" — plus de 25 requêtes d'insertion/suppression dans un seul lot.
• "Provided list of item keys contains duplicates" — deux requêtes touchant la même clé dans un seul lot.

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

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.