メニュー
Amazon DynamoDB
開発者ガイド (API Version 2012-08-10)

DynamoDB での項目の操作

DynamoDB では、項目は属性の集まりです。各属性には名前と値があります。属性値はスカラー型、セット型、ドキュメント型のいずれかです。詳細については、「Amazon DynamoDB: 仕組み」を参照してください。

DynamoDB は、作成、読み込み、更新、削除 (CRUD) の 4 つの基本的なオペレーション機能を提供します。

  • PutItem – 項目を作成します。

  • GetItem – 項目を読み込みます。

  • UpdateItem – 項目を更新します。

  • DeleteItem – 項目を削除します。

これらの各オペレーションでは、作業対象の項目のプライマリキーを指定する必要があります。たとえば、GetItem を使用して項目を読み込むには、その項目のパーティションキーとソートキー (該当する場合) を指定する必要があります。

4 つの基本的な CRUD オペレーションに加えて、DynamoDB は以下も提供します。

  • BatchGetItem – 1 つ以上のテーブルから最大 100 の項目を読み取ります。

  • BatchWriteItem – 1 つ以上のテーブルから最大 25 の項目を作成または削除します。

これらのバッチ操作は、複数の CRUD オペレーションを単一のリクエストにまとめます。さらに、応答のレイテンシーを最小限に抑えるため、バッチオペレーションは項目を並列で読み書きします。

このセクションには、これらのオペレーションを使用する方法の説明、および、条件付き更新やアトミックカウンターなどの関連するトピックが含まれています。このセクションには、AWS SDK を使用するサンプルコードも含まれています。ベストプラクティスについては、項目のベストプラクティス を参照してください。

項目を読み込む

DynamoDB テーブルから項目を読み込むには、GetItem オペレーションを使用します。必要な項目のプライマリキーと共にテーブルの名前を指定する必要があります。

次の AWS CLI の例は、ProductCatalog テーブルから項目を読み込む方法を示しています。

Copy
aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}'

注記

GetItem では、プライマリキーの一部だけではなく全体を指定する必要があります。たとえば、テーブルに複合プライマリキー (パーティションキーおよびソートキー) がある場合、パーティションキーおよびソートキーの値を指定する必要があります。

デフォルトでは、GetItem リクエストは結果的に整合性のある読み込みを行います。代わりに、ConsistentRead パラメータを使用して、強い整合性のある読み込みをリクエストできます。(これは、追加の読み込みキャパシティーユニットを消費しますが、項目の最新バージョンを返します。)

GetItem は、項目のすべての属性を返します。一部の属性のみが返されるように、プロジェクション式を使用できます。(詳しくは、プロジェクション式 を参照してください)。

GetItem で消費される読み込みキャパシティーユニットの数を返すには、ReturnConsumedCapacity パラメータを TOTAL に設定します。

次の AWS CLI の例は、オプションの GetItem パラメータを示しています。

Copy
aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --consistent-read \ --projection-expression "Description, Price, RelatedItems" \ --return-consumed-capacity TOTAL

項目を書き込む

DynamoDB テーブルの項目を作成、更新、または削除するには、次のオペレーションのいずれかを使用します。

  • PutItem

  • UpdateItem

  • DeleteItem

これらの各オペレーションで、プライマリキーの一部の属性ではなくすべての属性を指定する必要があります。たとえば、テーブルに複合プライマリキー (パーティションキーおよびソートキー) がある場合、パーティションキーおよびソートキーの値を指定する必要があります。

これらのオペレーションのいずれかで消費される書き込みキャパシティーユニットの数を返すには、ReturnConsumedCapacity パラメータを次のいずれかに設定します。

  • TOTAL—消費された書き込みキャパシティーユニットの総数を返します。

  • INDEXES—消費された書き込みキャパシティーユニットの総数とともに、テーブルおよびオペレーションに影響を受けた セカンダリインデックス の小計を返します。

  • NONE—書き込みキャパシティーの詳細は返されません。(これがデフォルトです)

PutItem

PutItem 新しい項目を作成します。同じキーを持つ項目がテーブルにすでに存在する場合は、新しい項目に置き換えられます。

Thread テーブルに新しい項目を書き込みます。Thread のプライマリキーは、ForumName(パーティションキー) と Subject(ソートキー) で構成されます。

Copy
aws dynamodb put-item \ --table-name Thread \ --item file://item.json

--item の引数は、ファイル item.json に保存されます。

