Query su un GSI DynamoDB con la AWS CLI

Interrogare un indice secondario globale è un normale aws dynamodb query più un flag: --index-name. La condizione di chiave punta allora alle chiavi dell'indice, non a quelle della tabella — qui AlbumTitle-index ci permette di recuperare i brani per album, un pattern di accesso che la tabella base (Artist + SongTitle) non può servire senza uno scan.

Codice

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"}}'

L'output sono gli Item corrispondenti in JSON DynamoDB:

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

Spiegazione

Alla tabella base non viene fatturato nulla per questa query. Aggiungi --return-consumed-capacity INDEXES e la ripartizione è esplicita:

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

Zero sulla tabella, tutto sull'indice. Un GSI è una tabella separata con il suo schema di chiave, le sue partizioni e la sua capacità, e leggerlo non tocca mai la tabella base. È anche il motivo per cui un GSI ha una storia di throttling tutta sua: un GSI sottoposto a throttling può fare throttling sulle scritture della tabella base anche se le letture non si incrociano mai.

--consistent-read viene rifiutato, non declassato. I GSI si replicano in modo asincrono e non esiste alcun flag che lo cambi:

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

Codice di uscita 254. Il riferimento dell'API lo dice in anticipo: "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" (recuperato il 2026-07-28). Gli indici secondari locali invece lo accettano, ed è uno dei pochi motivi reali per scegliere un LSI. Il ritardo in sé è trattato in perché i GSI sono eventualmente coerenti.

Gli Item privi della chiave dell'indice semplicemente non sono nell'indice. Contati sulla stessa tabella: 35 Item nella tabella base, 32 in AlbumTitle-index. I tre mancanti non hanno affatto un attributo AlbumTitle, confermato con uno scan su attribute_not_exists(AlbumTitle). Nulla è andato in errore e nulla ha avvertito. Questo è il pattern dell'indice sparso, ed è una scelta di progettazione deliberata quando scrivi l'attributo-flag solo per le righe che vuoi indicizzare, e un bug silenzioso di perdita di dati quando dai per scontato che l'indice rispecchi la tabella.

Ottieni solo ciò che l'indice proietta. "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" (recuperato il 2026-07-28). Su un indice KEYS_ONLY o INCLUDE questo significa un secondo get-item per ogni risultato per completare il resto, cioè l'N+1 che stavi cercando di evitare. La proiezione è fissata alla creazione dell'indice e non può essere cambiata dopo; vedi le proiezioni degli indici prima di sceglierne una.

Le chiavi di un indice non sono univoche. Molti Item possono condividere lo stesso AlbumTitle, quindi una query su un GSI restituisce una collezione dove l'equivalente query sulla tabella restituirebbe un singolo Item. Non esiste alcun get-item su un GSI, esattamente per questo motivo.

La paginazione si comporta come su qualsiasi query di tabella, inclusa l'abitudine della CLI di riportare il ConsumedCapacity di una sola pagina per un risultato paginato automaticamente. È misurato in dettaglio in Query con la AWS CLI; i flag qui sono gli stessi.

Fallo visivamente

Una query su indice ha più parti in movimento di una query sulla tabella: l'indice giusto, i nomi delle chiavi dell'indice e una proiezione che potrebbe non portare gli attributi che ti servono. Il DynamoDB Query Builder gratuito ti fa scegliere l'indice, costruisce la condizione di chiave sulle sue chiavi ed emette il comando CLI.

Per vedere quali indici ha davvero una tabella e interrogarli sui tuoi dati — proiezioni elencate, una griglia che pagina mentre scorri, richiesta ricopiabile come comando CLI — scarica DynoTable.

Esempi correlati

Query su un GSI DynamoDB in Node.js — la stessa query su indice con AWS SDK v3.
Query su un GSI DynamoDB in Python — la stessa query su indice con boto3.
GSI vs. LSI — quale tipo di indice si adatta al pattern di accesso.
"The table does not have the specified index" — il nome dell'indice non corrisponde (i nomi dei GSI sono case-sensitive).
"Consistent reads are not supported on global secondary indexes" — perché il flag di lettura coerente fallisce su un GSI.

Riferimenti

Riprodotto il 2026-07-28 con aws-cli/2.36.9 su DynamoDB Local (amazon/dynamodb-local) sulla porta 9000, su una tabella Music con un AlbumTitle-index che proietta ALL. Il testo dell'errore, la ripartizione della capacità e i conteggi degli Item sono output catturato.