DynamoDB BatchWriteItem em Node.js (AWS SDK v3)

BatchWriteItem grava ou exclui até 25 itens em uma única requisição (16 MB no total, 400 KB por item). No AWS SDK v3 você envia um BatchWriteItemCommand cujo RequestItems mistura entradas PutRequest e DeleteRequest — e você precisa fazer loop sobre UnprocessedItems, porque o batch como um todo não é atômico.

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

Explicação

RequestItems — um mapa de nome de tabela → um array de até 25 entradas PutRequest/DeleteRequest (uma requisição pode abranger múltiplas tabelas). Cada PutRequest.Item precisa da chave primária completa; cada DeleteRequest.Key é apenas a chave.
Não é uma transação — cada put/delete é atômico individualmente, mas o batch como um todo não é: algumas gravações podem ter sucesso enquanto outras sofrem throttling. Precisa de tudo-ou-nada? Use TransactWriteItems.
UnprocessedItems — o loop de retry não é opcional. Gravações com throttling voltam aqui no formato de RequestItems, prontas para reenviar; a AWS recomenda fortemente backoff exponencial entre as tentativas.
Sem updates, sem condições — BatchWriteItem não consegue expressar UpdateItem, ConditionExpression nem ReturnValues; um put em uma chave existente substitui o item inteiro silenciosamente. Chaves duplicadas, misturar put+delete no mesmo item, >25 requisições, um item de >400 KB, ou >16 MB no total fazem o DynamoDB rejeitar o batch inteiro.
O batching economiza round trips, não capacidade: cada put/delete cobra as mesmas WCUs que cobraria individualmente (um delete em um item inexistente ainda cobra uma WCU).

Faça visualmente

Prefere não montar à mão os itens em DynamoDB JSON? O DynamoDB Expression Builder constrói mapas tipados de valor e copia código executável, e a calculadora de tamanho de item verifica cada item contra o limite de 400 KB antes de você enviá-lo.

Para adicionar, editar e excluir itens em massa numa GUI — sem loops de retry para escrever — baixe o DynoTable.

Exemplos relacionados

Escrita em batch no DynamoDB em Python — o batch_writer() do boto3 faz o loop de retry por você.
DynamoDB BatchWriteItem com a AWS CLI — a mesma escrita em batch a partir do shell.
DynamoDB TransactWriteItems em Node.js — quando as gravações precisam ter sucesso ou falhar juntas.
Operações em batch no DynamoDB — limites, falha parcial e quando o batching compensa.
"Too many items requested for the BatchWriteItem call" — mais de 25 requisições de put/delete em um batch.
"Provided list of item keys contains duplicates" — duas requisições tocando a mesma chave em um batch.

References

Última verificação em 2026-07-13 contra a documentação oficial da AWS vinculada acima.