DynamoDB BatchGetItem di Node.js (AWS SDK v3)

BatchGetItem mengambil hingga 100 item berdasarkan primary key dalam satu permintaan. Di AWS SDK v3 panggilan ini harus berupa loop, karena UnprocessedKeys datang pada respons yang berhasil, bukan sebagai error. Apa yang mengisinya, dan mengapa 16 MB serta 1 MB per partisi adalah angka yang penting, dibahas di operasi batch di DynamoDB. Halaman ini tentang panggilan v3 dan apa yang ia kembalikan.

Kode

import {BatchGetItemCommand, DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let requestItems = {
  Music: {
    Keys: [
      {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'Cubano Chant'}},
      {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'A Mis Abuelos'}},
      {Artist: {S: 'Ella Fitzgerald'}, SongTitle: {S: 'Misty'}}
    ]
  }
};

const items = [];
let attempt = 0;

do {
  const response = await client.send(new BatchGetItemCommand({RequestItems: requestItems}));
  items.push(...(response.Responses?.Music ?? []));

  // A partial result is NOT an error: throttling, a >16 MB response, or an
  // internal failure returns the leftovers in UnprocessedKeys. Retry them
  // with exponential backoff.
  requestItems = response.UnprocessedKeys;
  if (requestItems && Object.keys(requestItems).length > 0) {
    attempt += 1;
    await sleep(Math.min(100 * 2 ** attempt, 5000));
  }
} while (requestItems && Object.keys(requestItems).length > 0);

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

Penjelasan

Optional chaining di situ bukan derau defensif. Responses dan UnprocessedKeys sama-sama opsional di tipe v3, jadi response.Responses?.Music ?? [] dan penjaga Object.keys() itulah yang diminta compiler. Di JavaScript polos, keduanyalah yang mencegah respons kosong pertama melempar error.
Bercabanglah pada err.name. v3 menaruh kode error layanan di sana, dan dua kegagalan yang benar-benar dilempar command ini tidak bisa dicoba ulang, jadi keduanya tak boleh masuk ke loop backoff. Lebih dari 100 key menghasilkan ValidationException / Too many items requested for the BatchGetItem call; key yang sama dua kali menghasilkan Provided list of item keys contains duplicates. Keduanya direproduksi apa adanya di halaman Python.
UnprocessedKeys datang sudah berbentuk RequestItems, dan hanya karena itulah loop bisa langsung menugaskannya kembali. Ia bukan kursor paginasi dan bukan berarti panggilannya gagal.
Backoff itu instruksi AWS, bukan basa-basi. Referensi API menyuruh Anda memakai "an exponential backoff algorithm" karena percobaan ulang seketika akan mendarat di partisi yang di-throttle yang sama.
ConsistentRead dan ProjectionExpression bersifat per tabel, disetel di dalam tiap entri RequestItems, bukan di level teratas. Itu mudah terlewat ketika map-nya hanya punya satu key dan terlihat seperti permintaan datar.

Seperti apa respons yang sebenarnya kembali

Jalankan blok kode di atas terhadap DynamoDB Local 3.3.0 dengan ketiga lagu tersedia, tambahkan ReturnConsumedCapacity: 'TOTAL', lalu catat judul lagunya alih-alih jumlahnya:

order:            [ 'A Mis Abuelos', 'Misty', 'Cubano Chant' ]
UnprocessedKeys:  {}
ConsumedCapacity: [ { TableName: 'Music', CapacityUnits: 1.5 } ]

Permintaannya mencantumkan Cubano Chant, A Mis Abuelos, Misty. Responsnya tidak berada di satu pun posisi itu, dan itulah sebabnya loop mendorong ke array datar alih-alih mengindeks berdasarkan offset. Cocokkan item kembali ke permintaan lewat atribut key-nya, dan sertakan key tersebut di ProjectionExpression mana pun supaya Anda masih punya sesuatu untuk dicocokkan.

Setel ConsistentRead: true pada entri Music yang sama dan ketiga key yang sama menghabiskan 3 unit, bukan 1,5. Tiga item di bawah 4 KB masing-masing ditagih sebagai tiga pembacaan GetItem terpisah, setengah unit untuk eventually consistent dan satu unit penuh untuk strongly consistent. Kalkulator harga mengubah aritmetika per item itu menjadi angka bulanan sebelum Anda mengunci sebuah pola baca.

Sekarang hapus Misty lalu jalankan ulang: dua item, UnprocessedKeys kosong, dan 1,0 unit. Key yang hilang tidak ditagih apa pun. Itu artefak DynamoDB Local dan bukan kontraknya; referensi BatchGetItem (diambil 2026-07-28) menyatakan bahwa permintaan untuk item yang tidak ada tetap menghabiskan kapasitas baca minimum sesuai jenis pembacaannya. Jangan menakar batch berisi cache miss dari hasil jalan lokal.

Untuk menarik sekumpulan key dan melihat apa yang sebenarnya kembali, tanpa menulis loop-nya lebih dulu, unduh DynoTable.

Contoh terkait

DynamoDB BatchGetItem di Python — pembacaan batch yang sama dengan boto3.
DynamoDB BatchGetItem dengan AWS CLI — pembacaan batch yang sama dari shell.
DynamoDB GetItem di Node.js — pembacaan satu item yang di-batch di sini.
Operasi batch di DynamoDB — batas, kegagalan sebagian, dan kapan batching sepadan.
"Too many items requested for the BatchGetItem call" — lebih dari 100 key dalam satu permintaan.
"Provided list of item keys contains duplicates" — key yang sama dua kali dalam satu batch.

Referensi

Terakhir diverifikasi 2026-07-28 terhadap dokumentasi resmi AWS yang ditautkan di atas.