Penulisan Bersyarat DynamoDB di Node.js (AWS SDK v3)

Sebuah penulisan bersyarat melampirkan ConditionExpression ke PutItem, UpdateItem, atau DeleteItem: DynamoDB mengevaluasinya terhadap item saat ini dan menerapkan penulisan hanya jika kondisi terpenuhi — secara atomik, tanpa race read-modify-write. Ini adalah primitif optimistic-locking DynamoDB. Contoh ini menjaga sebuah update dengan pemeriksaan versi.

Code

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

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

// Update the item only if nobody changed it since we read version 7.
const command = new UpdateItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  UpdateExpression: 'SET #upd0 = :updValue0, #version = :newVersion',
  ConditionExpression: 'attribute_exists(#cond0) AND #version = :expectedVersion',
  ExpressionAttributeNames: {
    '#upd0': 'Genre',
    '#version': 'Version',
    '#cond0': 'Artist'
  },
  ExpressionAttributeValues: {
    ':updValue0': {S: 'Latin Jazz'},
    ':expectedVersion': {N: '7'},
    ':newVersion': {N: '8'}
  },
  ReturnValuesOnConditionCheckFailure: 'ALL_OLD'
});

try {
  await client.send(command);
  console.log('Updated to version 8');
} catch (err) {
  if (err.name === 'ConditionalCheckFailedException') {
    // With ReturnValuesOnConditionCheckFailure: 'ALL_OLD', the current item
    // rides back on the exception — no extra read to see what beat you.
    console.log('Lost the race — item is now:', err.Item);
  } else {
    throw err;
  }
}

Penjelasan

ConditionExpression — diperiksa terhadap item tersimpan secara atomik bersama penulisan. Fungsi yang tersedia: attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, plus komparator (=, <>, <, >, <=, >=, BETWEEN, IN) dan AND/OR/NOT.
Dua idiom andalan:
- attribute_exists(#key) pada update = "hanya update, tidak pernah membuat". Tanpanya, UpdateItem pada key yang hilang diam-diam membuat item (bug upsert tak sengaja).
- attribute_not_exists(#key) pada put = "hanya membuat, tidak pernah menimpa" — ditunjukkan di halaman PutItem.
Optimistic locking — baca item (versi 7), lalu tulis dengan #version = :expectedVersion sambil menaikkan ke 8. Dua penulis serentak tidak bisa keduanya menang; yang kalah mendapat ConditionalCheckFailedException, membaca ulang, dan mencoba lagi pada versi baru.
ReturnValuesOnConditionCheckFailure: 'ALL_OLD' — menaruh item saat ini pada exception (err.Item, marshalled), menghemat GetItem lanjutan setelah pemeriksaan yang gagal. Ia mengonsumsi tidak ada kapasitas baca; penulisan bersyarat yang gagal tetap menagih upaya penulisannya.
Semua di sini di-alias (#version → Version) via ExpressionAttributeNames, sehingga reserved word tidak pernah menggigit.

Lakukan secara visual

Condition expression persis apa yang dibangun DynamoDB Expression Builder — pilih fungsinya, dapatkan expression + map name/value sebagai kode yang bisa dijalankan.

Untuk mengedit item dengan expression yang dihasilkan dan bisa ditinjau alih-alih placeholder yang diketik dengan tangan — unduh DynoTable.

Contoh terkait

Penulisan bersyarat DynamoDB di Python — optimistic lock yang sama dengan boto3.
Penulisan bersyarat DynamoDB dengan AWS CLI — optimistic lock yang sama dari shell.
DynamoDB PutItem di Node.js — put attribute_not_exists hanya-membuat.
Condition expression DynamoDB — setiap fungsi, dengan polanya.
Menegakkan keunikan pada beberapa atribut — kondisi + transaksi digabungkan.
DynamoDB ConditionalCheckFailedException — kapan pemeriksaan yang gagal itu diharapkan, dan cara menanganinya dengan murah.

References

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