DynamoDB の Update Expression:SET・REMOVE・ADD・DELETE
更新式は UpdateItem に、1 つの項目をどう変更するかを伝えます。どの属性を書き込み、インクリメントし、削除し、あるいはセットに畳み込むかを、4 つの句キーワードで記述します。
DynamoDB の更新式はどう動きますか?
DynamoDB の更新式は UpdateItem に、4 つの句を使って 1 つの項目をどう変更するかを伝えます。SET は属性を書き込むか上書きします。ADD は数値をアトミックにインクリメントするか、セットに和集合として加えます。REMOVE は属性、またはリスト要素を 1 つ削除します。DELETE はセットから特定のメンバーを取り除きます。1 回の呼び出しで 4 つすべてを同時に運べます。
- 1 回の呼び出しで 1 項目。 完全なキーで項目を名指しします。複数行にわたる
UPDATE … SET … WHEREはありません(多数の項目の更新は下の落とし穴で扱います)。 - 算術はサーバー側で行われます。
SET n = n + :xもADDも、事前に読み取ることなく数値を変更するので、同時に書き込む側が更新を失うことはありません。 - アップサートです。 まだ存在しないキーは作成されます。条件式で止めない限りはそうなります。
SQL から来ると、罠は read-modify-write です。値を読み取り、コードで変更し、書き戻す。並行実行下ではこれが更新を失います。変更は式の中で行ってください。
変更する対象で句を選ぶ
1 回の UpdateItem 呼び出しで、4 つの句すべてを任意の順序で同時に運べます。各キーワードは最大 1 回だけ現れ、カンマ区切りのアクションのリストを取ります。
| 句 | 対象 | 用途 |
|---|---|---|
SET | 任意の属性 | 値やドキュメントフィールドを書き込む/上書きする |
ADD | 数値またはセットのみ | アトミックにインクリメントする、またはセットに和集合として加える |
REMOVE | 任意の属性またはリスト要素 | 属性を削除する。リストインデックスを 1 つ落とす |
DELETE | セットのみ | セットから特定のメンバーを取り除く |
文字列への ADD やスカラーへの DELETE は、呼び出し全体を拒否する検証エラーです。スカラーは SET で変更してください。AWS の更新式リファレンスによれば、ADD は数値とセットに、DELETE はセットに限定されます。
実例:CMS の記事
式の名前と値の CMS テーブルで、記事 1 つにつき項目 1 つ、PK = "BLOG#eng" と SK = "ARTICLE#launch-notes" でキー付けします。
この項目は Revisions リスト、WordCount、RevisionCount、そして Tags 文字列セットを追跡します。各式の : で始まる名前は値のプレースホルダーで、ExpressionAttributeValues で渡します。
SET:スカラーとドキュメントを書き込む
SET はそこにあったものを上書きします。同じ呼び出しで、リビジョンをリストに追加し、新しい単語数を記録します。
SET WordCount = :words,
Revisions = list_append(Revisions, :rev),
UpdatedAt = :now
:rev はリビジョンのマップを 1 つ持つ 1 要素のリストです。list_append(Revisions, :rev) は末尾に追加し、list_append(:rev, Revisions) は先頭に追加します。引数の順序が連結の順序です。
この呼び出しには落とし穴があります。新しい記事では Revisions はまだ存在せず、存在しない属性への list_append は "The provided
expression refers to an attribute that does not exist in the item" で失敗します。if_not_exists でガードします。
SET Revisions = list_append(if_not_exists(Revisions, :empty), :rev)
if_not_exists(Revisions, :empty) は、存在すれば現在のリストを、なければフォールバックの :empty(空リスト [])を返します。これで最初のリビジョンもその後のすべてのリビジョンも同じ式を使えます。
ADD:カウントをアトミックにインクリメントする
RevisionCount を増やすのに、それを読み取り、コードで 1 を足して SET で書き戻すことはしないでください。2 つの同時の編集が両方とも 3 を読み、両方とも 4 を書き、1 つを落とします。ADD は算術をサーバー側で行います。
ADD RevisionCount :one
:one = 1 なら、これはアトミックカウンターです。同時呼び出しは項目上で直列化されるので、2 つの加算は +2 として反映されます。負の数を渡すとデクリメントします。RevisionCount が存在しなければ、ADD はまずそれを 0 として扱うので、カウンターを初期化する必要はありません。
SET RevisionCount = RevisionCount + :one も同じくアトミックです。
AWS のガイドは一般に "to ensure idempotent operations" のために ADD より SET を推奨しています。絶対値への SET は安全にリトライできます。インクリメントはどちらの形でもリトライできません。タイムアウトによって、すでに反映された呼び出しを SDK がリトライすると、カウントは 2 回増えます。
二重カウントが問題になるなら、読み取った値を条件にして新しい絶対値を書き込んでください。そのパターンと各インクリメントのコストはアトミックカウンターで扱っています。
すべての UpdateItem は、更新前と更新後のうち大きいほうの項目サイズに対して、1 KB あたり 1 書き込みユニット(切り上げ)を課金します。
DynamoDB 式ビルダーは、型付きの値とプレースホルダーでこれらの式を構築します。下のプリセットは launch-notes の記事で、WordCount の SET と RevisionCount へのアトミックな ADD です。編集して、UpdateExpression が再構築されるのを見てください。
dynamodb-expression-builder は、このツールの基盤となるオープンソース(MIT)ライブラリです。
REMOVE:属性やリビジョンを 1 つ落とす
REMOVE は属性をまるごと削除する方法です。「null にセット」はありません。それは単に NULL 値を書き込むだけです。1 回の呼び出しで、注目記事の終了日をクリアし、3 番目のリビジョンを落とします。
REMOVE FeaturedUntil, Revisions[2]
Revisions[2] はインデックス 2 の要素を削除し、その後のすべてを 1 つ下へシフト します。インデックス 3 が 2 になり、以下同様です。
1 つの式で 2 つのインデックスを REMOVE する場合、両方とも 元の リストに対して評価されるので、[2] と [3] を一緒に削除すると、期待どおり 3 番目と 4 番目の要素が落ちます。
DELETE:セットのメンバーを取り除く
Tags は文字列セットなので、タグを 1 つ廃止するには REMOVE ではなく DELETE を使います。REMOVE Tags はセット全体を落とします。DELETE は名指しされたメンバーを差し引きます。
DELETE Tags :retired
:retired = セット {"beta"} なら、そのメンバーだけが消えます。
ここで 2 つのルールが効いてきます。セットは決して空にできないので、最後のメンバーを削除すると Tags 属性がまるごと削除されます。そして値は属性に一致するセット型でなければならないので、裸の文字列は型エラーです。タグを追加するには、ADD Tags :new で和集合として加えます。
組み合わせる
「リビジョンを追加し、単語数を調整し、リビジョン数を増やし、タグを廃止する」更新は、3 つの句にまたがる 1 回の呼び出しです。
SET Revisions = list_append(if_not_exists(Revisions, :empty), :rev),
WordCount = if_not_exists(WordCount, :zero) + :delta
ADD RevisionCount :one
DELETE Tags :retired
これは新しい記事でも動きます。if_not_exists がリストと単語数を初期化し、ADD はカウントを 0 から始め、存在しないセットへの DELETE は何もしません。WordCount を if_not_exists で包まないと、最初の呼び出しは存在しない属性で失敗します。
WordCount = … + :delta は SET の中の算術で、現在の値に対してサーバー側で評価されます。
各キーワードは 1 回だけ現れるので、2 つ目の ADD アクションはカンマの後に同じ句へ加えます(ADD RevisionCount :one, Tags :new)。ただし、1 回の呼び出しで同じ属性に 2 回触れることはできません。ここで DELETE Tags :retired の隣に Tags :new を加えると、"Two document paths overlap" で失敗します。
避けるべき落とし穴
- 値を読み取ってから
SETで書き戻す。 read-modify-write は並行実行下で更新を失います。算術は式の中に入れ(SET n = n + :xまたはADD)、リトライで二重になりうるカウントに頼る前にアトミックカウンターを確認してください。 - 存在しないリストへの
list_append。 対象をif_not_existsで包まないと、最初の書き込みが失敗します。 REMOVEとDELETEの混同。REMOVEは属性を落とします。DELETEはセットからメンバーを差し引きます。これらを取り違えると、意図した以上に削除します。UpdateItemがアップサートであることを忘れる。 キーが存在しなければ、項目を作成します。「更新だけ」を意図するならConditionExpression(attribute_exists(PK))を追加してください。- 多数の項目を更新する。
UpdateItemが取るキーは 1 つです。QueryかScanでキーを集めて項目ごとにUpdateItemを 1 回送るか、すべて適用されるかまったく適用されないかでなければならない場合は、最大 100 アクションをTransactWriteItemsにまとめます。DynoTable の一括編集は、選択した行に対して設定、削除、追加を実行します。
これらの書き込みをガードするには条件式を、これらの式が実行される対象のキーをモデル化するにはシングルテーブル設計を参照してください。これらのいずれも式ビルダーで構築してコピーし、DynoTable を試して記事の項目を編集し、条件付きの SET/REMOVE として Commit される前に属性ごとの差分を確認してください。



