Consultar um GSI do DynamoDB em Node.js (AWS SDK v3)

Consultar um índice secundário global é um Query normal mais um parâmetro: IndexName. A key condition então mira as chaves do índice, não as da tabela — aqui AlbumTitle-index nos permite buscar músicas por álbum, um padrão de acesso que a tabela base (Artist + SongTitle) não consegue atender sem um scan.

Code

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

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

const items = [];
let lastEvaluatedKey;

do {
  const response = await client.send(
    new QueryCommand({
      TableName: 'Music',
      IndexName: 'AlbumTitle-index',
      KeyConditionExpression: '#hashKey = :hashKeyValue',
      ExpressionAttributeNames: {
        '#hashKey': 'AlbumTitle'
      },
      ExpressionAttributeValues: {
        ':hashKeyValue': {S: 'Danzon'}
      },
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

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

console.log(`Found ${items.length} songs on the album`);

Explicação

IndexName — nomeia o GSI a consultar (TableName ainda é obrigatório). A KeyConditionExpression usa a chave de partição (e a chave de classificação opcional) do índice — AlbumTitle aqui — com os mesmos operadores de uma query de tabela.
Apenas consistência eventual — os GSIs replicam da tabela base de forma assíncrona. Passar ConsistentRead: true em uma query de GSI não a atualiza; ela falha com uma ValidationException. (Índices secundários locais suportam consistência forte.)
Você obtém apenas os atributos projetados — uma query de GSI retorna o que o índice projeta (ALL, KEYS_ONLY ou os atributos listados em INCLUDE) e não pode buscar o resto na tabela base. Precisa de um atributo não projetado? Faça um GetItem de acompanhamento na chave da tabela, ou amplie a projeção.
As chaves não são únicas em um GSI — muitos itens podem compartilhar a mesma chave de índice, e itens que não têm o atributo da chave de índice simplesmente não aparecem (esse é o padrão de índice esparso).
Paginação — idêntica a uma query de tabela: no máximo 1 MB por página, faça o loop LastEvaluatedKey → ExclusiveStartKey até ele ficar undefined.

Faça visualmente

O DynamoDB Expression Builder constrói a key condition + mapas de nome/valor para queries de índice e copia o código.

Para navegar nos índices de uma tabela e executar queries de GSI a partir de um formulário — grade paginada, cópia do código SDK v3 gerado — baixe o DynoTable.

Exemplos relacionados

Consultar um GSI do DynamoDB em Python — a mesma query de índice com boto3.
Consultar um GSI do DynamoDB com a AWS CLI — a mesma query de índice a partir do shell.
DynamoDB Query em Node.js — consultando a tabela base.
GSI vs. LSI — qual tipo de índice se encaixa no padrão de acesso.
Por que os GSIs têm consistência eventual — o atraso de replicação explicado.
"The table does not have the specified index" — o nome do índice não corresponde (os nomes de GSI diferenciam maiúsculas de minúsculas).
"Consistent reads are not supported on global secondary indexes" — por que a flag de leitura consistente falha em um GSI.

References

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