DynamoDB BatchGetItem en Node.js (AWS SDK v3)

BatchGetItem récupère jusqu'à 100 éléments par clé primaire en une seule requête (16 Mo max). Dans l'AWS SDK v3 tu envoies un BatchGetItemCommand avec une carte RequestItems table → clés — et tu dois boucler sur UnprocessedKeys, car un lot peut légitimement ne renvoyer qu'une partie de ce que tu as demandé.

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

Explication

RequestItems — une carte nom de table → { Keys: [...] } ; une requête peut couvrir plusieurs tables. Chaque clé doit être la clé primaire complète (partition + tri pour une clé composite). Plus de 100 clés, ou la même clé deux fois, échoue avec une ValidationException.
Responses — une carte nom de table → les éléments trouvés. Les éléments reviennent dans aucun ordre particulier, et les clés qui n'existent pas n'apparaissent tout simplement pas — associe les résultats aux requêtes par leurs attributs de clé.
UnprocessedKeys — la boucle de relance ci-dessus n'est pas optionnelle. Si la réponse dépasse 16 Mo, que le débit est épuisé, ou qu'une lecture de partition dépasse 1 Mo, DynamoDB renvoie le reste ici au format RequestItems, prêt à être réinjecté directement. AWS recommande fortement un backoff exponentiel entre les tentatives — une relance immédiate a tendance à retomber sur la même limitation.
Cohérence — les lectures par lot sont à terme par défaut ; définis ConsistentRead: true par table pour des lectures fortement cohérentes.
Par table tu peux aussi passer ProjectionExpression (avec ExpressionAttributeNames) pour ne récupérer que certains attributs.
BatchGetItem peut récupérer les éléments en parallèle côté serveur — il économise des allers-retours, pas de la capacité de lecture : DynamoDB facture chaque élément du lot comme un GetItem individuel.

À faire visuellement

Tu préfères ne pas assembler à la main des cartes de clés en DynamoDB JSON ? Le DynamoDB Expression Builder construit des cartes clé/valeur typées et copie du code exécutable, et le calculateur de taille d'élément montre à quel point un lot s'approche du plafond de 16 Mo.

Pour récupérer et inspecter des éléments sur plusieurs tables dans une interface graphique — aucune boucle de relance à écrire — télécharge DynoTable.

Exemples liés

DynamoDB BatchGetItem en Python — la même lecture par lot avec boto3.
DynamoDB BatchGetItem avec l'AWS CLI — la même lecture par lot depuis le shell.
DynamoDB GetItem en Node.js — la lecture d'un seul élément que ceci regroupe en lot.
Opérations par lot dans DynamoDB — limites, échec partiel, et quand le regroupement en lot est payant.
"Too many items requested for the BatchGetItem call" — plus de 100 clés dans une seule requête.
"Provided list of item keys contains duplicates" — la même clé deux fois dans un seul lot.

References

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