Node.js (AWS SDK v3) ile DynamoDB GSI Sorgulama

Bir GSI sorgusu, normal bir Query artı IndexName'dir; sonra iki şey bir tablo sorgusu gibi davranmayı bırakır: alışkın olduğunuz tutarlılık bayrağı bir hataya dönüşür ve sayfalama imleci fazladan bir öznitelik kazanır. Burada AlbumTitle-index, şarkıları albüme göre getirir; temel tablonun (Artist + SongTitle) bir tarama olmadan yapamayacağı bir şey.

Kod

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

İmleç iki değil, üç öznitelik genişliğindedir

Yukarıdaki döngüyü tek bir albümdeki 300 şarkıya karşı çalıştırın ve geri verdiği LastEvaluatedKey'i inceleyin:

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

Bir GSI anahtarı benzersiz değildir, dolayısıyla indeks anahtarı tek başına bir taramayı sürdüremez. DynamoDB, indeks anahtarını ve temel tablo anahtarını birlikte döndürür ve ikisi de ExclusiveStartKey içinde dokunulmadan geri gitmelidir. "Gördüğüm son sıralama anahtarı"nı saklayan elle yazılmış bir imlecin bir tabloda çalışıp bir indekste sessizce öğe kaybetmesinin ya da tekrarlamasının nedeni budur — ve tablo anahtarı, sızdırmak istemeyeceğiniz bir kullanıcı kimliği olduğunda o anahtarı bir istemcide kalıcılaştırmanın neden kötü bir fikir olduğunun da.

ConsistentRead: true bir yükseltme değil, 400'dür

İçgüdü, güçlü tutarlı bir okumanın daha fazla kapasiteye mal olduğu ve size daha taze veri verdiği yönündedir. Bir GSI üzerinde size isteğe mal olur:

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

API başvurusu da aynı ölçüde açıktır: "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." Bir GSI üzerindeki Scan aynı bayrağı aynı mesajla reddeder. Yerel ikincil indeksler ise onu kabul eder.

2026-07-28 tarihinde node v24.18.0 üzerinde @aws-sdk/client-dynamodb 3.1095.0 ile DynamoDB Local'a (amazon/dynamodb-local) karşı yeniden üretildi. Hata metni ve anahtar yapıları motorun kendi çıktısıdır.

Açıklama

• IndexName, TableName'in yerini almaz. İkisi de aynı komuta girer ve KeyConditionExpression sonrasında tablonunkini değil, indeksin bölüm anahtarını (AlbumTitle) adlandırır — bir tablo sorgusuyla aynı işleç kümesiyle.
• İzdüşümü alırsınız, başka bir şey değil. Bir GSI sorgusu, indeksin izdüşürdüğünü (ALL, KEYS_ONLY ya da INCLUDE listesi) döndürür ve API başvurusuna göre "global secondary index queries cannot fetch attributes from the parent table". Eksik bir öznitelik, temel anahtar üzerinde bir takip GetItem'ı ya da daha geniş bir izdüşüm ve yeniden oluşturulmuş bir indeks demektir.
• İndeks anahtarı olmayan öğeler hiç görünmez. Bu, seyrek indeks desenidir ve bir özelliktir: yalnızca status = "OPEN" olan satırları indeksleyin, GSI küçük kalsın. Aynı zamanda bir GSI sorgusunun beklediğinizden daha az öğe döndürüp hiç hata vermemesinin de nedenidir.
• Çoğaltma eşzamansızdır, dolayısıyla az önce tabloya inen bir yazma henüz indekste olmayabilir. Yazma-sonrası-okuma yollarında sıkı bir döngüde yeniden denemek yerine bunu hesaba katın.

Görsel olarak yapın

Bir GSI'yı sonradan eklemek bunu öğrenmenin pahalı yoludur. Tek tablo tasarımı planlayıcısı erişim desenlerinizi alır ve hangilerinin bir indeks anahtarına ihtiyaç duyduğunu, hangilerine temel tablonun zaten hizmet ettiğini hesaplar.

Bir tablonun indekslerine göz atmak ve GSI sorgularını bir formdan, sayfalanmış bir ızgarayla çalıştırmak için DynoTable'ı indirin.

İlgili örnekler

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

Kaynaklar

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