DynamoDBのアイテムベース操作:GetItem、PutItem、UpdateItem、DeleteItem
DynamoDBのAPIは3つのファミリーに分かれます:プライマリキーで単一のアイテムを操作する
アイテムベースの操作、1つのパーティション内の範囲を読み取るQuery、そして
すべてを読み取るScanです。本ガイドは最初のファミリー — 最もよく使う4つの操作、
GetItem、PutItem、UpdateItem、DeleteItemを扱います。これらはDynamoDBが提供する
中で最も安価で高速な呼び出しであり、その区別(特にPutとUpdate)を正しく理解すれば、
不慮のデータ損失バグの一群を防げます。
DynamoDBのアイテムベース操作とは?
DynamoDBのアイテムベース操作とは、完全なプライマリキーで単一のアイテムを対象とする4つの呼び出しです:GetItemはアイテムを読み取り、PutItemはアイテムを作成または完全に置き換え、UpdateItemは特定の属性をその場で変更し、DeleteItemはアイテムを削除します。それぞれがちょうど1つのアイテムだけを対象とするため、多数のアイテムを読み取るQueryやScanとは違い、最も高速で最も安価な呼び出しになります。
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は本当に
「このアイテムを完全な新しい状態として書き込む」という意味のときだけ使いましょう。
PutItemとUpdateItemはどちらも
条件式を受け付けるので、書き込みを条件付きに
できます(「まだ存在しない場合のみ」)。
DynoTableでのアイテムベース操作
これらの操作の背後にある生のAPI呼び出しを確認したいですか？ DynamoDB式ビルダーで式と型付き値マップを組み立て、 DynamoDB JSONコンバーターでプレーンJSONのアイテムをAPIの型付き形式に変換してください。
DynoTableでは、同じ作業が視覚的になります:グリッドでアイテムを開いて読み取り
(GetItem)、属性を編集してコミットし(UpdateItem)、行を追加または置き換え
(PutItem)、または削除します — 1回に1つのアイテムを。
落とし穴と次のステップ
PutItemはアイテム全体を置き換える — 残りを失わずにいくつかのフィールドを変更する には、UpdateItemを使いましょう。- 完全なプライマリキーを知っている必要がある — キーがないならアイテム操作ではなく Query/Scanです。
- 多数のアイテムを一度に? 1つずつループしてはいけません — バッチ操作はそれらをより少ない往復にまとめます。
- 古い値/新しい値が必要? 後続の
GetItemの代わりにReturnValuesを設定しましょう。 - 関連: QueryとScanが多数読み取り側を扱っています。
1行もAPIコードを書かずにアイテムを読み書き・削除したいですか? DynoTableをダウンロードして、テーブルを直接操作してください。