DynamoDB BatchWriteItem di Node.js (AWS SDK v3)

BatchWriteItem melakukan put atau delete hingga 25 item dalam satu permintaan. Ia bukan UpdateItem versi kecil: setiap PutRequest mengganti seluruh item yang tersimpan, dan tipe v3 tidak memberi Anda tempat untuk melampirkan kondisi. Operasi batch di DynamoDB membahas batas dan model kegagalan sebagiannya; halaman ini tentang panggilan v3 dan satu cara ia kehilangan data secara diam-diam.

Kode

import {BatchWriteItemCommand, 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: [
    {
      PutRequest: {
        Item: {
          Artist: {S: 'Arturo Sandoval'},
          SongTitle: {S: 'Cubano Chant'},
          AlbumTitle: {S: 'Danzon'},
          Year: {N: '1994'}
        }
      }
    },
    {
      PutRequest: {
        Item: {
          Artist: {S: 'Arturo Sandoval'},
          SongTitle: {S: 'A Mis Abuelos'},
          AlbumTitle: {S: 'Danzon'},
          Year: {N: '1994'}
        }
      }
    },
    {
      DeleteRequest: {
        Key: {Artist: {S: 'Ella Fitzgerald'}, SongTitle: {S: 'Misty'}}
      }
    }
  ]
};

let attempt = 0;

do {
  const response = await client.send(new BatchWriteItemCommand({RequestItems: requestItems}));

  // Writes that were throttled come back in UnprocessedItems — resubmit them
  // with exponential backoff until the map is empty.
  requestItems = response.UnprocessedItems;
  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('Batch written');

Penjelasan

Anggota sisanya bernama UnprocessedItems, bukan UnprocessedKeys. Sisi baca memakai nama yang satunya, dan di JavaScript salah ketik di sini tetap ter-compile, terbaca sebagai undefined, lalu mengubah do/while menjadi panggilan sekali jalan yang membuang penulisan yang di-throttle begitu saja. TypeScript menangkapnya; JS polos tidak.
Tidak ada tempat untuk menaruh kondisi. Tipe WriteRequest v3 punya persis dua anggota opsional, PutRequest dan DeleteRequest, dan tak satu pun menerima ConditionExpression atau ReturnValues. Ini bukan SDK yang bersikap konservatif: referensi API menyatakan Anda tidak bisa menetapkan kondisi pada masing-masing permintaan put dan delete. Kalau sebuah penulisan butuh penjaga, ia tidak layak berada di batch, melainkan di UpdateItem dengan kondisi atau di sebuah transaksi.
Dua kesalahan yang bisa di-catch, keduanya tidak bisa dicoba ulang, dibedakan lewat err.name. Dua puluh enam entri memunculkan ValidationException / Too many items requested for the BatchWriteItem call. Menyentuh satu key dua kali memunculkan Provided list of item keys contains duplicates, dan pesan itu juga mencakup pasangan put+delete selain dua put, yang terbaca ganjil saat pertama kali Anda melihatnya.
Daftar penolakan seluruh batch lebih panjang dari tiga yang jelas. Selain >25 permintaan, item >400 KB, dan total >16 MB, DynamoDB menolak batch karena tabel yang tidak ada, key yang tidak cocok dengan schema, partition key di atas 2048 byte, atau sort key di atas 1024 byte. Satu entri buruk membuat Anda kehilangan seluruh 25 entri.
Batching membeli round trip, bukan kapasitas. Tiap entri ditagih sebagai PutItem atau DeleteItem tersendiri, dibulatkan ke atas per 1 KB, dan delete yang mengarah ke item yang tidak ada tetap menghabiskan satu write unit.

PutRequest yang hanya berisi key menghancurkan sisa item

Ella Fitzgerald / Misty awalnya punya AlbumTitle dan Year. Kirim satu PutRequest yang hanya membawa dua atribut key:

{PutRequest: {Item: {Artist: {S: 'Ella Fitzgerald'}, SongTitle: {S: 'Misty'}}}}

Lalu baca kembali dengan ConsistentRead: true. DynamoDB Local 3.3.0 mengembalikan:

{
  "Artist": { "S": "Ella Fitzgerald" },
  "SongTitle": { "S": "Misty" }
}

AlbumTitle dan Year lenyap. Panggilannya berhasil, UnprocessedItems berisi {}, dan tak ada apa pun di respons yang menyebut dua atribut yang ia buang. Sebuah put adalah penggantian item utuh, jadi batch yang dirakit dari payload sebagian (body permintaan API, subset kolom CSV, hasil Query terproyeksi yang menghilangkan atribut) menghapus setiap atribut yang tidak dibawa payload itu.

Itulah mode kegagalan yang harus Anda antisipasi ketika memakai batch untuk sesuatu yang terasa seperti update. Perbaikannya adalah membaca item saat ini lebih dulu lalu menggabungkannya, atau berhenti melakukan batching dan memakai UpdateItem, yang hanya menyentuh atribut yang Anda sebut.

Alasan lain sebuah batch 25 item menjadi batch 12 item adalah ukuran. Penulisan dibulatkan ke atas per 1 KB untuk penagihan dan permintaannya dibatasi 16 MB, jadi jumlah byte sebenarnya dari sebuah item menentukan baik tagihan Anda maupun berapa banyak yang muat. Kalkulator ukuran item memberi Anda angka itu per item sebelum Anda merakit array-nya.

Untuk memuat, menyunting, dan menghapus item secara massal tanpa menulis sendiri semantik penggantiannya, unduh DynoTable.

Contoh terkait

Penulisan batch DynamoDB di Python — batch_writer() boto3 mengerjakan loop retry-nya untuk Anda.
DynamoDB BatchWriteItem dengan AWS CLI — penulisan batch yang sama dari shell.
DynamoDB TransactWriteItems di Node.js — ketika penulisan harus berhasil atau gagal bersama-sama.
Operasi batch di DynamoDB — batas, kegagalan sebagian, dan kapan batching sepadan.
"Too many items requested for the BatchWriteItem call" — lebih dari 25 permintaan put/delete dalam satu batch.
"Provided list of item keys contains duplicates" — dua permintaan menyentuh key yang sama dalam satu batch.

Referensi

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