DynamoDB Query auf einem GSI mit der AWS CLI

Einen Global Secondary Index abzufragen ist eine ganz normale aws dynamodb query plus ein Flag: --index-name. Die Key Condition zielt dann auf die Keys des Index, nicht auf die der Tabelle — hier lässt uns AlbumTitle-index Songs nach Album holen, ein Zugriffsmuster, das die Basistabelle (Artist + SongTitle) ohne Scan nicht bedienen kann.

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

Die Ausgabe sind die passenden Items in DynamoDB JSON:

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

Erklärung

Der Basistabelle wird für diese Abfrage nichts berechnet. Ergänze --return-consumed-capacity INDEXES, und die Aufteilung wird explizit:

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

Null gegen die Tabelle, alles gegen den Index. Ein GSI ist eine eigene Tabelle mit eigenem Key-Schema, eigenen Partitionen und eigener Kapazität, und ihn zu lesen berührt die Basistabelle nie. Deshalb hat ein GSI auch seine eigene Drosselungsgeschichte: ein gedrosselter GSI kann Writes auf der Basistabelle drosseln, obwohl Reads nie hinüberreichen.

--consistent-read wird abgelehnt, nicht heruntergestuft. GSIs replizieren asynchron, und es gibt kein Flag, das daran etwas ändert:

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

Exit-Code 254. Die API-Referenz sagt es vorab genauso: "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" (abgerufen am 2026-07-28). Local Secondary Indexes akzeptieren es sehr wohl, was einer der wenigen echten Gründe ist, einen LSI zu wählen. Die Verzögerung selbst behandelt warum GSIs letztendlich konsistent sind.

Items ohne den Index-Key stehen schlicht nicht im Index. Auf derselben Tabelle gezählt: 35 Items in der Basistabelle, 32 im AlbumTitle-index. Den drei fehlenden fehlt das Attribut AlbumTitle komplett, bestätigt durch einen Scan auf attribute_not_exists(AlbumTitle). Nichts hat einen Fehler geworfen und nichts hat gewarnt. Das ist das Muster Sparse Index — bewusstes Design, wenn du das Flag-Attribut nur für die Zeilen schreibst, die indiziert sein sollen, und ein stiller Datenverlust-Bug, wenn du annimmst, der Index spiegele die Tabelle.

Du bekommst nur, was der Index projiziert. "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" (abgerufen am 2026-07-28). Auf einem KEYS_ONLY- oder INCLUDE-Index heißt das ein zweites get-item pro Ergebnis, um den Rest nachzuladen — genau das N+1, das du vermeiden wolltest. Die Projektion steht mit dem Anlegen des Index fest und lässt sich danach nicht mehr ändern; siehe Index-Projektionen, bevor du dich entscheidest.

Index-Keys sind nicht eindeutig. Viele Items können sich einen AlbumTitle teilen, eine GSI-Abfrage liefert also eine Menge, wo die gleichwertige Tabellenabfrage ein einzelnes Item zurückgäbe. Ein get-item gegen einen GSI gibt es aus genau diesem Grund nicht.

Die Paginierung verhält sich wie bei jeder Tabellenabfrage, inklusive der Angewohnheit der CLI, für ein automatisch paginiertes Ergebnis die ConsumedCapacity einer einzigen Seite zu melden. Das ist im Detail auf Query mit der AWS CLI gemessen; die Flags sind hier dieselben.

Mach es visuell

Eine Index-Abfrage hat mehr bewegliche Teile als eine Tabellenabfrage: der richtige Index, die eigenen Key-Namen des Index und eine Projektion, die vielleicht nicht die Attribute mitbringt, die du brauchst. Der kostenlose DynamoDB Query Builder lässt dich den Index auswählen, baut die Key Condition gegen dessen Keys und gibt den CLI-Befehl aus.

Um zu sehen, welche Indizes eine Tabelle tatsächlich hat, und sie gegen deine eigenen Daten abzufragen — Projektionen aufgelistet, ein Grid, das beim Scrollen nachlädt, die Anfrage als CLI-Befehl zurückkopieren — lade DynoTable herunter.

Referenzen

Am 2026-07-28 mit aws-cli/2.36.9 gegen DynamoDB Local (amazon/dynamodb-local) auf Port 9000 reproduziert, auf einer Music-Tabelle mit einem AlbumTitle-index, der ALL projiziert. Der Fehlertext, die Kapazitätsaufteilung und die Item-Zahlen sind aufgezeichnete Ausgabe.

DynamoDB Query auf einem GSI mit der AWS CLI

Code

Erklärung

Mach es visuell

Verwandte Beispiele

Referenzen

Diesen Request visuell bauen