Copy
{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"}, "Message": {"S": "First post in this thread"}, "LastPostedBy": {"S": "fred@example.com"}, "LastPostDateTime": {"S": "201603190422"} }

UpdateItem

指定されたキーを持つ項目が存在しない場合は、UpdateItem により新しい項目が作成されます。または、既存の項目の属性が変更されます。

更新式を使用して、変更する属性と新しい値を指定します。 (詳細については、「更新式」を参照してください)。更新式では、実際の値にプレースホルダーとして式の属性値を使用します。(詳しくは、式の属性値 を参照してください)。

Thread 項目の様々な属性を変更します。オプションの ReturnValues パラメータは、更新後に表示されるように項目を表示します。(詳しくは、戻り値 を参照してください)。

Copy
aws dynamodb update-item \ --table-name Thread \ --key file://key.json \ --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \ --expression-attribute-values file://expression-attribute-values.json \ --return-values ALL_NEW

--key の引数は、ファイル key.json に保存されます。

Copy
{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"} }

--expression-attribute-values の引数は、ファイル expression-attribute-values.json に保存されます。

Copy
{ ":zero": {"N":"0"}, ":lastpostedby": {"S":"barney@example.com"} }

DeleteItem

DeleteItem は指定されたキーを持つ項目を削除します。

この AWS CLI の例は、Thread 項目を削除する方法を示しています。

Copy
aws dynamodb delete-item \ --table-name Thread \ --key file://key.json

戻り値

場合によっては、ある属性値を変更する前後にその属性値が表示されるように DynamoDB で 返すこともできます。PutItemUpdateItem、および DeleteItem オペレーションには、ReturnValues パラメータがあり、これを使用することで、属性の変更前後に、その属性値を返すことができます。

ReturnValues のデフォルトの値は NONE で、DynamoDB は変更された属性の情報を返しません。

以下は DynamoDB API オペレーションごとに整理された ReturnValues のその他の有効な設定です。

PutItem

  • ReturnValues: ALL_OLD

    • 既存の項目に上書きする場合、ALL_OLD は上書きの前に表示されたように、項目全体を返します。

    • 存在しない項目を書き込んだ場合は、ALL_OLD による影響はありません。

UpdateItem

UpdateItem の最も一般的な使用方法は、既存の項目の更新です。ただし、UpdateItem は実際にはアップサートを実行します。つまり、項目が存在しない場合は、自動的に作成します。

  • ReturnValues: ALL_OLD

    • 既存の項目を更新する場合、ALL_OLD は更新前に表示されたように、項目全体を返します。

    • 存在しない項目を更新 (アップサート) すると、ALL_OLD による影響はありません。

  • ReturnValues: ALL_NEW

    • 既存の項目を更新する場合、ALL_NEW は更新後に表示されるように、項目全体が返されます。

    • 存在しない項目を更新 (アップサート) すると、ALL_NEW は項目全体を返します。

  • ReturnValues: UPDATED_OLD

    • 既存の項目を更新した場合、UPDATED_OLD は、更新前に表示されたように、更新された属性だけを返します。

    • 存在しない項目を更新 (アップサート) すると、UPDATED_OLD による影響はありません。

  • ReturnValues: UPDATED_NEW

    • 既存の項目を更新した場合、UPDATED_NEW は、更新後に表示されるように、影響のある属性だけを返します。

    • 存在しない項目を更新 (アップサート) する場合、UPDATED_NEW は更新後に表示される、更新された属性だけを返します。

DeleteItem

  • ReturnValues: ALL_OLD

    • 既存の項目を削除すると、ALL_OLD は削除の前に表示されたように、項目全体を返します。

    • 存在しない項目を削除すると、ALL_OLD はデータを返しません。

バッチオペレーション

複数の項目の読み込みや書き込みを必要とするアプリケーションのために、DynamoDB は BatchGetItem および BatchWriteItem オペレーションを提供します。これらのオペレーションを使用すると、アプリケーションから DynamoDB へのネットワークラウンドトリップの数を減らすことができます。さらに、DynamoDB は個別の読み込みまたは書き込みオペレーションを並行して実行します。同時実行またはスレッディングの管理をする必要がないので、アプリケーションにはこの並列処理が役立ちます。

バッチオペレーションは、基本的に複数の読み込みまたは書き込みリクエストをまとめます。たとえば、BatchGetItem リクエストに 5 つの項目が含まれている場合、DynamoDB によって 5 回の GetItem オペレーションが実行されます。同様に、BatchWriteItem リクエストに 2 つの入力リクエストと 4 つの削除リクエストが含まれている場合、DynamoDB によって 2 つの PutItem リクエストと 4 つの DeleteItem リクエストが実行されます。

一般的に、バッチのすべてのリクエストが失敗しない限り、バッチオペレーションは失敗しません。たとえば、BatchGetItem オペレーションを実行する際、バッチの個々の GetItem リクエストが失敗したとします。この場合、BatchGetItem は失敗した GetItem リクエストからキーとデータを返します。バッチのその他の GetItem リクエストは影響を受けません。

BatchGetItem

1 回の BatchGetItem オペレーションには、最大 100 の個々の GetItem リクエストが含まれていて、最大 16 MB のデータを取得できます。さらに、BatchGetItem オペレーションで、複数のテーブルから項目を取得できます。

一部の属性のみが返されるようにプロジェクション式を使用して Thread テーブルから 2 つの項目を取得します。

Copy
aws dynamodb batch-get-item \ --request-items file://request-items.json

--request-items の引数は、ファイル request-items.json に保存されます。

Copy
{ "Thread": { "Keys": [ { "ForumName":{"S": "Amazon DynamoDB"}, "Subject":{"S": "DynamoDB Thread 1"} }, { "ForumName":{"S": "Amazon S3"}, "Subject":{"S": "S3 Thread 1"} } ], "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies" } }

BatchWriteItem

BatchWriteItem オペレーションには最大 25 の個々の PutItemDeleteItem リクエストを含むことができ、最大 16 MB のデータを書き込めます。(個々の項目の最大サイズは 400 KB です)さらに、BatchWriteItem オペレーションで、複数のテーブルの項目を入力したり削除したりできます。

注記

BatchWriteItem では UpdateItem リクエストはサポートされません。

ProductCatalog テーブルに 2 つの項目を書き込みます。

Copy
aws dynamodb batch-write-item \ --request-items file://request-items.json

--request-items の引数は、ファイル request-items.json に保存されます。

Copy
{ "ProductCatalog": [ { "PutRequest": { "Item": { "Id": { "N": "601" }, "Description": { "S": "Snowboard" }, "QuantityOnHand": { "N": "5" }, "Price": { "N": "100" } } } }, { "PutRequest": { "Item": { "Id": { "N": "602" }, "Description": { "S": "Snow shovel" } } } } ] }

アトミックカウンタ

UpdateItem オペレーションを使用して、アトミックカウンターを実装できます。このカウンターは、その他の書き込みリクエストを妨害することなく、無条件で増分される数値属性です。(すべての書き込みリクエストは、受信された順に適用されます)。アトミックカウンターでは、更新はべき等ではありません。つまり、UpdateItem を呼び出すたびに数値はインクリメントされます。

ウェブサイトの訪問者数を追跡するためにアトミックカウンターを使用できます。この場合、アプリケーションでは、現在値に関係なく、数値はインクリメントされます。UpdateItem オペレーションが失敗した場合、アプリケーションはオペレーションを再試行します。これには、カウンターを 2 度更新する恐れがありますが、ウェブサイトの訪問者数のカウントに多少の誤差があっても許容できるでしょう。

アトミックカウンターはカウントの誤差が許容されない場合にはふさわしくありません (銀行業務用のアプリケーションなど)。このような場合は、アトミックカウンターの代わりに条件付き更新を使用する方が安全です。

詳細については、「数値属性の増減」を参照してください。

以下の AWS CLI の例では、商品の Price が 5 でインクリメントされます。UpdateItem はべき等ではないので、Price はこの例を実行するたびに増えていきます。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": { "N": "601" }}' \ --update-expression "SET Price = Price + :incr" \ --expression-attribute-values '{":incr":{"N":"5"}}' \ --return-values UPDATED_NEW

条件付きの書き込み

デフォルトでは、DynamoDB 書き込みオペレーション (PutItemUpdateItemDeleteItem) は無条件です。つまり、これらの各オペレーションでは、指定のプライマリキーを持つ既存の項目が上書きされます。

DynamoDB はオプションでこれらのオペレーションの条件付き書き込みをサポートしています。条件付き書き込みが成功するのは、項目の属性が 1 つ以上の想定条件を満たす場合のみです。それ以外の場合は、エラーが返されます。条件付き書き込みは多くの状況で役立ちます。たとえば、同じプライマリキーを持つ既存の項目がない場合にのみ、PutItem オペレーションが成功するようにできます。または、属性の 1 つに特定の値がある場合に UpdateItem オペレーションが項目を変更することを防ぐことができます。

条件付き書き込みは、複数のユーザーが同じ項目を変更しようとする場合に役立ちます。2 人のユーザー (Alice と Bob) が DynamoDB テーブルから同じ項目を処理している以下の図を考慮します。

Alice が AWS CLI を使用して Price 属性を 8 に更新するとします。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --expression-attribute-values file://expression-attribute-values.json

--expression-attribute-values の引数は、ファイル expression-attribute-values.json に保存されます。

Copy
{ ":newval":{"N":"8"} }

次に、Bob が後で同様の UpdateItem リクエストを発行しますが、Price を 12 に変更します。Bob には、--expression-attribute-values パラメータは次のように見えます。

Copy
{ ":newval":{"N":"12"} }

Bob のリクエストは成功しますが、その前の Alice の更新は失われます。

条件付き PutItemDeleteItem、または UpdateItem をリクエストするには、条件式を指定します。条件式は、属性名、条件付き演算子および組み込み関数を含む文字列です。式全体の評価結果が true になる必要があります。そうでない場合、オペレーションは失敗します。

次は、条件付き書き込みにより Alice の更新が上書きされるのを防ぐ方法について、以下の図を考慮します。

Alice はまず Price を 8 に更新しますが、現在の Price が 10 である場合にのみ、という条件でそうします。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --condition-expression "Price = :currval" \ --expression-attribute-values file://expression-attribute-values.json

--expression-attribute-values の引数は、ファイル expression-attribute-values.json に保存されます。

Copy
{ ":newval":{"N":"8"}, ":currval":{"N":"10"} }

条件が true に評価されるため、Alice の更新は成功します。

次に、Bob は、Price を 12 に 更新しますが、現在の Price が 10 である場合にのみ、という条件でそうします。Bob には、--expression-attribute-values パラメータは次のように見えます。

Copy
{ ":newval":{"N":"12"}, ":currval":{"N":"10"} }

Alice がすでに Price を 8 に変更していたので、条件式は false 評価され Bob の更新は失敗します。

詳細については、「条件式」を参照してください。

条件付き書き込みのべき等性

条件付き書き込みはべき等のオペレーションです。つまり、同じ条件付き書き込みリクエストを DynamoDB に何度も送信できますが、更新が DynamoDB によって最初に実行された後は、リクエストがあってもそれ以上項目への影響はありません。

たとえば、UpdateItem リクエストを発行し、項目の Price を、現在の Price が 20 である場合のみ、3 増加させるとします。リクエストを送信した後、その結果を得る前にネットワークエラーが発生したため、リクエストが成功したかどうか不明です。条件付き書き込みはべき等のオペレーションであるため、同じ UpdateItem リクエストを再試行できます。すると、DynamoDB は項目の現在の Price が 20 である場合のみ更新します。

条件付き書き込みにより消費されるキャパシティーユニット

条件付き書き込み中に ConditionExpression が false と評価された場合でも、DynamoDB はテーブルから書き込みキャパシティーを消費します。

  • 項目が現在テーブルに存在しない場合、DynamoDB は 1 つの書き込みキャパシティーユニットを消費します。

  • 項目が存在する場合、消費される書き込みキャパシティーユニットの数は、項目のサイズによって異なります たとえば、1 KB の項目の条件付き書き込みが失敗すると、1 つの書き込みキャパシティーユニットが消費されます。項目のサイズがその倍である場合、条件付き書き込みが失敗すると、2 つの書き込みキャパシティーユニットが消費されます。

注記

書き込みオペレーションでは、書き込みキャパシティーユニットのみが消費されます。読み込みキャパシティーユニットは消費されません。

条件付き書き込みが失敗した場合は、ConditionalCheckFailedException が返されます。これが起きたら、応答で消費された書き込みキャパシティーに関する情報は送られてきません。ただし、Amazon CloudWatch のテーブルで ConsumedWriteCapacityUnits メトリクスを表示できます。(詳細については、「DynamoDB のモニタリング」の「DynamoDB メトリクス」を参照してください。)

条件付き書き込みの際に消費された書き込みキャパシティユニットの数を返すには、ReturnConsumedCapacity パラメータを使用します。

  • TOTAL—消費された書き込みキャパシティーユニットの総数を返します。

  • INDEXES—消費された書き込みキャパシティーユニットの総数とともに、テーブルおよびオペレーションに影響を受けた セカンダリインデックス の小計を返します。

  • NONE—書き込みキャパシティーの詳細は返されません。(これがデフォルトです)

注記

local secondary indexは、グローバルセカンダリインデックスとは異なり、プロビジョニングされたスループット容量をそのテーブルと共有します。local secondary indexでの読み取りと書き込みのアクティビティは、テーブルからプロビジョニングされたスループット容量を消費します。