DynamoDB TransactWriteItems di Node.js (AWS SDK v3)

TransactWriteItems mengelompokkan hingga 100 penulisan ke dalam satu operasi all-or-nothing — entah setiap aksi commit, atau tidak ada yang commit. Di AWS SDK v3 Anda mengirim TransactWriteItemsCommand yang array TransactItems-nya mencampur aksi Put, Update, Delete, dan ConditionCheck, masing-masing dengan kondisi opsional.

Code

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

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

// Move one award between two songs — atomically. If the first song has no
// award to give, NEITHER update happens.
const command = new TransactWriteItemsCommand({
  TransactItems: [
    {
      Update: {
        TableName: 'Music',
        Key: {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'Cubano Chant'}},
        UpdateExpression: 'SET #upd0 = #upd0 - :one',
        ConditionExpression: '#upd0 >= :one',
        ExpressionAttributeNames: {'#upd0': 'Awards'},
        ExpressionAttributeValues: {':one': {N: '1'}}
      }
    },
    {
      Update: {
        TableName: 'Music',
        Key: {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'A Mis Abuelos'}},
        UpdateExpression: 'SET #upd0 = if_not_exists(#upd0, :zero) + :one',
        ExpressionAttributeNames: {'#upd0': 'Awards'},
        ExpressionAttributeValues: {':one': {N: '1'}, ':zero': {N: '0'}}
      }
    }
  ]
});

try {
  await client.send(command);
  console.log('Transaction committed');
} catch (err) {
  if (err.name === 'TransactionCanceledException') {
    // One reason per action, in TransactItems order. 'None' means that action
    // was fine — some OTHER action sank the transaction.
    const codes = (err.CancellationReasons ?? []).map((r) => r.Code);
    console.log('Transaction canceled:', codes); // e.g. ['ConditionalCheckFailed', 'None']
  } else {
    throw err;
  }
}

Penjelasan

• TransactItems — hingga 100 aksi Put / Update / Delete / ConditionCheck, agregat 4 MB. Aksi bisa mencakup beberapa tabel (akun + Region yang sama), tetapi tidak boleh ada dua aksi yang menargetkan item yang sama — itu saja membatalkan transaksi.
• ConditionCheck — menegaskan sebuah kondisi pada item yang tidak dimodifikasi transaksi (mis. "akun masih ada") dan memveto seluruh transaksi jika gagal.
• TransactionCanceledException — satu-satunya error yang perlu ditangani. err.CancellationReasons mendaftar satu {Code, Message} per aksi dalam urutan — kode mencakup ConditionalCheckFailed, TransactionConflict (transaksi lain menyentuh sebuah item di tengah jalan — aman untuk dicoba ulang dengan backoff), ProvisionedThroughputExceeded, dan ValidationError; None menandai aksi yang tidak bersalah. Setel ReturnValuesOnConditionCheckFailure: 'ALL_OLD' pada sebuah aksi untuk mendapatkan atribut item yang kalah dalam reason-nya.
• ClientRequestToken — lewatkan satu untuk membuat panggilan idempotent selama 10 menit; sebuah retry SDK setelah timeout jaringan kemudian tidak bisa menerapkan penulisan dua kali.
• Biaya — penulisan transaksional mengonsumsi dua penulisan yang mendasari per item (prepare + commit), jadi mereka menagih kira-kira 2× WCU dari penulisan biasa. Jangan meraih transaksi ketika sebuah penulisan bersyarat satu-item sudah memberi Anda atomisitas pada satu item.

Lakukan secara visual

Condition dan update expression di dalam setiap aksi adalah bagian yang rumit — DynamoDB Expression Builder merakitnya dengan map name/value dan menyalin kode yang bisa dijalankan.

Untuk mengedit item dan meninjau expression yang dihasilkan dalam GUI — unduh DynoTable.

Contoh terkait

• DynamoDB TransactWriteItems di Python — transaksi yang sama dengan boto3.
• DynamoDB TransactWriteItems dengan AWS CLI — transaksi yang sama dari shell.
• Penulisan bersyarat DynamoDB di Node.js — atomisitas satu-item tanpa biaya 2×.
• Transaksi DynamoDB — isolasi, idempotensi, dan kapan transaksi sepadan.
• DynamoDB TransactionCanceledException — setiap kode cancellation-reason, diuraikan.
• "Too many actions in a TransactWriteItems call" — batas 100-aksi dan 4 MB transaksi.
• "Transaction request cannot include multiple operations on one item" — satu aksi per item, per transaksi.

References

• TransactWriteItems — Amazon DynamoDB API Reference
• Amazon DynamoDB transactions: how it works — Amazon DynamoDB Developer Guide
• DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide

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