中級読了 1 分

DynamoDBのReturnValues:古いまたは新しいアイテムを取得する

デフォルトでは、DynamoDBの書き込みは成功以外に何も返しません。ReturnValuesは、書き込み自体に、書き込み前の状態または書き込み後の状態のアイテムを返すよう求めます。

DynamoDBのReturnValuesは何をするのか?

ReturnValuesは、DynamoDBの書き込みに対して同じ呼び出しの中でアイテムを返すよう指示します。これにより、2回目のGetItemとそれが生む競合状態を回避できます。PutItemとDeleteItemはNONEまたはALL_OLDを受け付け、UpdateItemは5つすべて(NONE、ALL_OLD、UPDATED_OLD、ALL_NEW、UPDATED_NEW)を受け付け、古いまたは新しい値をアトミックに返します。

  • UPDATED_NEWは、今インクリメントしたカウンターを同じ呼び出しで読み戻します。
  • ALL_OLDは監査ログ用の変更前イメージを、書き込み時点の状態のまま、書き込み自体から取得します。
  • 返された属性に読み取りユニットは消費されません。
  • 条件が失敗したときは、2つ目のパラメータ ReturnValuesOnConditionCheckFailureが、例外の中で現在のアイテムを返します。

問題:今上書きした値が必要

サポートデスクを運用していて、担当者がチケットのステータスをopenからpendingに変更するとします。監査ログには、変更前のステータスが何だったかを記録する必要があります。ReturnValuesがなければ、こうするでしょう:

  1. 現在のステータスを読み取るGetItem、
  2. 新しいものを設定するUpdateItem。

ステップ1と2の間に別の担当者がステータスを変更するかもしれず、すると監査ログは古い「変更前」の値を記録してしまいます。しかも、1つの論理的な操作に対して2回の呼び出しです。

ReturnValuesはこれを、書き込み時点で実際にそうだった古いステータスを返す、単一のアトミックなUpdateItemにまとめます。

5つの選択肢と、それぞれの使いどころ

選択は、アイテムのどの部分と書き込みのどちら側が必要かです:

ReturnValues返すもの対象使う場面
NONEなし(デフォルト)Put, Update, Deleteアイテムを返す必要がない
ALL_OLDアイテム全体、書き込み前Put, Update, Delete監査 / 「今何を置き換えた?」
UPDATED_OLD触れた属性、書き込み前Update変更したフィールドだけをログに記録する場合
ALL_NEWアイテム全体、書き込み後Update新しいアイテムを呼び出し元に返す場合
UPDATED_NEW触れた属性、書き込み後Update今インクリメントしたカウンターを読み戻す場合

「触れた」とは、値が変わらなかったものも含めて、更新式で名前を挙げたすべての属性を意味します。すでにその値だったstatusにSET status = :sしても、statusは返されます。

サポートチケットの監査では、ALL_OLD(ステータスフィールドだけをログに記録するなら UPDATED_OLD)が変更前の状態をアトミックに捉えます。

非対称性に注目してください:PutItemとDeleteItemはNONEとALL_OLDのみをサポートします。deleteには返すべき「新しい」値がなく、putの新しい値はまさに送ったものだからです。AWSのドキュメントに正確な対応表があります。

UPDATED_NEWでカウンターを読み戻す

更新式でversion属性をインクリメントし、同じ呼び出しで新しい値を読み取ります:

UpdateItem  PK=TICKET#8842
  UpdateExpression: ADD version :one
  ExpressionAttributeValues: {":one": {"N": "1"}}
  ReturnValues: UPDATED_NEW
→ Attributes.version.N == "41"   (was 40)

受け取るのは触れた属性だけで、アイテム全体ではありません。アイテムが大きく、呼び出し元が 1つの数値だけを必要とする場合に向いています。カウンターについて、そしてリトライした ADDが二重にカウントされる理由については:アトミックカウンター。

条件が失敗したときにアイテムを取得する

ReturnValuesと条件式は、同じ呼び出しの中で組み合わせられます。上限を下回っている間だけretryCountをインクリメントし、新しいカウントを返します。存在しない属性との比較は偽になるので、attribute_not_existsの側が最初の呼び出しを通します:

