DynamoDBのアイテムベース操作
GetItem、PutItem、UpdateItem、DeleteItemは、それぞれ完全なプライマリキーで指定した1つのアイテムを操作します。キーがわかっている単一のアイテムを読み書きする、最も安価な方法です。
その違い(特にPutとUpdate)を正しく理解すれば、不慮のデータ損失バグの一群を防げます。1回の呼び出しで多数のアイテムを扱うために、DynamoDBには読み取り用の
QueryとScan、そしてバッチ操作とトランザクション操作があります。
DynamoDBのアイテムベース操作とは?
GetItem: 完全なプライマリキーで1つのアイテムを読み取る。PutItem: 1つのアイテムを作成または完全に置き換える。UpdateItem: 1つのアイテムを作成、またはその特定の属性をその場で変更する。DeleteItem: 完全なプライマリキーで1つのアイテムを削除する。- 4つすべてが完全なプライマリキーを必要とする(パーティションキー、テーブルにソートキーがあればそれも)ので、それぞれがちょうど1つのアイテムを指定します。
PutItemはアイテム全体を上書きし、UpdateItemは指定したものだけを変更する。これらを混同すると、属性が静かに消えます。
決定的な特徴:1つのアイテム、完全なキー
すべてのアイテムベース操作は、完全なプライマリキーで単一のアイテムを対象とします。 DynamoDBはパーティションキーをハッシュし、まっすぐそのアイテムにたどり着きます。フィルタリングもスキャンもありません。完全なキーがわからないなら、代わりに QueryとScanを使いましょう。
USER#<id>をキーにしたユーザーアカウントを運用しているとします:
PK: USER#204 email, displayName, plan, createdAtUSER#204に対するGetItem→ そのユーザーに直接アクセス。USER#204に対するDeleteItem→ そのユーザーを削除。
どちらも正確なキーが必要です。
PutItemとUpdateItem:痛い目を見るほう
PutItemはアイテム全体を書き込む。USER#204がすでに存在していて、{email, displayName}だけでPutItemすると、既存のplanとcreatedAt属性は消えます。putはアイテム全体を置き換えるのであって、マージしません。UpdateItemは指定したものだけを変更する。SET email = …を伴うUpdateItemは、他のすべての属性をそのまま残し、アイテムが存在しなければ作成します(upsert)。
経験則:既存のアイテムを変更するならUpdateItemを使い、PutItemは本当に「このアイテムを完全な新しい状態として書き込む」という意味のときだけ使いましょう。どちらも「まだ存在しない場合のみ」のような条件式を受け付けます。
コスト:1つのアイテム、1ホップ
2 KBのアイテムに対するGetItemのコストは、結果整合性で0.5 RCU、強い整合性で
1 RCUです(4 KBブロック1つ、切り上げ)。そのため、キーがわかっている 1つのアイテムを読む最も安価な方法になります。
1つのパーティションキー配下の多数のアイテムなら、Queryのほうがアイテムあたりは安くなります。切り上げる前にそれらのサイズを合算するからです。2 KBのアイテム10件は、
1回のQueryなら結果整合性で2.5 RCU、10回のGetItem呼び出しなら5 RCUかかります
(複合プライマリキー)。
パーティションキーしか知らずアプリケーションコードでフィルタするなら、Queryが読むすべてのアイテム分を払うことになります。
| 操作 | 必要なキー | 典型的な用途 | キャパシティの形 |
|---|---|---|---|
GetItem | 完全なプライマリキー | IDによるポイント読み取り | アイテムサイズ、4 KBあたり |
PutItem | 完全なプライマリキー | アイテム全体の作成または置き換え | 新旧アイテムの大きいほう、1 KBあたり |
UpdateItem | 完全なプライマリキー | 属性のパッチ | 更新前後のアイテムの大きいほう、1 KBあたり |
DeleteItem | 完全なプライマリキー | 行の削除 | 削除したアイテムのサイズ、1 KBあたり |
Query + filter | パーティション(+任意のソート条件) | 1パーティション内の多数のアイテム | 読み取ったアイテムの合計、4 KBあたり |
UpdateItemは、属性を1つ変更するだけでもアイテム全体に課金します。代表的なアイテムをアイテムサイズ計算機で測り、それから料金計算ツールでGetItemのループと1回のQueryの料金を比べましょう。
書き込みの条件式
PutItem、UpdateItem、DeleteItemは任意の条件式を受け付けます。典型的なパターン:
attribute_not_exists(pk)をputに:競合なしの作成専用インサート。attribute_exists(pk)をupdateに:うっかりスタブを作るのを拒否する。plan = :expectedPlanをupdateに:楽観的並行制御。別のライターが先にplanを変更していたら、読み直して再試行する。status = :closedをdeleteに:クローズ済みのチケットだけを削除する。
条件は別途の読み取り料金を加えません。DynamoDBは書き込み中に、保存されているアイテムに対して条件を評価します。条件が失敗した書き込みでも書き込みキャパシティは消費され、
ConditionalCheckFailedExceptionが返されます。
条件はDynamoDB式ビルダーで視覚的に構築し、
ConditionExpressionとExpressionAttributeNames、ExpressionAttributeValuesを
SDK呼び出しにコピーしましょう。
冪等性と上書きの安全性
条件のないPutItemは、アイテム全体に対する最後の書き手が勝つ方式です。WebhookのハンドラーやSQSのコンシューマーでは、処理済みマーカーに対するattribute_not_existsで
putをガードするか、attribute_not_exists(processed)でガードした
SET processed = :trueを使いましょう。
監査ログのために以前の属性値が必要なときは、先行するGetItemの代わりに同じ
UpdateItemにReturnValuesを追加してください。往復は1回、読み取りと書き込みの競合もありません。
正しいアイテム操作を選ぶ
| 意図 | 呼び出し | ガード |
|---|---|---|
| ユーザーIDでプロフィールを読む | GetItem | なし |
| 不在ならユーザーを作成 | PutItem | attribute_not_exists(pk) |
| メールを変更し他のフィールドは保持 | UpdateItem | 任意でemail = :expectedOld |
| 設定ブロブ全体を置き換え | PutItem | ペイロードが完全なときだけ |
| クローズ済みチケットを削除 | DeleteItem | status = :closed |
| 既知のキーで50件のチケットを読む | BatchGetItem | 50回の直列GetItemではなく |
DynoTableでのアイテムベース操作
DynoTableでは、行を開くとクイックビューでアイテムを読み取れ、「Item を編集」を選ぶと変更できます。変更をステージは編集をキューに入れ、コミット前に属性の差分を確認できるようにします。変更を Commitは、ステージとコミットを1つの操作で行います。
どちらの場合も、コミットはアイテムをTransactWriteItems呼び出しとして書き込み、各アイテムは読み取った時点から変更されていないことを条件とします。そのため、コミットした編集はトランザクション書き込みとして、1 KBあたり1ではなく2 WCUで課金されます。
削除して Commit(⌘⇧⌫)は、選択した行を確認のための一時停止なしに即座に削除します。ステージした削除(⌘⌫)は、他の変更と一緒に差分の中で待機します。

同じ呼び出しをコードで書くには、式ビルダーで更新句と条件句を組み立て(SDK v3のスニペットを出力します)、 DynamoDB JSONコンバーターでプレーンJSONのアイテムをAPIの型付き形式に変換しましょう。
落とし穴と次のステップ
PutItemはアイテム全体を置き換える。 残りを失わずにいくつかのフィールドを変更するには、UpdateItemを使いましょう。- 完全なプライマリキーを知っている必要がある。 キーがないならアイテム操作ではなく QueryかScanです。
- 多数のアイテムを一度に? 1つずつループしてはいけません: バッチ操作はそれらをより少ない往復にまとめます。
- 古い値/新しい値が必要? 後続の
GetItemの代わりにReturnValuesを設定しましょう。 - 関連: QueryとScanが多数読み取り側を扱っています。
DynoTableをダウンロードして、自分のテーブルに対して単一のアイテムを読み取り、編集し、コミットしましょう。ステージした編集は、コミット前に差分として表示されます。


