DynamoDB の Condition Expression:書き込みに条件を付ける
条件式は、DynamoDB が書き込みをコミットする 前 に既存のアイテムに対して評価する述語です。これは DynamoDB が持つ、書き込みに対する WHERE 句にもっとも近いものであり、不変条件を強制する唯一の安全な方法です。
DynamoDB の条件式はどう機能するのか?
条件式は、書き込みをコミットする前に、DynamoDB が現在のアイテムに対してサーバー側で評価する述語です。真なら書き込みは進み、偽なら書き込みは ConditionalCheckFailedException で拒否され、何も変わりません。チェックと変更を 1 つのアトミックな操作にまとめるため、並行する呼び出し元が古い読み取りで競合することはありません。
- ガードするのは書き込みだけ。
PutItem、UpdateItem、DeleteItemとTransactWriteItemsの各アクションが条件式を受け取ります。読み取りには代わりにFilterExpressionを使います。 - read-then-write を置き換える。 SQL から来ると、行を読み、アプリコードでチェックし、それから更新するでしょう。DynamoDB では、そのギャップが並行呼び出し元を待ち受けるデータ破損バグになります。
- 拒否された書き込みも課金される。 照合対象となった既存アイテムのサイズ分の書き込みキャパシティを消費し、アイテムが存在しなければ 1 ユニットを消費します。
どこに適用されるか
ConditionExpression は PutItem、UpdateItem、DeleteItem、そして
TransactWriteItems の各アクションに付けられます。Query や Scan の一部ではありません。それらは読み取りパスの別物である FilterExpression を使います。
ConditionExpression | FilterExpression | |
|---|---|---|
| パス | 書き込み(Put/Update/Delete) | 読み取り(Query/Scan) |
| 失敗時の効果 | 書き込み全体を拒否 | 結果からアイテムを除外 |
| 見るもの | 書き込み前の現在のアイテム | 各候補アイテム(読み取り後) |
| コスト | 失敗した書き込みも課金される | フィルタされたアイテムも読み取り分は課金される |
どちらもサーバー側で走ります。偽の条件は変更を中止し、偽のフィルタはすでに読み取り分を支払った行を隠すだけです。(AWS: Condition Expressions)
条件関数と演算子
条件言語は小さいものです。
attribute_exists(path)/attribute_not_exists(path):この 属性 はアイテムに存在するか?「なければ作成のみ」「あれば更新のみ」の定番のイディオムです。- 比較演算子
=、<>、<、<=、>、>=:値または別の属性に対して。 attribute_type、begins_with、contains、size:型と文字列/セットのチェック。BETWEEN … AND …、IN (…):範囲とメンバーシップ。AND、OR、NOT、括弧:上記を組み合わせるため。
(AWS: Comparison Operator and Function Reference)
算術演算はありません。clearedCents - holdCents >= :amt は構文エラーになるため、
2 つの属性にまたがるルールには、その結果を 3 つ目の属性として保存する必要があります(後述の実践例を参照)。
パーティションキー に対する attribute_not_exists は、PutItem を既存アイテムを上書きしないインサートのように振る舞わせる定石です。アイテム API には独立したインサート操作がないため、条件 が インサートのセマンティクスそのものになります。
PartiQL の INSERT は同じチェックを代わりに実行し、既存のキーを拒否します。(AWS: PartiQL insert statements)
実践例:残高不足から台帳を守る
銀行の台帳を例に取ります。各口座は 1 つのアイテムです。
PK = "ACCT#a7f3"
SK = "BALANCE"
clearedCents = 50000
引き落としは残高を決してゼロ未満に押し下げてはならず、存在しない口座を引き落としてはなりません。2 つのルールで、どちらも書き込み自体の中で強制できます。
誤ったやり方(地雷)
GetItem ACCT#a7f3 / BALANCE → clearedCents = 50000
if (50000 >= 30000) ... ← app-side check
UpdateItem SET clearedCents = 20000
GetItem と UpdateItem の間で、2 つ目の引き落としが同じ 50000 を読み、自分のチェックを通過し、同じく書き込むことができます。両方が成功し、口座はマイナスになります。これは read-modify-write の競合であり、アプリ側でいくら検証しても直りません。チェックと書き込みが別々の操作だからです。
正しいやり方
チェックを書き込みに折り込みます。口座が存在し かつ 十分な残高を持つことを条件に、更新式で 30000 セント引き落とします。
UpdateItem ACCT#a7f3 / BALANCE
SET clearedCents = clearedCents - :amt
ConditionExpression:
attribute_exists(PK) AND clearedCents >= :amt
:amt = 30000 は値のプレースホルダーです(式の名前と値を参照)。
残高が低すぎるか、アイテムが作成されていなければ、DynamoDB は書き込みを
ConditionalCheckFailedException で拒否し、残高は手つかずのままです。
条件は、並行する書き込みが着地した後の 保存されている 値を比較します。30000 の
2 回目の引き落としは 20000 を見て拒否されます。以前に読んだかもしれない 50000 を根拠に動くことは決してありません。
ルールが 2 つの属性にまたがる場合(たとえば確定済み資金から保留分を引いたもの)、結果を専用の属性(availableCents)に保持し、その入力と同じ SET で変更して、
availableCents >= :amt を条件にします。
DynamoDB 式ビルダーは、名前と値も含めて正確な式を組み立ててコピーします。下のビルダーは上のガード付き引き落とし(attribute_exists(PK) と
clearedCents >= 30000)にプリセットされているので、生成された ConditionExpression を読めます。
dynamodb-expression-builder は、このツールの基盤となるオープンソース(MIT)ライブラリです。
引き落としを安全にリトライできるようにする
ガード付きの引き落としは冪等ではありません。書き込みが着地した後にレスポンスが失われると、リトライはもう一度それを送り、残高が十分残っていれば、エラーなしに 2 回目の引き落としを行います。>= のチェックは、繰り返しと新しい引き落としを区別できません(カウンターと同じ落とし穴です)。
各引き落としに ID を与え、同じトランザクションの中でそのマーカーアイテムを書き込みます。
TransactWriteItems
Put ACCT#a7f3 / TXN#t-123
ConditionExpression: attribute_not_exists(PK)
Update ACCT#a7f3 / BALANCE
SET clearedCents = clearedCents - :amt
ConditionExpression: attribute_exists(PK) AND clearedCents >= :amt
t-123 の繰り返しは自分のマーカーを見つけてトランザクション全体をキャンセルするので、残高は 1 回だけ動きます。代償はトランザクションによる
2 倍の書き込みユニットと、引き落としごとに 1 つの小さなアイテムです。リトライの期間が過ぎたら期限切れになるよう、マーカーに TTL 属性を付けましょう。
同じ呼び出しのリトライだけをカバーすればよいなら、引き落としを 1 アクションの
TransactWriteItems として ClientRequestToken 付きで送り、トークンを再利用します。
10 分以内であれば、同じトークンでの繰り返しは 2 回適用されることなく成功します。
UpdateItem にはトークンのパラメータがないため、トークンが守るのはトランザクションだけです。マーカーは、自分のコードが後から送るリトライも捕捉します。
DynoTable でガードを調べる
条件付き書き込みが失敗したとき、当て推量ではなくアイテムの実際の状態を見たくなります。口座アイテムを呼び出して clearedCents を直接読みましょう。

