DynamoDB GSI in Python (boto3) abfragen

Einen globalen Sekundärindex abzufragen ist ein normales query plus einem Parameter: IndexName. 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

import boto3

client = boto3.client("dynamodb")

paginator = client.get_paginator("query")

items = []
for page in paginator.paginate(
    TableName="Music",
    IndexName="AlbumTitle-index",
    KeyConditionExpression="#hashKey = :hashKeyValue",
    ExpressionAttributeNames={"#hashKey": "AlbumTitle"},
    ExpressionAttributeValues={":hashKeyValue": {"S": "Danzon"}},
):
    items.extend(page["Items"])

print(f"Found {len(items)} songs on the album")

Erklärung

• IndexName — benennt den abzufragenden GSI (TableName ist weiterhin erforderlich). Die KeyConditionExpression 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. ConsistentRead=True bei einer GSI-Abfrage zu übergeben wertet sie nicht auf; sie löst eine ValidationException aus. (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. Brauchst du ein nicht projiziertes Attribut? Setze mit get_item auf dem Tabellenschlüssel nach, oder erweitere die Projektion.
• 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 — client.get_paginator("query") folgt LastEvaluatedKey über die Seiten genau wie bei einer Tabellenabfrage; jede page trägt eine Items-Liste.
• Auf der Resource-API ist dieselbe Abfrage table.query(IndexName="AlbumTitle-index", KeyConditionExpression=Key("AlbumTitle").eq("Danzon")) mit nativen Python-Werten.

Visuell erledigen

Der DynamoDB Expression Builder baut die Schlüsselbedingung + Name-/Wert-Maps für Index-Abfragen und kopiert lauffähigen boto3-Code.

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

Verwandte Beispiele

• DynamoDB GSI in Node.js abfragen — dieselbe Index-Abfrage mit AWS SDK v3.
• DynamoDB GSI mit der AWS CLI abfragen — dieselbe Index-Abfrage aus der Shell.
• DynamoDB Query in Python — 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
• DynamoDB.Paginator.Query — Boto3 documentation
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide

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