AWS CLI での DynamoDB 条件付き書き込み

条件付き書き込みは、put-item、update-item、delete-item に --condition-expression を付けます。DynamoDB はそれを現在のアイテムに対して評価し、条件が成立する場合にのみ書き込みを適用します。アトミックで、read-modify-write の競合はありません。これは DynamoDB の楽観的ロックのプリミティブです。この例では、バージョンチェックで更新をガードします。

Code

aws dynamodb update-item \
  --table-name 'Music' \
  --key '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"}}' \
  --update-expression 'SET #upd0 = :updValue0, #version = :newVersion' \
  --condition-expression 'attribute_exists(#cond0) AND #version = :expectedVersion' \
  --expression-attribute-names '{"#upd0":"Genre","#version":"Version","#cond0":"Artist"}' \
  --expression-attribute-values '{":updValue0":{"S":"Latin Jazz"},":expectedVersion":{"N":"7"},":newVersion":{"N":"8"}}'

成功するとコマンドは何も出力せず、0 で終了します。別の書き込み側が先に到達していた場合、条件は失敗します。

An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation:
The conditional request failed

Explanation

--condition-expression — 書き込みとアトミックに、保存されたアイテムに対してチェックされます。利用可能な関数: attribute_exists、attribute_not_exists、attribute_type、contains、begins_with、size、加えて比較演算子（=、<>、<、>、<=、>=、BETWEEN、IN）と AND/OR/NOT。
2つの主力イディオム:
- 更新での attribute_exists(#key) = 「更新のみ、決して作成しない」。これがないと、存在しないキーへの update-item はアイテムを静かに作成します（意図しないアップサートのバグ）。
- プットでの attribute_not_exists(#key) = 「作成のみ、決して上書きしない」— PutItem ページで示しています。
楽観的ロック — アイテム（バージョン7）を読み取り、8 に上げながら #version = :expectedVersion で書き込みます。2つの並行する書き込み側が両方とも勝つことはありません。負けた側は ConditionalCheckFailedException で非ゼロ終了し、再読み取りして新しいバージョンでリトライします。
--return-values-on-condition-check-failure ALL_OLD — 失敗時に現在のアイテムを添付するよう DynamoDB に要求します（有効な値は ALL_OLD | NONE。読み取りキャパシティは消費しません）。SDK はそのアイテムを例外で表面化しますが、CLI のデフォルトのエラー出力はメッセージだけを表示するため、スクリプトは通常、失敗後に get-item で再読み取りします。
失敗した条件付き書き込みでも書き込みの試行分は課金されます。条件を無料の存在チェックとして使わないでください。

Do it visually

条件式はまさに DynamoDB Expression Builder が構築するものです。関数を選べば、式と name/value マップがすぐに実行できる CLI コマンドとして得られます。

シェルクォートされたプレースホルダーの代わりに、生成された、レビュー可能な式でアイテムを編集するには — DynoTable をダウンロードしてください。

DynamoDB conditional write in Node.js — AWS SDK v3 での同じ楽観的ロック。
DynamoDB conditional write in Python — boto3 での同じ楽観的ロック。
DynamoDB PutItem with the AWS CLI — 作成のみの attribute_not_exists プット。
DynamoDB condition expressions — すべての関数とパターン。
Understanding ReturnValues — 各返却オプションが何を返すか。
DynamoDB ConditionalCheckFailedException — 失敗したチェックが想定内のとき、それを安価に扱う方法。

References

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

AWS CLI での DynamoDB 条件付き書き込み

Code

Explanation

Do it visually

Related examples

References