拒否を読み解き、盲目的にリトライしない
ConditionalCheckFailedException は一時的なエラーではないため、同じ状態に対して同じ書き込みをリトライしても何も変わりません。ビジネスルールが発火したことを意味します。残高不足、重複作成、古いバージョンです。ドメインの結果として表面化させましょう。
失敗をデバッグ可能にするものが 2 つあります。
ReturnValuesOnConditionCheckFailure: ALL_OLD。 DynamoDB が失敗と一緒に現在のアイテムを返すので、2 回目の読み取りなしに「残高は 20000 でしたが、30000 を要求しました」と示せます。(AWS: Working with Items)- 2 つの失敗理由を見分ける。
attribute_exists(PK) AND clearedCents >= :amtは「口座なし」と「残高不足」を 1 つの例外にまとめてしまいます。ALL_OLDを設定していれば、アイテムが返らないことは口座が存在しないことを意味し、アイテムが返ることは資金が足りなかったことを意味します。ただし、自分の引き落としのリトライがすでに着地していた場合は別です。マーカートランザクションではCancellationReasonsが決着をつけます。マーカーのPutが失敗していれば、その引き落としはすでに適用済みです。
楽観的ロックも同じトリック
楽観的ロックは、version 属性に対する条件式です。どの書き込みも読み取ったバージョンを表明し、それをインクリメントします。
UpdateItem ACCT#a7f3 / BALANCE
SET clearedCents = :new, version = :next
ConditionExpression: version = :seen
別の書き手が先に動いていれば、version = :seen は偽となり、書き込みは拒否され、再読み込みしてリトライします。これが DynamoDB がロックなしで並行性制御を行う方法です。見たものを表明し、それが動いていたら失敗する。(AWS: Optimistic Locking with
Version Number)
DynoTable のステージングエリアは、同じ「見たものを表明する」チェックを属性ごとに実行します。更新は、属性が編集を始めたときの値をまだ保持している場合にのみコミットされるので、並行編集は解決すべき競合として表面化します。
落とし穴と次のステップ
- 予約語と衝突する名前。
status、name、ttl、その他 ~570 語は予約されています。エイリアスしなければValidationException("Attribute name is a reserved keyword; reserved keyword: status")で失敗します。式の名前と値を参照するか、予約語チェッカーからエイリアスマップを取得しましょう。 - 条件は別のアイテムを参照できない。 書き込まれるアイテムしか見えません。アイテムをまたぐ不変条件には、アクションごとの
ConditionExpressionを伴うTransactWriteItems、またはマーカーアイテムに対するConditionCheckが必要です。これは複数の属性にまたがる一意な値の背後にあるパターンです。 - 失敗した書き込みでも書き込みキャパシティはかかる。 拒否は、それを阻んだアイテムのサイズ分を課金します。300 KB のアイテムに対しては 300 書き込みユニットです。頻繁にガードされるアイテムは小さく保ち、大きなペイロードは別のアイテムか S3 に移しましょう(アイテムサイズの上限)。
これらのガードが保護する書き込みについては更新式を、ガードが走るキーのモデル化についてはシングルテーブル設計を参照してください。独自のガードは式ビルダーで書けます。両方のマップ付きで ConditionExpression を出力します。実データを編集するときは
DynoTable をダウンロードしてください。ステージされたアイテム編集は上記の「見たものを表明する」チェック付きでコミットされるので、並行編集は競合として表面化します。