UpdateItem  PK=JOB#1
  ConditionExpression: attribute_not_exists(retryCount) OR retryCount < :max
  UpdateExpression: ADD retryCount :one
  ExpressionAttributeValues: {":one": {"N": "1"}, ":max": {"N": "3"}}
  ReturnValues: UPDATED_NEW
  ReturnValuesOnConditionCheckFailure: ALL_OLD
→ 1st call:  Attributes.retryCount.N == "1"
→ 3rd call:  Attributes.retryCount.N == "3"
→ 4th call:  ConditionalCheckFailedException with Item.retryCount.N == "3"

ReturnValuesが値を入れるのは成功したレスポンスだけです。条件が失敗すると ConditionalCheckFailedExceptionが返ります。

ReturnValuesOnConditionCheckFailure: ALL_OLDを指定すると、例外が現在の状態のアイテムを運んできます(JavaScript SDK v3ではerr.Item)。受け付けるのはALL_OLDか NONEだけで、読み取りユニットはかかりません。

楽観的ロックのリトライに使いましょう:GetItemなしで現在のバージョンを得て、再計算し、再送します。信頼できないクライアントにそれをそのまま返してはいけません。そのケースは一意性のガイドで扱っています。

削除とput

ReturnValues: ALL_OLDを付けたDeleteItemは、キューのアイテムに対して「取り出して返す」セマンティクスを実装する方法です:削除されたアイテムがAttributesに返ってきます。deleteに ALL_NEWがないのは、アイテムがもう存在しないからです。

ALL_OLDを付けたPutItemは、既存のキーを上書きしたときに以前のアイテムを返すので、入れ替えのワークフローに便利です。キーが存在しなかった場合、レスポンスにAttributesは含まれません。

キャパシティに関する注意

返された属性は無料です。AWSは "No read capacity units are consumed." と述べています。書き込みは通常どおり、更新前と更新後のアイテムサイズの大きいほうに基づき、1 KB単位で課金されます。返ってくる属性がいくつあっても変わりません。

古い値を記録するためにGetItemしてからUpdateItemしようとしていたなら、読み取り1回分と書き込み1回分を支払っていたことになります。2 KBのアイテムを毎秒500回更新する場合、やめられる強い整合性の読み取りは1回あたり1 RCUで、毎秒500 RCUです。

結果整合性の読み取りならその半分(毎秒250 RCU)ですが、古い「変更前」の値を返すことがあり、それはまさに最初の問題そのものです。

DynoTableで変更前と変更後を確認する

UpdateItemとその更新式はDynamoDB式ビルダーで組み立てましょう。SET/ADD句に加えて、属性名と値のマップを出力します。

DynoTableでは、アイテムエディタで属性の変更をステージし、保留中の変更で並列差分を開きます。コミット前に、古い値と新しい値が並んで表示されます。

古い側はDynoTableが読み込んだ時点のアイテムで、コミットは条件付きなので、その間に誰かがアイテムを変更していれば競合になります。コミット後は、グリッドから形式を選んでコピーでJSONをコピーし、テストフィクスチャに使えます。

DynoTableでアイテムのステージ済み変更を確認しているところ:更新がコミットされる前の古い値と新しい値。
DynoTableでアイテムのステージ済み変更を確認しているところ:更新がコミットされる前の古い値と新しい値。

落とし穴と次のステップ

  • 変更の前後を読むためにGetItemしてから書き込んではいけない。 往復であり競合です。 ReturnValuesを使いましょう。
  • UPDATED_*は触れた属性のみを返す。 アイテム全体が必要ならALL_*を使いましょう。
  • ReturnValuesは条件の代わりにはならない。 書き込みをガードするには条件式を追加し、その効果を読み戻すには ReturnValuesを使いましょう。両者は組み合わせられます。
  • 関連: 更新式、アトミックカウンター。

2回の呼び出しをスクリプトで書かずに編集を行い、変更前後を確認したいですか? DynoTableをダウンロードして、各編集をコミット前に変更前/変更後の差分として確認してください。

著者: Dmitriy · 更新日