Interroger un GSI DynamoDB avec l'AWS CLI

Interroger un index secondaire global est un aws dynamodb query normal plus un drapeau : --index-name. 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

aws dynamodb query \
  --table-name 'Music' \
  --index-name 'AlbumTitle-index' \
  --key-condition-expression '#hashKey = :hashKeyValue' \
  --expression-attribute-names '{"#hashKey":"AlbumTitle"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Danzon"}}'

La sortie correspond aux éléments trouvés en DynamoDB JSON :

{
    "Items": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
    ],
    "Count": 2,
    "ScannedCount": 2
}

Explication

--index-name — nomme le GSI à interroger (--table-name reste obligatoire). La --key-condition-expression 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. Ajouter --consistent-read à 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.
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é).
La pagination est automatique — la CLI suit les jetons de pagination du service en coulisses et affiche le résultat combiné. Utilise --max-items pour plafonner la sortie (un NextToken apparaît ; reprends avec --starting-token), ou --no-paginate pour un seul appel de service.

À faire visuellement

Le DynamoDB Expression Builder construit la condition de clé + les cartes de noms/valeurs pour les requêtes sur index et te remet une commande CLI prête à l'emploi.

Pour parcourir les index d'une table et exécuter des requêtes sur GSI depuis un formulaire — grille paginée, copie en tant que CLI — télécharge DynoTable.

Exemples liés

Interroger un GSI DynamoDB en Node.js — la même requête sur index avec l'AWS SDK v3.
Interroger un GSI DynamoDB en Python — la même requête sur index avec boto3.
DynamoDB Query avec l'AWS CLI — 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.