DynamoDB GSI mit der AWS CLI abfragen

Einen globalen Sekundärindex abzufragen ist ein normales aws dynamodb query plus einem Flag: --index-name. Die Schlüsselbedingung zielt dann auf die Schlüssel des Index, nicht der Tabelle — hier lässt uns AlbumTitle-index Songs nach Album abrufen, ein Zugriffsmuster, das die Basistabelle (Artist + SongTitle) ohne einen 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 als DynamoDB JSON:

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

Erklärung

• --index-name — benennt den abzufragenden GSI (--table-name ist weiterhin erforderlich). Die --key-condition-expression nutzt den Partitions- (und optionalen Sortier-)Schlüssel des Index — hier AlbumTitle — mit denselben Operatoren wie eine Tabellenabfrage.
• Nur letztendliche Konsistenz — GSIs replizieren asynchron von der Basistabelle. --consistent-read bei einer GSI-Abfrage hinzuzufügen wertet sie nicht auf; sie schlägt mit einer ValidationException fehl. (Local Secondary Indexes unterstützen starke Konsistenz.)
• Du bekommst nur projizierte Attribute — eine GSI-Abfrage gibt zurück, was der Index projiziert (ALL, KEYS_ONLY oder die per INCLUDE gelisteten Attribute) und kann den Rest nicht aus der Basistabelle holen.
• Schlüssel sind in einem GSI nicht eindeutig — viele Items können denselben Indexschlüssel teilen, und Items, denen das Indexschlüssel-Attribut fehlt, erscheinen einfach nicht (das ist das Sparse-Index-Muster).
• Pagination ist automatisch — die CLI folgt den Pagination-Tokens des Service hinter den Kulissen und gibt das kombinierte Ergebnis aus. Nutze --max-items, um die Ausgabe zu begrenzen (ein NextToken erscheint; fortsetzen mit --starting-token), oder --no-paginate für einen einzelnen Service-Aufruf.

Visuell erledigen

Der DynamoDB Expression Builder baut die Schlüsselbedingung + Name-/Wert-Maps für Index-Abfragen und liefert dir einen sofort lauffähigen CLI-Befehl.

Um die Indizes einer Tabelle zu durchsuchen und GSI-Abfragen aus einem Formular auszuführen — paginiertes Raster, Copy-as-CLI — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB GSI in Node.js abfragen — dieselbe Index-Abfrage mit AWS SDK v3.
• DynamoDB GSI in Python abfragen — dieselbe Index-Abfrage mit boto3.
• DynamoDB Query mit der AWS CLI — Abfrage der Basistabelle.
• GSI vs. LSI — welcher Indextyp zum Zugriffsmuster passt.
• Warum GSIs letztendlich konsistent sind — die Replikationsverzögerung erklärt.
• "The table does not have the specified index" — der Indexname passt nicht (GSI-Namen sind case-sensitiv).
• "Consistent reads are not supported on global secondary indexes" — warum das Consistent-Read-Flag bei einem GSI fehlschlägt.

References

• Query — Amazon DynamoDB API Reference
• query — AWS CLI Command Reference
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
• Using AWS CLI pagination options — AWS CLI User Guide

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.