DynamoDB PutItem di Node.js (AWS SDK v3)

PutItem menulis satu item utuh dan menggantikan item mana pun yang punya primary key sama (aksi berbasis item membahas bedanya dengan UpdateItem). Client v3 mengirim DynamoDB JSON secara langsung, jadi Item memuat nilai { S: … } / { N: … } alih-alih JavaScript biasa.

Kode

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

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

const command = new PutItemCommand({
  TableName: 'Music',
  Item: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'},
    AlbumTitle: {S: 'Danzon'},
    Year: {N: '1994'},
    Awards: {N: '0'}
  },
  ConditionExpression: 'attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)',
  ExpressionAttributeNames: {
    '#cond0': 'Artist',
    '#cond1': 'SongTitle'
  }
});

try {
  await client.send(command);
  console.log('Song written');
} catch (err) {
  if (err.name === 'ConditionalCheckFailedException') {
    console.log('A song with that key already exists — not overwritten');
  } else {
    throw err;
  }
}

Penjelasan

err.name adalah pemeriksaan yang tepat, dan bukan satu-satunya hal yang ada pada error itu. Menangkap kondisi yang gagal di atas lalu mencetak objeknya memberikan:

err.name                     ConditionalCheckFailedException
err instanceof Error         true
err.message                  The conditional request failed
err.$metadata.httpStatusCode 400

Setiap error v3 membawa $metadata berisi kode status, request id, dan jumlah percobaan, yang justru itulah yang Anda inginkan dalam sebaris log. err.name stabil lintas paket modular; instanceof ConditionalCheckFailedException juga bekerja tapi menarik kelasnya masuk sebagai value import, jadi bundler mempertahankannya.

Error itu bisa menyerahkan item yang menghalangi penulisan Anda. Tambahkan ReturnValuesOnConditionCheckFailure: 'ALL_OLD' ke command-nya dan err.Item datang terisi: lima atribut pada jalannya di atas, dengan Year sebagai {"N":"1994"}. Kebanyakan handler hanya-membuat melakukan GetItem setelah kegagalan untuk mencari tahu apa yang sudah ada di sana. Perjalanan bolak-balik itu bisa dihindari. (ReturnValues: 'ALL_OLD' adalah sepupunya di jalur sukses; ReturnValues membahas sisanya.)

marshall() menolak lebih banyak input daripada yang Anda kira. Menukar Item bertipe di halaman ini dengan DynamoDBDocumentClient dan objek biasa adalah langkah berikutnya yang lazim, dan @aws-sdk/util-dynamodb bersikap ketat secara default. Tiga error nyata, apa adanya:

{Genre: undefined}   Pass options.removeUndefinedValues=true to remove undefined values from map/array/set.
{tags: new Set()}    Pass a non-empty set, or options.convertEmptyValues=true.
{n: 9007199254740993} Number 9007199254740992 is greater than Number.MAX_SAFE_INTEGER. Use NumberValue from @aws-sdk/lib-dynamodb.

Yang pertama adalah yang sampai ke produksi: field opsional yang bernilai undefined alih-alih tidak ada sama sekali melempar error saat marshal, dan removeUndefinedValues: true di DynamoDBDocumentClient.from(client, {marshallOptions}) adalah perbaikan standarnya.

Baca lagi baris ketiga. Literalnya adalah 9007199254740993; pesannya mengutip 9007199254740992. JavaScript sudah membulatkan nilai itu sebelum SDK sempat melihatnya, jadi SDK melaporkan apa yang ia terima. Inilah seluruh alasan DynamoDB mengangkut N sebagai string: ia menampung presisi 38 digit, sedangkan number JS menampung 15 sampai 17. Apa pun yang sebenarnya adalah identifier tempatnya di S, dan apa pun yang sebenarnya adalah desimal tempatnya di NumberValue atau string yang Anda format sendiri.

ConditionExpression memakan kapasitas tulis bahkan ketika ia berkata tidak. AWS: "if the expression evaluates to false, DynamoDB still consumes write capacity units from the table" (diambil 2026-07-28). Loop hanya-membuat yang ketat ditagih per percobaan. Sebagai kalibrasi, put yang berhasil atas item ~15 KB melaporkan "CapacityUnits": 15; penulisan dibulatkan ke atas per 1 KB alih-alih per 4 KB seperti pembacaan.

Alias-nya menanggung beban. #cond0/#cond1 mengarah ke Artist/SongTitle lewat ExpressionAttributeNames. Nama inline bekerja sampai salah satunya bertabrakan dengan sebuah reserved word, dan kemudian expression-nya gagal pada atribut yang bahkan tak Anda sentuh.

Lakukan secara visual

Aturan marshalling di atas paling mudah diperiksa dengan melihat kedua bentuknya berdampingan. Konverter DynamoDB JSON gratis mengubah JSON biasa menjadi bentuk bertipe { S: … } dan sebaliknya, jadi Anda bisa memastikan apa yang akan dihasilkan marshall() sebelum Anda mengirimnya.

Untuk menulis dan menyunting item terhadap tabel Anda sendiri — satu formulir per atribut, pemilih tipe, salin hasilnya kembali sebagai kode SDK v3 — unduh DynoTable.

Panduan terkait

Condition expression DynamoDB — attribute_not_exists, optimistic locking, dan lainnya.
Tipe data DynamoDB — bagaimana setiap tipe atribut ditulis.
DynamoDB ConditionalCheckFailedException — apa yang dilempar kondisi hanya-membuat ketika item-nya sudah ada.
DynamoDB ValidationException — penampung serba-guna untuk item atau expression yang bentuknya salah.

Referensi

Direproduksi 2026-07-28 pada Node v24.18.0 dengan @aws-sdk/client-dynamodb 3.1095.0 dan @aws-sdk/util-dynamodb 3.996.7, terhadap DynamoDB Local (amazon/dynamodb-local) di port 9000. String error, bentuk objeknya, dan pembacaan kapasitasnya adalah keluaran yang ditangkap, dikutip apa adanya.