Node.js'te DynamoDB'de GSI Sorgulama (AWS SDK v3)

Bir global ikincil indeksi sorgulamak, normal bir Query artı bir parametredir: IndexName. Anahtar koşulu bu durumda tablonun değil, indeksin anahtarlarını hedefler — burada AlbumTitle-index, temel tablonun (Artist + SongTitle) bir tarama olmadan hizmet edemeyeceği bir erişim deseni olan, şarkıları albüme göre getirmemizi sağlar.

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

Açıklama

• IndexName — sorgulanacak GSI'yı adlandırır (TableName yine de zorunludur). KeyConditionExpression, bir tablo sorgusuyla aynı operatörlerle indeksin bölüm (ve isteğe bağlı sıralama) anahtarını — burada AlbumTitle — kullanır.
• Yalnızca nihai tutarlılık — GSI'lar temel tablodan eşzamansız olarak çoğaltılır. Bir GSI sorgusunda ConsistentRead: true geçirmek onu yükseltmez; bir ValidationException ile başarısız olur. (Yerel ikincil indeksler güçlü tutarlılığı destekler.)
• Yalnızca yansıtılan öznitelikleri alırsınız — bir GSI sorgusu, indeksin yansıttığını (ALL, KEYS_ONLY veya INCLUDE ile listelenen öznitelikler) döndürür ve gerisini temel tablodan getiremez. Yansıtılmamış bir özniteliğe mi ihtiyacınız var? Tablo anahtarında bir GetItem ile devam edin ya da projeksiyonu genişletin.
• Bir GSI'da anahtarlar benzersiz değildir — birçok öğe aynı indeks anahtarını paylaşabilir ve indeks anahtarı özniteliği eksik olan öğeler basitçe görünmez (bu, seyrek-indeks desenidir).
• Sayfalama — bir tablo sorgusuyla aynıdır: sayfa başına en fazla 1 MB, undefined olana kadar LastEvaluatedKey → ExclusiveStartKey döngüsü.

Görsel olarak yapın

DynamoDB Expression Builder, indeks sorguları için anahtar koşulunu + ad/değer eşlemelerini oluşturur ve kodu kopyalar.

Bir tablonun indekslerini gezinmek ve bir formdan GSI sorguları çalıştırmak için — sayfalanmış ızgara, üretilen SDK v3 kodunu kopyalama — DynoTable'ı indirin.

İlgili örnekler

• Python'da DynamoDB'de GSI Sorgulama — boto3 ile aynı indeks sorgusu.
• AWS CLI ile DynamoDB'de GSI Sorgulama — kabuktan aynı indeks sorgusu.
• Node.js'te DynamoDB Query — temel tabloyu sorgulama.
• GSI ve LSI — erişim desenine hangi indeks türünün uyduğu.
• GSI'lar neden nihai tutarlıdır — çoğaltma gecikmesinin açıklaması.
• "The table does not have the specified index" — indeks adı eşleşmiyor (GSI adları büyük/küçük harf duyarlıdır).
• "Consistent reads are not supported on global secondary indexes" — tutarlı okuma bayrağının bir GSI'da neden başarısız olduğu.

References

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

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.