DynamoDB Query GSI di Node.js (AWS SDK v3)

Mengkueri sebuah global secondary index adalah Query biasa ditambah satu parameter: IndexName. Key condition kemudian menargetkan key index, bukan key tabel — di sini AlbumTitle-index memungkinkan kita mengambil lagu berdasarkan album, sebuah pola akses yang tidak bisa dilayani base table (Artist + SongTitle) tanpa scan.

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`);

Penjelasan

IndexName — menyebut GSI yang dikueri (TableName tetap wajib). KeyConditionExpression menggunakan partition key index (dan sort key opsional) — AlbumTitle di sini — dengan operator yang sama seperti kueri tabel.
Hanya eventual consistency — GSI mereplikasi dari base table secara asinkron. Melewatkan ConsistentRead: true pada kueri GSI tidak meningkatkannya; ia gagal dengan ValidationException. (Local secondary index mendukung strong consistency.)
Anda hanya mendapat atribut yang diproyeksikan — kueri GSI mengembalikan apa yang diproyeksikan index (ALL, KEYS_ONLY, atau atribut yang tercantum INCLUDE) dan tidak bisa mengambil sisanya dari base table. Butuh atribut yang tidak diproyeksikan? Tindak lanjuti dengan GetItem pada key tabel, atau perlebar proyeksi.
Key tidak unik di GSI — banyak item bisa berbagi key index yang sama, dan item yang tidak memiliki atribut key index tidak akan muncul (itulah pola sparse-index).
Paginasi — identik dengan kueri tabel: paling banyak 1 MB per halaman, loop LastEvaluatedKey → ExclusiveStartKey hingga menjadi undefined.

Lakukan secara visual

DynamoDB Expression Builder membangun key condition + map name/value untuk kueri index dan menyalin kodenya.

Untuk menelusuri index sebuah tabel dan menjalankan kueri GSI dari sebuah form — grid berpaginasi, salin kode SDK v3 yang dihasilkan — unduh DynoTable.

Contoh terkait

DynamoDB Query GSI di Python — kueri index yang sama dengan boto3.
DynamoDB Query GSI dengan AWS CLI — kueri index yang sama dari shell.
DynamoDB Query di Node.js — mengkueri base table.
GSI vs. LSI — tipe index mana yang cocok dengan pola akses.
Mengapa GSI eventually consistent — lag replikasi dijelaskan.
"The table does not have the specified index" — nama index tidak cocok (nama GSI case-sensitive).
"Consistent reads are not supported on global secondary indexes" — mengapa flag consistent-read gagal pada GSI.

References

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.