DynamoDB GSI in Node.js (AWS SDK v3) 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 {DynamoDBClient, QueryCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const items = [];
let lastEvaluatedKey;

do {
  const response = await client.send(
    new QueryCommand({
      TableName: 'Music',
      IndexName: 'AlbumTitle-index',
      KeyConditionExpression: '#hashKey = :hashKeyValue',
      ExpressionAttributeNames: {
        '#hashKey': 'AlbumTitle'
      },
      ExpressionAttributeValues: {
        ':hashKeyValue': {S: 'Danzon'}
      },
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

  items.push(...(response.Items ?? []));
  lastEvaluatedKey = response.LastEvaluatedKey;
} while (lastEvaluatedKey);

console.log(`Found ${items.length} 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 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. Brauchst du ein nicht projiziertes Attribut? Setze mit GetItem 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 — identisch zu einer Tabellenabfrage: höchstens 1 MB pro Seite, schleife LastEvaluatedKey → ExclusiveStartKey, bis er undefined ist.

Visuell erledigen

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

Um die Indizes einer Tabelle zu durchsuchen und GSI-Abfragen aus einem Formular auszuführen — paginiertes Raster, kopiere den generierten SDK-v3-Code — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB GSI in Python abfragen — dieselbe Index-Abfrage mit boto3.
• DynamoDB GSI mit der AWS CLI abfragen — dieselbe Index-Abfrage aus der Shell.
• DynamoDB Query in Node.js — 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
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
• Paginating table query results — Amazon DynamoDB Developer Guide

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