Node.js (AWS SDK v3) での DynamoDB TransactWriteItems

TransactWriteItems は、最大100個の書き込みを1つのオール・オア・ナッシングの操作にまとめます。すべてのアクションがコミットされるか、まったく何も起きないかのどちらかです。AWS SDK v3 では、TransactItems 配列が Put、Update、Delete、ConditionCheck のアクションを混在させる TransactWriteItemsCommand を送信します。それぞれ任意の条件付きです。

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;
  }
}

Explanation

TransactItems — 最大100個の Put / Update / Delete / ConditionCheck アクション、集計4 MB。アクションは複数のテーブルにまたがれます（同一アカウント + リージョン）が、2つのアクションが同じアイテムを対象にすることはできません — それだけでトランザクションがキャンセルされます。
ConditionCheck — トランザクションが変更しないアイテムに条件をアサートし（例: 「アカウントがまだ存在する」）、失敗した場合はトランザクション全体を拒否します。
TransactionCanceledException — 処理すべき唯一のエラーです。err.CancellationReasons は、アクションごとに1つの {Code, Message} を順に列挙します。コードには ConditionalCheckFailed、TransactionConflict（別のトランザクションが処理中にアイテムに触れた — バックオフ付きでリトライしても安全）、ProvisionedThroughputExceeded、ValidationError が含まれます。None は無実のアクションを示します。アクションに ReturnValuesOnConditionCheckFailure: 'ALL_OLD' を設定すると、その理由に負けたアイテムの属性が得られます。
ClientRequestToken — これを渡すと呼び出しが10分間べき等になります。ネットワークタイムアウト後の SDK リトライで、書き込みを2回適用できなくなります。
コスト — トランザクション書き込みはアイテムごとに2つの基礎的な書き込みを消費し（準備 + コミット）、プレーンな書き込みの約2× の WCU を課金します。単一アイテムの条件付き書き込みがすでに1アイテムのアトミック性を提供しているときは、トランザクションに手を伸ばさないでください。

Do it visually

各アクション内の条件式と更新式が厄介な部分です。DynamoDB Expression Builder がそれらを name/value マップとともに組み立て、実行可能なコードをコピーします。

アイテムを編集し、生成された式を GUI でレビューするには — DynoTable をダウンロードしてください。

DynamoDB TransactWriteItems in Python — boto3 での同じトランザクション。
DynamoDB TransactWriteItems with the AWS CLI — シェルからの同じトランザクション。
DynamoDB conditional write in Node.js — 2× のコストなしの単一アイテムのアトミック性。
DynamoDB transactions — 分離、べき等性、そしてトランザクションが割に合うのはいつか。
DynamoDB TransactionCanceledException — すべてのキャンセル理由コードを解読。
"Too many actions in a TransactWriteItems call" — 100アクションと4 MB のトランザクション制限。
"Transaction request cannot include multiple operations on one item" — トランザクションごと、アイテムごとに1アクション。

References

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Node.js (AWS SDK v3) での DynamoDB TransactWriteItems

Code

Explanation

Do it visually

Related examples

References