DynamoDB Query a un GSI en Node.js (AWS SDK v3)

Consultar un índice secundario global es un Query normal más un parámetro: IndexName. La condición de clave apunta entonces a las claves del índice, no a las de la tabla — aquí AlbumTitle-index nos permite obtener canciones por álbum, un patrón de acceso que la tabla base (Artist + SongTitle) no puede servir sin un 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`);

Explicación

IndexName — nombra el GSI a consultar (TableName sigue siendo obligatorio). El KeyConditionExpression usa la clave de partición (y la de ordenación opcional) del índice — AlbumTitle aquí — con los mismos operadores que una consulta de tabla.
Solo consistencia eventual — los GSI se replican desde la tabla base de forma asíncrona. Pasar ConsistentRead: true en una consulta a un GSI no la mejora; falla con una ValidationException. (Los índices secundarios locales sí admiten consistencia fuerte.)
Solo obtienes los atributos proyectados — una consulta a un GSI devuelve lo que el índice proyecta (atributos ALL, KEYS_ONLY o los listados con INCLUDE) y no puede obtener el resto de la tabla base. ¿Necesitas un atributo no proyectado? Continúa con GetItem sobre la clave de la tabla, o amplía la proyección.
Las claves no son únicas en un GSI — muchos items pueden compartir la misma clave de índice, y los items a los que les falta el atributo de clave del índice simplemente no aparecen (ese es el patrón de índice disperso).
Paginación — idéntica a una consulta de tabla: como máximo 1 MB por página, itera LastEvaluatedKey → ExclusiveStartKey hasta que sea undefined.

Hazlo visualmente

El DynamoDB Expression Builder construye la condición de clave + los mapas de nombres/valores para consultas de índice y copia el código.

Para explorar los índices de una tabla y ejecutar consultas a GSI desde un formulario — cuadrícula paginada, copia del código SDK v3 generado — descarga DynoTable.

Ejemplos relacionados

DynamoDB Query a un GSI en Python — la misma consulta de índice con boto3.
DynamoDB Query a un GSI con la AWS CLI — la misma consulta de índice desde el shell.
DynamoDB Query en Node.js — consultar la tabla base.
GSI vs. LSI — qué tipo de índice encaja con el patrón de acceso.
Por qué los GSI son de consistencia eventual — el retardo de replicación explicado.
"The table does not have the specified index" — el nombre del índice no coincide (los nombres de GSI distinguen mayúsculas y minúsculas).
"Consistent reads are not supported on global secondary indexes" — por qué la opción de lectura consistente falla en un GSI.

References

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.