DynamoDB Query a un GSI en Python (boto3)

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 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")

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; lanza 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 get_item 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 — client.get_paginator("query") sigue LastEvaluatedKey a través de las páginas exactamente igual que en una consulta de tabla; cada page lleva una lista Items.
En la API de recurso, la misma consulta es table.query(IndexName="AlbumTitle-index", KeyConditionExpression=Key("AlbumTitle").eq("Danzon")) con valores nativos de Python.

Hazlo visualmente

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

Para explorar los índices de una tabla y ejecutar consultas a GSI desde un formulario — cuadrícula paginada, copiar como código — descarga DynoTable.

Ejemplos relacionados

DynamoDB Query a un GSI en Node.js — la misma consulta de índice con AWS SDK v3.
DynamoDB Query a un GSI con la AWS CLI — la misma consulta de índice desde el shell.
DynamoDB Query en Python — 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.