Obter todos os itens do DynamoDB em Node.js (AWS SDK v3)

Ler uma tabela inteira no SDK v3 significa paginar um Scan até o fim. Cada resposta é limitada a 1 MB, e você devolve LastEvaluatedKey como ExclusiveStartKey até que uma delas pare de vir (como funcionam os cursores do DynamoDB).

O loop abaixo foi escrito à mão para que o cursor fique visível. Em código de verdade você usaria o paginateScan, que o SDK já traz.

Código

import {DynamoDBClient, ScanCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const items = [];
let lastEvaluatedKey;

do {
  const response = await client.send(
    new ScanCommand({
      TableName: 'Music',
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

  items.push(...(response.Items ?? []));
  lastEvaluatedKey = response.LastEvaluatedKey;
} while (lastEvaluatedKey);

console.log(`Table holds ${items.length} items`);

Explicação

• O paginateScan já faz isso — import {paginateScan} from '@aws-sdk/client-dynamodb', e então for await (const page of paginateScan({client}, {TableName: 'Music'})). Ele é gerado a partir dos mesmos três campos de cursor que o loop acima usa à mão (ExclusiveStartKey, LastEvaluatedKey, Limit), então nada muda de comportamento quando você troca.
• Só a ausência de LastEvaluatedKey significa que acabou — uma resposta com zero Items e um cursor é normal, não uma tabela vazia. Sair do loop com Items.length === 0 é o clássico bug de linhas faltando, e uma FilterExpression torna páginas vazias rotina em vez de exceção.
• Limit conta itens avaliados por chamada, não itens no total — é o terceiro campo que o paginador controla, e nem ele nem o pageSize do paginador limitam o tamanho do array que você acaba segurando.
• ExclusiveStartKey: undefined na primeira passada está tudo bem — o serializador descarta membros indefinidos, então a primeira iteração não precisa de caso especial.
• items cresce até o tamanho da tabela — processe cada página dentro do loop e a deixe ir (grave, envie por stream, agregue) a menos que você saiba que a tabela é pequena. Acumular está a um crescimento de tabela de distância de um crash por falta de memória.
• Um scan cobra cada byte que lê, a cada execução — ProjectionExpression reduz o que trafega pela rede, e não a conta (por quê), e uma FilterExpression descarta itens depois que eles já foram lidos e cobrados (Scan com filtro). Em um caminho quente você quer um Query.
• Divida-o com Segment / TotalSegments — N workers assíncronos, cada um controlando o próprio cursor sobre a própria fatia, todos em um cliente compartilhado. O Node vai rodá-los concorrentemente sem reclamar; o custo de leitura não muda, só o tempo de relógio (quando isso vale a pena).

Faça isso visualmente

O construtor de consultas do DynamoDB gera este programa inteiro, loop de paginação incluído, a partir de um formulário, em SDK v3 e em outros sete alvos.

O DynoTable pagina uma tabela ao vivo para você em uma grade de rolagem infinita, e exporta o Scan por trás dessa grade como código executável. Baixe o DynoTable.

Exemplos relacionados

• Obter todos os itens em Python — a mesma leitura completa com o paginador do boto3.
• Obter todos os itens com a AWS CLI — a CLI pagina por você.
• Scan do DynamoDB em Node.js — fazendo scan com uma FilterExpression.
• Scans paralelos — Segment/TotalSegments, número de workers e quando se dar ao trabalho.
• Por que meu Scan do DynamoDB é lento e caro? — o modelo de custo e como evitá-lo.
• DynamoDB ProvisionedThroughputExceededException — ler a tabela inteira é a forma clássica de esbarrar nele.
• "The provided starting key is invalid" — uma chave de retomada corrompida no loop de paginação.

Referências

• Scan — Amazon DynamoDB API Reference
• Scanning tables in DynamoDB — Amazon DynamoDB Developer Guide
• DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide
• [paginateScan — AWS SDK for JavaScript v3 source](https://github.com/aws/aws-sdk-js-v3/blob/main/the client-dynamodb ScanPaginator module)

Verificado pela última vez em 2026-07-28 contra a documentação oficial da AWS vinculada acima.