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

Interroger un index secondaire global est un Query normal plus un paramètre : IndexName. La condition de clé cible alors les clés de l'index, pas celles de la table — ici AlbumTitle-index nous permet de récupérer les chansons par album, un schéma d'accès que la table de base (Artist + SongTitle) ne peut pas servir sans 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`);

Explication

IndexName — nomme le GSI à interroger (TableName reste obligatoire). Le KeyConditionExpression utilise la clé de partition (et de tri optionnelle) de l'index — AlbumTitle ici — avec les mêmes opérateurs qu'une requête sur table.
Cohérence à terme uniquement — les GSI se répliquent depuis la table de base de façon asynchrone. Passer ConsistentRead: true sur une requête sur GSI ne l'améliore pas ; elle échoue avec une ValidationException. (Les index secondaires locaux, eux, prennent en charge la forte cohérence.)
Tu n'obtiens que les attributs projetés — une requête sur GSI renvoie ce que l'index projette (attributs ALL, KEYS_ONLY, ou listés dans INCLUDE) et ne peut pas récupérer le reste depuis la table de base. Besoin d'un attribut non projeté ? Enchaîne avec un GetItem sur la clé de table, ou élargis la projection.
Les clés ne sont pas uniques dans un GSI — de nombreux éléments peuvent partager la même clé d'index, et les éléments qui n'ont pas l'attribut de clé d'index n'apparaissent tout simplement pas (c'est le motif d'index clairsemé).
Pagination — identique à une requête sur table : au plus 1 Mo par page, boucle LastEvaluatedKey → ExclusiveStartKey jusqu'à ce qu'il soit undefined.

À faire visuellement

Le DynamoDB Expression Builder construit la condition de clé + les cartes de noms/valeurs pour les requêtes sur index et copie le code.

Pour parcourir les index d'une table et exécuter des requêtes sur GSI depuis un formulaire — grille paginée, copie du code SDK v3 généré — télécharge DynoTable.

Exemples liés

Interroger un GSI DynamoDB en Python — la même requête sur index avec boto3.
Interroger un GSI DynamoDB avec l'AWS CLI — la même requête sur index depuis le shell.
DynamoDB Query en Node.js — interroger la table de base.
GSI vs. LSI — quel type d'index convient au schéma d'accès.
Pourquoi les GSI sont à cohérence à terme — le décalage de réplication expliqué.
"The table does not have the specified index" — le nom de l'index ne correspond pas (les noms de GSI sont sensibles à la casse).
"Consistent reads are not supported on global secondary indexes" — pourquoi le drapeau de lecture cohérente échoue sur un GSI.

References

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.