Paginação no DynamoDB

O DynamoDB nunca retorna "todos" os resultados em uma única chamada. Um Query ou Scan retorna no máximo 1 MB de dados, depois entrega a você uma LastEvaluatedKey para retomar dali. Fazer a paginação certa significa iterar sobre essa chave — não sobre um contador.

Como funciona a paginação no DynamoDB?

Um Query ou Scan retorna no máximo 1 MB por chamada, depois devolve uma LastEvaluatedKey. Para paginar, você passa essa chave como a ExclusiveStartKey da próxima chamada e itera até o DynamoDB não retornar mais nenhuma chave. Não há números de página, não há contagem total, e o Limit limita os itens avaliados — não os itens retornados.

let key;
do {
  const out = await client.send(new QueryCommand({...params, ExclusiveStartKey: key}));
  process(out.Items);
  key = out.LastEvaluatedKey;
} while (key);

Quando a LastEvaluatedKey é undefined, você chegou ao fim. Passe-a de volta como ExclusiveStartKey para buscar a próxima fatia.

O controle de fluxo é um único loop que só termina com uma chave ausente:

Cada passagem ou retoma a partir da chave retornada ou para — não há contador.

Limit não é um tamanho de página

O Limit limita quantos itens o DynamoDB avalia, não quantos ele retorna depois de uma FilterExpression. Uma consulta com Limit: 25 atrás de um filtro pode retornar 3 itens e ainda assim entregar uma LastEvaluatedKey — você precisa continuar paginando até a chave estar vazia, mesmo quando uma página parece curta. Uma LastEvaluatedKey não vazia também nunca promete mais itens correspondentes; só uma chave ausente prova que você chegou ao fim.

Deixe o SDK paginar

Ambos os SDKs envolvem o loop acima para que você possa iterar sobre as páginas diretamente:

// AWS SDK for JavaScript v3
import {paginateQuery} from '@aws-sdk/lib-dynamodb';
for await (const page of paginateQuery({client}, params)) {
  process(page.Items);
}

# boto3
paginator = client.get_paginator('query')
for page in paginator.paginate(**params):
    process(page['Items'])

Sem números de página

O DynamoDB não tem contagem total nem acesso aleatório a páginas — você não pode pular para a "página 7" nem voltar sem replayar os cursores. Projete UIs em torno de scroll infinito / "carregar mais", não de páginas numeradas. (Uma consulta Select: 'COUNT' ainda lê — e cobra por — cada item correspondente para contá-los.)

Cursores stateless para APIs

A LastEvaluatedKey são apenas os atributos de chave do último item. Codifique-a em base64 e entregue-a aos clientes como um nextToken opaco; decodifique-a de volta para ExclusiveStartKey na próxima requisição. Sem estado de cursor no servidor.

Esse token é DynamoDB-JSON — inspecione ou crie um à mão com o conversor de DynamoDB-JSON. E se você está paginando para contornar um Scan, isso geralmente é um sinal para adicionar um índice.

Para pular a escrita do laço por completo, o construtor de consultas compõe a solicitação Query/Scan completa e emite um programa executável para SDK v3, CLI ou boto3 — laço de paginação incluído.

Experimente o DynoTable para paginar pelos resultados de consulta visualmente, com o cursor rastreado por você.