Consultar un GSI de DynamoDB con la AWS CLI

Consultar un índice secundario global es un aws dynamodb query normal más un flag: --index-name. La condición de clave apunta entonces a las claves del índice, no a las de la tabla — aquí AlbumTitle-index nos deja recuperar canciones por álbum, un patrón de acceso que la tabla base (Artist + SongTitle) no puede servir sin un Scan.

Código

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 elementos coincidentes en JSON de DynamoDB:

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

Explicación

A la tabla base no se le factura nada por esta consulta. Añade --return-consumed-capacity INDEXES y el reparto es explícito:

"ConsumedCapacity": {
    "CapacityUnits": 132.0,
    "Table": {"CapacityUnits": 0.0},
    "GlobalSecondaryIndexes": {"AlbumTitle-index": {"CapacityUnits": 132.0}}
}

Cero contra la tabla, todo contra el índice. Un GSI es una tabla aparte con su propio esquema de clave, sus propias particiones y su propia capacidad, y leerlo nunca toca la tabla base. También por eso un GSI tiene su propia historia de limitaciones: un GSI limitado puede limitar las escrituras de la tabla base aunque las lecturas nunca crucen.

--consistent-read se rechaza, no se degrada. Los GSI replican de forma asíncrona y no hay flag que lo cambie:

aws: [ERROR]: An error occurred (ValidationException) when calling the Query operation: Consistent reads are not supported on global secondary indexes

Código de salida 254. La API Reference lo dice por adelantado: "Strongly consistent reads are not supported on global secondary indexes. If you query a global secondary index with ConsistentRead set to true, you will receive a ValidationException" (consultada el 2026-07-28). Los índices secundarios locales sí lo aceptan, que es una de las pocas razones reales para elegir un LSI. El retraso en sí está cubierto en por qué los GSI son eventualmente consistentes.

Los elementos sin la clave del índice simplemente no están en el índice. Contado sobre la misma tabla: 35 elementos en la tabla base, 32 en AlbumTitle-index. Los tres que faltan no tienen atributo AlbumTitle en absoluto, confirmado con un Scan sobre attribute_not_exists(AlbumTitle). Nada dio error y nada avisó. Este es el patrón de índice disperso, y es diseño deliberado cuando escribes el atributo bandera solo para las filas que quieres indexar, y un bug silencioso de pérdida de datos cuando das por hecho que el índice refleja la tabla.

Solo obtienes lo que el índice proyecta. "If you query or scan a global secondary index, you can only request attributes that are projected into the index. Global secondary index queries cannot fetch attributes from the parent table" (consultada el 2026-07-28). En un índice KEYS_ONLY o INCLUDE eso significa un segundo get-item por resultado para rellenar el resto, que es justo el N+1 que intentabas evitar. La proyección se fija al crear el índice y no puede cambiarse después; consulta proyecciones de índice antes de elegir una.

Las claves de índice no son únicas. Muchos elementos pueden compartir un mismo AlbumTitle, así que una consulta a un GSI devuelve una colección donde la consulta equivalente a la tabla devolvería un solo elemento. No existe tal cosa como un get-item contra un GSI, precisamente por esto.

La paginación se comporta como en cualquier consulta a una tabla, incluida la costumbre de la CLI de informar del ConsumedCapacity de una sola página en un resultado autopaginado. Eso está medido en detalle en Query con la AWS CLI; los flags son los mismos aquí.

Hazlo visualmente

Una consulta a un índice tiene más piezas móviles que una a una tabla: el índice correcto, los nombres de clave propios del índice y una proyección que puede no llevar los atributos que necesitas. El DynamoDB Query Builder gratuito te deja elegir el índice, construye la condición de clave contra sus claves y emite el comando de la CLI.

Para ver qué índices tiene realmente una tabla y consultarlos contra tus propios datos — proyecciones listadas, una cuadrícula que pagina mientras haces scroll, copiar la petición de vuelta como comando de la CLI — descarga DynoTable.

Ejemplos relacionados

Consultar un GSI de DynamoDB en Node.js — la misma consulta al índice con AWS SDK v3.
Consultar un GSI de DynamoDB en Python — la misma consulta al índice con boto3.
GSI frente a LSI — qué tipo de índice encaja con el patrón de acceso.
"The table does not have the specified index" — el nombre del índice no coincide (los nombres de GSI distinguen mayúsculas).
"Consistent reads are not supported on global secondary indexes" — por qué el flag de lectura consistente falla en un GSI.

Referencias

Reproducido el 2026-07-28 con aws-cli/2.36.9 contra DynamoDB Local (amazon/dynamodb-local) en el puerto 9000, sobre una tabla Music con un AlbumTitle-index que proyecta ALL. El texto del error, el reparto de capacidad y los recuentos de elementos son salida capturada.