DynamoDB BatchGetItem em Node.js (AWS SDK v3)

BatchGetItem busca até 100 itens por chave primária em uma única requisição (16 MB no máximo). No AWS SDK v3 você envia um BatchGetItemCommand com um mapa RequestItems de tabela → chaves — e você precisa fazer loop sobre UnprocessedKeys, porque um batch pode legitimamente retornar apenas parte do que você pediu.

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

Explicação

RequestItems — um mapa de nome de tabela → { Keys: [...] }; uma requisição pode abranger múltiplas tabelas. Cada chave deve ser a chave primária completa (partição + classificação para uma chave composta). Mais de 100 chaves, ou a mesma chave duas vezes, falha com uma ValidationException.
Responses — um mapa de nome de tabela → os itens encontrados. Os itens voltam em nenhuma ordem específica, e chaves que não existem simplesmente não aparecem — associe os resultados às requisições pelos atributos de chave.
UnprocessedKeys — o loop de retry acima não é opcional. Se a resposta passar de 16 MB, a capacidade se esgotar, ou a leitura de uma partição passar de 1 MB, o DynamoDB retorna o restante aqui no formato de RequestItems, pronto para ser realimentado diretamente. A AWS recomenda fortemente backoff exponencial entre as tentativas — um retry imediato tende a reincidir no mesmo throttle.
Consistência — leituras em batch têm consistência eventual por padrão; defina ConsistentRead: true por tabela para leituras com consistência forte.
Por tabela você também pode passar ProjectionExpression (com ExpressionAttributeNames) para buscar apenas alguns atributos.
BatchGetItem pode recuperar itens em paralelo do lado do servidor — ele economiza round trips, não capacidade de leitura: o DynamoDB cobra cada item do batch como um GetItem individual.

Faça visualmente

Prefere não montar à mão os mapas de chave em DynamoDB JSON? O DynamoDB Expression Builder constrói mapas tipados de chave/valor e copia código executável, e a calculadora de tamanho de item mostra o quão perto um batch chega do teto de 16 MB.

Para buscar e inspecionar itens entre tabelas numa GUI — sem loops de retry para escrever — baixe o DynoTable.

Exemplos relacionados

DynamoDB BatchGetItem em Python — a mesma leitura em batch com boto3.
DynamoDB BatchGetItem com a AWS CLI — a mesma leitura em batch a partir do shell.
DynamoDB GetItem em Node.js — a leitura de item único que isto agrupa.
Operações em batch no DynamoDB — limites, falha parcial e quando o batching compensa.
"Too many items requested for the BatchGetItem call" — mais de 100 chaves em uma requisição.
"Provided list of item keys contains duplicates" — a mesma chave duas vezes em um batch.

References

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