DynamoDB Query di Node.js (AWS SDK v3)

Sebuah Query yang lengkap di AWS SDK v3 adalah do/while di bawah, bukan client.send() tunggal yang ditampilkan kebanyakan cuplikan: satu halaman dibatasi 1 MB, dan sisa partisinya hanya datang kalau Anda mengumpankan LastEvaluatedKey kembali. Lihat Query vs. Scan untuk tahu kapan Query memang pembacaan yang tepat.

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

Apa yang sebenarnya dilakukan loop itu

Terhadap fixture 600 lagu, setiap lagu ~3,9 KB dan semuanya di bawah Artist = "Arturo Sandoval", loop di atas mengirim tiga request:

Round trip	`Count`	`ScannedCount`	Unit baca	`LastEvaluatedKey`
1	271	271	128.5	ada
2	271	271	128.5	ada
3	58	58	27.5	tidak ada

Tak seorang pun mengonfigurasi angka 271. Di situlah 1 MB habis, jadi batas halamannya bergeser setiap kali ukuran item Anda berubah. Partisi yang hari ini memuat satu halaman tambahan akan memuat dua setelah Anda menambahkan satu atribut, dan kode yang membaca response.Items dari satu send() diam-diam mengembalikan 271 dari 600 lagu tanpa error apa pun.

Sekarang tambahkan Limit: 10 dan sebuah FilterExpression pada Year ke query yang sama:

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

Sepuluh item dievaluasi, nol dikembalikan, dan request-nya tetap memakan kapasitas baca. Limit membatasi apa yang dibaca DynamoDB, dan filter-nya berjalan setelah itu, jadi Limit yang dipilih dengan maksud "beri saya 10 hasil" memberi Anda antara 0 dan 10.

Diukur 2026-07-28 terhadap DynamoDB Local (amazon/dynamodb-local) dengan @aws-sdk/client-dynamodb 3.1095.0 pada node v24.18.0. Angka hitungan dan kapasitasnya adalah field respons mesin itu sendiri.

Penjelasan

ExclusiveStartKey: lastEvaluatedKey bernilai undefined pada iterasi pertama, dan itu disengaja: serializer v3 membuang member undefined, jadi literal objek yang sama bekerja untuk request pertama dan setiap lanjutannya. Menggantinya dengan {} — tebakan yang jelas untuk "mulai dari awal" — gagal dengan ValidationException: The provided starting key is invalid.
@aws-sdk/client-dynamodb tak pernah melakukan marshalling untuk Anda. Nilai masuk sebagai {S: 'Arturo Sandoval'} dan item kembali dengan cara yang sama. Itulah imbalannya karena tidak menarik DocumentClient; kalau Anda lebih suka menulis objek JS biasa, @aws-sdk/lib-dynamodb adalah pembungkus yang perlu Anda pakai.
Angka bertahan melewati round trip sebagai string. Melakukan unmarshalling {N: '9007199254740993'} dengan unmarshall dari @aws-sdk/util-dynamodb mengembalikan bigint JS, bukan number yang kehilangan presisi; lewatkan {wrapNumbers: true} dan Anda mendapat {value: '9007199254740993'} sebagai gantinya. Bagaimanapun juga, jangan melakukan Number() pada N DynamoDB yang belum Anda periksa ukurannya.
KeyConditionExpression menerima kesetaraan pada partition key plus paling banyak satu kondisi sort key (=, <, <=, >, >=, BETWEEN, begins_with). Selain itu tempatnya di sebuah FilterExpression, yang berjalan setelah pembacaan.
ScanIndexForward: false membalik urutan sort key; menaik adalah defaultnya. IndexName mengalihkan command yang sama ke sebuah secondary index.

Lakukan secara visual

Query builder DynamoDB memancarkan seluruh bentuk ini — key condition, map nama dan nilai, serta loop LastEvaluatedKey — sebagai program SDK v3 yang siap dijalankan, jadi paginasinya bukan bagian yang Anda lupakan.

Untuk menjalankan query terhadap tabel sungguhan dalam sebuah GUI, dengan formulir key condition dan grid hasil berpaginasi, unduh DynoTable.

Panduan terkait

Query vs. Scan — mengapa Query adalah default yang tepat.
Key condition expression — setiap operator partition/sort key yang sah.
"Query condition missed key schema element" — key condition menyebut atribut yang salah atau melewatkan partition key.
"Query key condition not supported" — operator yang tak bisa dipakai key condition, seperti contains atau kondisi sort key kedua.