DynamoDB Query a un GSI con la AWS CLI

Consultar un índice secundario global es un aws dynamodb query normal más una opción: --index-name. 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

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 salida son los items coincidentes en DynamoDB JSON:

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

Explicación

--index-name — nombra el GSI a consultar (--table-name sigue siendo obligatorio). El --key-condition-expression 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. Añadir --consistent-read a 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.
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).
La paginación es automática — la CLI sigue los tokens de paginación del servicio entre bastidores e imprime el resultado combinado. Usa --max-items para limitar la salida (aparece un NextToken; reanuda con --starting-token), o --no-paginate para una única llamada al servicio.

Hazlo visualmente

El DynamoDB Expression Builder construye la condición de clave + los mapas de nombres/valores para consultas de índice y te da un comando de CLI listo para ejecutar.

Para explorar los índices de una tabla y ejecutar consultas a GSI desde un formulario — cuadrícula paginada, copiar como CLI — 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 en Python — la misma consulta de índice con boto3.
DynamoDB Query con la AWS CLI — 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.