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

Query pada GSI adalah Query biasa plus IndexName, lalu dua hal berhenti berperilaku seperti query pada tabel: flag konsistensi yang biasa Anda pakai berubah menjadi error, dan cursor paginasinya bertambah satu atribut. Di sini AlbumTitle-index mengambil lagu berdasarkan album, yang tak bisa dilakukan tabel dasarnya (Artist + SongTitle) tanpa sebuah scan.

Kode

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

Cursor-nya selebar tiga atribut, bukan dua

Jalankan loop di atas terhadap 300 lagu pada satu album lalu periksa LastEvaluatedKey yang dikembalikannya:

table query  -> ['Artist', 'SongTitle']
GSI query    -> ['AlbumTitle', 'Artist', 'SongTitle']

Key sebuah GSI tidak unik, jadi key index saja tak bisa melanjutkan sebuah scan. DynamoDB mengembalikan key index dan key tabel dasar sekaligus, dan keduanya harus dikembalikan ke ExclusiveStartKey tanpa disentuh. Inilah sebabnya cursor buatan tangan yang menyimpan "sort key terakhir yang saya lihat" bekerja pada tabel tapi diam-diam kehilangan atau mengulang item pada sebuah index — dan mengapa menyimpan key itu ke klien adalah ide buruk ketika key tabelnya adalah user id yang lebih baik tidak Anda bocorkan.

ConsistentRead: true adalah 400, bukan peningkatan

Nalurinya adalah bahwa pembacaan strongly consistent memakan kapasitas lebih banyak dan Anda mendapat data yang lebih segar. Pada sebuah GSI, ia justru memakan request Anda:

ValidationException: Consistent reads are not supported on global secondary indexes
HTTP 400

API reference sama blak-blakannya: "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." Scan pada sebuah GSI menolak flag yang sama dengan pesan yang sama. Local secondary index memang menerimanya.

Direproduksi 2026-07-28 terhadap DynamoDB Local (amazon/dynamodb-local) dengan @aws-sdk/client-dynamodb 3.1095.0 pada node v24.18.0. Teks error dan bentuk key-nya adalah keluaran mesin itu sendiri.

Penjelasan

• IndexName tidak menggantikan TableName. Keduanya masuk ke command yang sama, dan KeyConditionExpression lalu menyebut partition key milik index (AlbumTitle), bukan milik tabel, dengan himpunan operator yang sama seperti query pada tabel.
• Anda mendapat projection-nya dan tidak lebih. Query pada GSI mengembalikan apa yang di-project index itu (ALL, KEYS_ONLY, atau daftar INCLUDE), dan menurut API reference "global secondary index queries cannot fetch attributes from the parent table". Atribut yang hilang berarti GetItem susulan pada key dasarnya, atau projection yang lebih lebar dan index yang dibuat ulang.
• Item yang tak punya key index tak pernah muncul. Itulah pola sparse index, dan itu sebuah fitur: index hanya baris dengan status = "OPEN" dan GSI-nya tetap kecil. Itu juga alasan sebuah query GSI bisa mengembalikan lebih sedikit item daripada yang Anda harapkan tanpa memunculkan error apa pun.
• Replikasinya asinkron, jadi penulisan yang baru saja mendarat di tabel mungkin belum ada di index. Perhitungkan itu pada jalur baca-setelah-tulis alih-alih mencoba ulang dalam loop ketat.

Lakukan secara visual

Menambahkan GSI belakangan adalah cara mahal untuk mempelajari hal ini. Perencana single-table design menerima pola akses Anda lalu menentukan mana yang butuh key index dan mana yang sudah dilayani tabel dasarnya.

Untuk menjelajahi index sebuah tabel dan menjalankan query GSI dari sebuah formulir, dengan grid berpaginasi, unduh DynoTable.

Contoh terkait

• DynamoDB Query pada GSI di Python — query index yang sama dengan boto3.
• DynamoDB Query pada GSI dengan AWS CLI — query index yang sama dari shell.
• DynamoDB Query di Node.js — melakukan query pada tabel dasarnya.
• GSI vs. LSI — jenis index mana yang cocok untuk pola akses tersebut.
• Mengapa GSI eventually consistent — lag replikasinya dijelaskan.
• "The table does not have the specified index" — nama index-nya tidak cocok (nama GSI bersifat case-sensitive).
• "Consistent reads are not supported on global secondary indexes" — mengapa flag consistent-read gagal pada sebuah GSI.

Referensi

• Query — Amazon DynamoDB API Reference
• Using Global Secondary Indexes in DynamoDB — Amazon DynamoDB Developer Guide
• Paginating table query results — Amazon DynamoDB Developer Guide