Node.js (AWS SDK v3) ile DynamoDB Query

AWS SDK v3'te eksiksiz bir Query, çoğu parçacığın gösterdiği tek client.send() değil, aşağıdaki do/while'dır: bir sayfa 1 MB ile sınırlıdır ve bölümün geri kalanı ancak LastEvaluatedKey'i geri beslerseniz gelir. Query'nin ne zaman doğru okuma olduğunu görmek için bkz. Query ile Scan karşılaştırması.

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',
      KeyConditionExpression: '#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)',
      ExpressionAttributeNames: {
        '#hashKey': 'Artist',
        '#rangeKey': 'SongTitle'
      },
      ExpressionAttributeValues: {
        ':hashKeyValue': {S: 'Arturo Sandoval'},
        ':rangeKeyValue': {S: 'C'}
      },
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

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

console.log(`Found ${items.length} items`);

Döngü gerçekte ne yapıyor

Her şarkı ~3,9 KB ve hepsi Artist = "Arturo Sandoval" altında olan 600 şarkılık bir düzeneğe karşı, yukarıdaki döngü üç istek gönderir:

271'i kimse yapılandırmadı. 1 MB'ın tükendiği yer orasıdır, dolayısıyla sayfa sınırı öğe boyutunuz değiştikçe kayar. Bugün bir kez sayfalayan bir bölüm, bir öznitelik ekledikten sonra iki kez sayfalar ve tek bir send() çağrısından response.Items okuyan kod, 600 şarkının 271'ini hiç hata vermeden sessizce döndürür.

Şimdi aynı sorguya Limit: 10 ve Year üzerinde bir FilterExpression ekleyin:

Count: 0   ScannedCount: 10   ConsumedCapacity: 5   LastEvaluatedKey: set

On öğe değerlendirildi, sıfır öğe döndürüldü ve istek yine de okuma kapasitesine mal oldu. Limit, DynamoDB'nin ne okuduğunu sınırlar ve filtre bundan sonra çalışır, dolayısıyla "bana 10 sonuç ver" anlamında seçilmiş bir Limit size 0 ile 10 arasında bir şey verir.

2026-07-28 tarihinde node v24.18.0 üzerinde @aws-sdk/client-dynamodb 3.1095.0 ile DynamoDB Local'a (amazon/dynamodb-local) karşı ölçüldü. Sayımlar ve kapasite motorun kendi yanıt alanlarıdır.

Açıklama

• İlk geçişte ExclusiveStartKey: lastEvaluatedKey undefined'dır ve bu bilinçlidir: v3 serileştirici undefined üyeleri düşürür, dolayısıyla aynı nesne değişmezi hem ilk istek hem de her takip için çalışır. "Baştan başla"nın akla gelen tahmini olan {} ile değiştirmek, ValidationException: The provided starting key is invalid ile başarısız olur.
• @aws-sdk/client-dynamodb sizin yerinize asla marshal etmez. Değerler {S: 'Arturo Sandoval'} olarak girer ve öğeler aynı şekilde geri gelir. DocumentClient'ı çekmemenin karşılığı budur; düz JS nesneleri yazmayı yeğlerseniz, uzanacağınız sarmalayıcı @aws-sdk/lib-dynamodb'dir.
• Sayılar gidiş-dönüşten dize olarak sağ çıkar. {N: '9007199254740993'} değerini @aws-sdk/util-dynamodb'deki unmarshall ile çözmek, kayıplı bir number değil bir JS bigint döndürür; {wrapNumbers: true} geçirirseniz bunun yerine {value: '9007199254740993'} alırsınız. Her hâlükârda, boyutunu denetlemediğiniz bir DynamoDB N değerini Number() ile sarmayın.
• KeyConditionExpression, bölüm anahtarında bir eşitlik artı en fazla bir sıralama anahtarı koşulu (=, <, <=, >, >=, BETWEEN, begins_with) alır. Başka her şeyin yeri, okumadan sonra çalışan bir FilterExpression'dır.
• ScanIndexForward: false sıralama anahtarı sırasını ters çevirir; artan sıra varsayılandır. IndexName aynı komutu bir ikincil indekse çevirir.

Görsel olarak yapın

DynamoDB sorgu oluşturucu bu yapının tamamını — anahtar koşulu, ad ve değer haritaları ve LastEvaluatedKey döngüsü — çalıştırılabilir bir SDK v3 programı olarak üretir, böylece sayfalama unuttuğunuz kısım olmaz.

Gerçek tablolara karşı bir GUI'de, anahtar koşulu formu ve sayfalanmış bir sonuç ızgarasıyla sorgu çalıştırmak için DynoTable'ı indirin.

İlgili kılavuzlar

• Query ile Scan karşılaştırması — Query'nin neden doğru varsayılan olduğu.
• Anahtar koşulu ifadeleri — her geçerli bölüm/sıralama anahtarı işleci.
• "Query condition missed key schema element" — anahtar koşulu yanlış özniteliği adlandırıyor ya da bölüm anahtarını atlıyor.
• "Query key condition not supported" — anahtar koşulunun kullanamayacağı bir işleç, örneğin contains ya da ikinci bir sıralama anahtarı koşulu.

Kaynaklar

• Query — Amazon DynamoDB API Reference
• QueryCommand — AWS SDK for JavaScript v3 Reference
• Querying tables — Amazon DynamoDB Developer Guide
• Key condition expressions for Query — Amazon DynamoDB Developer Guide