AWS CLI での DynamoDB TransactWriteItems

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

Code

aws dynamodb transact-write-items \
  --transact-items '[
    {
      "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"}}
      }
    }
  ]'

成功するとコマンドは何も出力せず、0 で終了します。いずれかの条件が失敗すると、トランザクション全体がキャンセルされます。

An error occurred (TransactionCanceledException) when calling the TransactWriteItems
operation: Transaction cancelled, please refer cancellation reasons for specific
reasons [ConditionalCheckFailed, None]

Explanation

--transact-items — 最大100個の Put / Update / Delete / ConditionCheck アクション、集計4 MB、値は DynamoDB JSON。アクションは複数のテーブルにまたがれます（同一アカウント + リージョン）が、2つのアクションが同じアイテムを対象にすることはできません — それだけでトランザクションがキャンセルされます。
キャンセル理由は、エラーメッセージにアクション順で載ります。コードには ConditionalCheckFailed、TransactionConflict（別のトランザクションが処理中にアイテムに触れた — 再実行しても安全）、ProvisionedThroughputExceeded、ValidationError が含まれます。None は無実のアクションを示します。ここでは最初の更新の条件（Awards >= 1）が失敗しました。2番目のアクションは問題ありませんでした。
ConditionCheck — トランザクションが変更しないアイテムに条件をアサートし、失敗した場合はトランザクション全体を拒否します。
--client-request-token — 固定のトークンを渡すと、再実行が10分間べき等になります。タイムアウト後に正確なコマンドを再実行しても、書き込みを2回適用できなくなります。
コスト — トランザクション書き込みは、プレーンな書き込みの約2×の WCU を課金します（準備 + コミット）。単一アイテムのアトミック性には、条件付き書き込みの方が安価なツールです。
ヒント: アクション配列をファイルに保持して --transact-items file://transaction.json を渡しましょう。

Do it visually

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

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

DynamoDB TransactWriteItems in Node.js — AWS SDK v3 での同じトランザクション。
DynamoDB TransactWriteItems in Python — boto3 での同じトランザクション。
DynamoDB BatchWriteItem with the AWS CLI — アトミック性が不要なときの一括書き込み。
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 ドキュメントに照らして確認しました。

AWS CLI での DynamoDB TransactWriteItems

Code

Explanation

Do it visually

Related examples

References