Query DynamoDB sur un GSI en Python (boto3)

Interroger un index secondaire global est une query normale 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 des chansons par album, un motif d'accès que la table de base (Artist + SongTitle) ne peut servir sans un scan.

Code

import boto3

client = boto3.client("dynamodb")

paginator = client.get_paginator("query")

items = []
for page in paginator.paginate(
    TableName="Music",
    IndexName="AlbumTitle-index",
    KeyConditionExpression="#hashKey = :hashKeyValue",
    ExpressionAttributeNames={"#hashKey": "AlbumTitle"},
    ExpressionAttributeValues={":hashKeyValue": {"S": "Danzon"}},
):
    items.extend(page["Items"])

print(f"Found {len(items)} songs on the album")

Explication

IndexName — nomme le GSI à interroger (TableName reste requis). La KeyConditionExpression utilise la clé de partition (et l'éventuelle clé de tri) de l'index — AlbumTitle ici — avec les mêmes opérateurs qu'une query de table.
Cohérence à terme uniquement — les GSI se répliquent depuis la table de base de façon asynchrone. Passer ConsistentRead=True sur une query de GSI ne la met pas à niveau ; ça lève une ValidationException. (Les index secondaires locaux, eux, supportent la cohérence forte.)
Tu n'obtiens que les attributs projetés — une query de GSI renvoie ce que l'index projette (ALL, KEYS_ONLY, ou les attributs listés par 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 get_item sur la clé de table, ou élargis la projection.
Les clés ne sont pas uniques dans un GSI — plusieurs é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 de l'index épars).
Pagination — client.get_paginator("query") suit LastEvaluatedKey de page en page exactement comme sur une query de table ; chaque page porte une liste Items.
Avec l'API resource, la même query s'écrit table.query(IndexName="AlbumTitle-index", KeyConditionExpression=Key("AlbumTitle").eq("Danzon")) avec des valeurs Python natives.

À faire visuellement

Le DynamoDB Expression Builder construit la condition de clé + les maps de noms/valeurs pour les queries d'index et copie du code boto3 exécutable.

Pour parcourir les index d'une table et exécuter des queries de GSI depuis un formulaire — grille paginée, copie du code — télécharge DynoTable.

Exemples liés

Query DynamoDB sur un GSI en Node.js — la même query d'index avec AWS SDK v3.
Query DynamoDB sur un GSI avec l'AWS CLI — la même query d'index depuis le shell.
Query DynamoDB en Python — interroger la table de base.
GSI vs. LSI — quel type d'index correspond au motif 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 d'index ne correspond pas (les noms de GSI sont sensibles à la casse).
"Consistent reads are not supported on global secondary indexes" — pourquoi le flag 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.