DynamoDB BatchWriteItem in Node.js (AWS SDK v3)

BatchWriteItem inserisce o elimina fino a 25 Item in una sola richiesta (16 MB totali, 400 KB per Item). In AWS SDK v3 invii un BatchWriteItemCommand il cui RequestItems mescola voci PutRequest e DeleteRequest — e devi iterare su UnprocessedItems, perché il batch nel suo complesso non è atomico.

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

Spiegazione

RequestItems — una mappa nome tabella → un array di massimo 25 voci PutRequest/DeleteRequest (una singola richiesta può interessare più tabelle). Ogni PutRequest.Item richiede la chiave primaria completa; ogni DeleteRequest.Key è solo la chiave.
Non è una transazione — ogni put/delete è atomica individualmente, ma il batch nel suo complesso no: alcune scritture possono riuscire mentre altre subiscono throttling. Ti serve il tutto-o-niente? Usa TransactWriteItems.
UnprocessedItems — il ciclo di retry non è opzionale. Le scritture sottoposte a throttling tornano qui in forma RequestItems, pronte da reinviare; AWS raccomanda vivamente un backoff esponenziale tra i tentativi.
Niente aggiornamenti, niente condizioni — BatchWriteItem non può esprimere UpdateItem, ConditionExpression o ReturnValues; un put su una chiave esistente sostituisce silenziosamente l'intero Item. Chiavi duplicate, mescolare put+delete sullo stesso Item, >25 richieste, un Item >400 KB, o >16 MB totali fanno sì che DynamoDB rifiuti l'intero batch.
Il batching fa risparmiare round trip, non capacità: ogni put/delete fattura gli stessi WCU che addebiterebbe individualmente (un delete su un Item inesistente fattura comunque un WCU).

Fallo visivamente

Preferisci non assemblare a mano gli Item in DynamoDB JSON? Il DynamoDB Expression Builder costruisce mappe di valori tipizzate e copia codice eseguibile, e il calcolatore delle dimensioni degli Item verifica ogni Item rispetto al limite di 400 KB prima di inviarlo.

Per aggiungere, modificare ed eliminare Item in blocco in una GUI — senza cicli di retry da scrivere — scarica DynoTable.

Esempi correlati

Scrittura batch di DynamoDB in Python — il batch_writer() di boto3 fa il ciclo di retry per te.
DynamoDB BatchWriteItem con la AWS CLI — la stessa scrittura batch dalla shell.
DynamoDB TransactWriteItems in Node.js — quando le scritture devono riuscire o fallire insieme.
Operazioni batch in DynamoDB — limiti, fallimenti parziali e quando conviene il batching.
"Too many items requested for the BatchWriteItem call" — più di 25 richieste put/delete in un solo batch.
"Provided list of item keys contains duplicates" — due richieste che toccano la stessa chiave in un solo batch.

References

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.