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

更新式

テーブルの既存の項目を更新するには、UpdateItem オペレーションを使用します。更新する項目のキーを指定する必要があります。また、変更する属性を示す更新式と、その式に割り当てる値も指定する必要があります。

更新式は、UpdateItem がスカラー値の設定、リストやマップでの要素の削除など、項目の属性を変更する方法も指定します。

更新式の構文の概要を次に示します。

Copy
update-expression ::= [ SET action [, action] ... ] [ REMOVE action [, action] ...] [ ADD action [, action] ... ] [ DELETE action [, action] ...]

更新式は、1 つ以上の句で構成されます。各句は、SETREMOVEADD、または DELETE キーワードで始まります。これらのいずれの句も、任意の順序で更新式に含めることができます。ただし、各アクションキーワードは 1 回のみ表示できます。

各句内には、カンマで区切った 1 つ以上のアクションがあります。各アクションはデータ変更を表します。

このセクションの例は、「プロジェクション式」の ProductCatalog 項目に基づいています。

SET - 項目の属性の変更または追加

1 つ以上の属性を項目に追加するには、更新式で SET アクションを使用します。これらのいずれかの属性が既に存在する場合、新しい値で上書きされます。

SET を使用して、数値型である属性を増減することもできます。複数の SET アクションを実行するには、オペレーションをカンマで区切ります。

次の構文の概要について説明します。

  • path 要素は、項目へのドキュメントパスです。

  • operand 要素は、項目へのドキュメントパスまたは関数とすることができます。

Copy
set-action ::= path = value value ::= operand | operand '+' operand | operand '-' operand operand ::= path | function

次の PutItem オペレーションは、例で参照するサンプル項目を作成します。

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

--item の引数は、ファイル item.json に保存されます。(分かりやすいように、いくつかの項目属性のみが使用されます)

Copy
{ "Id": {"N": "789"}, "ProductCategory": {"S": "Home Improvement"}, "Price": {"N": "52"}, "InStock": {"BOOL": true}, "Brand": {"S": "Acme"} }

属性の変更

ProductCategoryPrice 属性を更新します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET ProductCategory = :c, Price = :p" \ --expression-attribute-values file://values.json \ --return-values ALL_NEW

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

Copy
{ ":c": { "S": "Hardware" }, ":p": { "N": "60" } }

注記

UpdateItem オペレーションでは、--return-values ALL_NEW により DynamoDB は更新後に表示される項目を返します。

リストおよびマップの追加

新しいリストおよび新しいマップを追加します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET RelatedItems = :ri, ProductReviews = :pr" \ --expression-attribute-values file://values.json \ --return-values ALL_NEW

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

Copy
{ ":ri": { "L": [ { "S": "Hammer" } ] }, ":pr": { "M": { "FiveStar": { "L": [ { "S": "Best product ever!" } ] } } } }

リストに要素を追加

新しい属性を RelatedItems リストに追加します。リストの要素はゼロベースであるため、[0] はリスト内の最初の要素、[1] は 2 番目の要素、という順番で表されることに注意してください。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET RelatedItems[1] = :ri" \ --expression-attribute-values file://values.json \ --return-values ALL_NEW

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

Copy
{ ":ri": { "S": "Nails" } }

注記

SET を使用してリスト要素を更新すると、その要素のコンテンツは、指定した新しいデータで置き換えられます。要素が既に存在していない場合、SET はリストの末尾に新しい要素を追加します。

1 つの SET オペレーションに複数の要素を追加すると、要素は要素番号で順にソートされます。

ネストされたマップ属性の追加

ネストされたマップ属性を追加します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET #pr.#5star[1] = :r5, #pr.#3star = :r3" \ --expression-attribute-names file://names.json \ --expression-attribute-values file://values.json \ --return-values ALL_NEW

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

Copy
{ "#pr": "ProductReviews", "#5star": "FiveStar", "#3star": "ThreeStar" }

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

Copy
{ ":r5": { "S": "Very happy with my purchase" }, ":r3": { "L": [ { "S": "Just OK - not that great" } ] } }

数値属性の増減

既存の数値属性は増減することができます。これを行うには、+(プラス)および -(マイナス)演算子を使用します。

項目の Price を下げます。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET Price = Price - :p" \ --expression-attribute-values '{":p": {"N":"15"}}' \ --return-values ALL_NEW

Price を上げるために、更新式で + オペレーションを使用します。

リストに要素を追加

リストの最後に要素を追加できます。これを行うには、list_append 関数の SETを使用します。(関数名では大文字と小文字が区別されます)list_append 関数は SET アクションに固有で、更新式でのみ使用できます。構文は次のとおりです。

  • list_append (list1, list2)

この関数は入力として 2 つのリストを取得し、 list1list2 を追加します。

リストに要素を追加 で、RelatedItems リストを作成し、HammerNails の 2 つの要素を入力しました。次に、RelatedItems の末尾にさらに 2 つの要素を追加します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET #ri = list_append(#ri, :vals)" \ --expression-attribute-names '{"#ri": "RelatedItems"}' \ --expression-attribute-values file://values.json \ --return-values ALL_NEW

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

Copy
{ ":vals": { "L": [ { "S": "Screwdriver" }, {"S": "Hacksaw" } ] } }

最後に、RelatedItems先頭 にもう 1 つの要素を追加します。これを行うには、list_append 要素の順序を入れ替えます。(list_append は 2 つのリストを入力し、1 番目のリストに 2 番目のリストを追加することに注意してください)

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET #ri = list_append(:vals, #ri)" \ --expression-attribute-names '{"#ri": "RelatedItems"}' \ --expression-attribute-values '{":vals": {"L": [ { "S": "Chisel" }]}}' \ --return-values ALL_NEW

生成される RelatedItems 属性には次の順序で 5 つの要素が含まれます。ChiselHammerNailsScrewdriverHacksaw

既存の属性の上書きを防止

既存の属性の上書きを回避するには、SETif_not_exists 関数を使用できます。(関数名では大文字と小文字が区別されます)if_not_exists 関数は SET アクションに固有で、更新式でのみ使用できます。構文は次のとおりです。

  • if_not_exists (path, value)

指定された path で項目が属性を含まない場合、if_not_existsvalue に評価されます。それ以外の場合は、path に評価されます。

項目にすでに Price 属性がない場合にのみ、項目の Price 属性を設定します。(Price がすでにある場合は何も起こりません)

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET Price = if_not_exists(Price, :p)" \ --expression-attribute-values '{":p": {"N": "100"}}' \ --return-values ALL_NEW

REMOVE - 項目から属性を削除

1 つ以上の属性を項目から削除するには、更新式で REMOVE アクションを使用します。複数の REMOVE アクションを実行するには、オペレーションをカンマで区切ります。

更新式の REMOVE の構文の概要を次に示します。唯一のオペランドは、削除する属性のドキュメントパスです。

Copy
remove-action ::= path

項目から属性を削除します。(属性が存在しない場合は、何も起こりません)

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "REMOVE Brand, InStock, QuantityOnHand" \ --return-values ALL_NEW

リストから要素を削除

REMOVE を使用して、リストから個別要素を削除できます。

リストに要素を追加 で、リスト属性 (RelatedItems) を変更したため、5 つの要素を含みます。

  • [0] - Chisel

  • [1] - Hammer

  • [2] - Nails

  • [3] - Screwdriver

  • [4] - Hacksaw

次の AWS CLI の例では、リストから HammerNails を削除します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \ --return-values ALL_NEW

HammerNails を削除すると、残りの要素は変わります。リストには以下が含まれます。

  • [0] - Chisel

  • [1] - Screwdriver

  • [2] - Hacksaw

ADD - 数値とセットの更新

注記

通常は、ADD ではなく SET を使用することをお勧めします。

項目に新しい属性および値を追加するには、更新式で ADD アクションを使用します。

属性が既に存在する場合、ADD の動作は属性のデータ型によって決まります。

  • 属性が数値で、追加する値も数値である場合、値は既存の属性に数学的に追加されます(値が負の数値である場合は、既存の属性から減算されます)。

  • 属性が設定され、追加する値も設定された場合、値は既存のセットに付加されます。

注記

ADD アクションでは、数値とセットデータ型のみがサポートされます。

複数の ADD アクションを実行するには、オペレーションをカンマで区切ります。

次の構文の概要について説明します。

  • path 要素は、属性へのドキュメントパスです。属性は数値またはセットデータ型である必要があります。

  • value 要素は、属性に追加する数値(数値データ型の場合)、または属性に付加するセット(セットデータ型の場合)です。

Copy
add-action ::= path value

数値の追加

QuantityOnHand 属性が存在しないと想定します。次の AWS CLI の例では、QuantityOnHand を 5 に設定します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "ADD QuantityOnHand :q" \ --expression-attribute-values '{":q": {"N": "5"}}' \ --return-values ALL_NEW

これで QuantityOnHand が存在するようになったので、QuantityOnHand が毎回 5 増分するように例を再実行できます。

セットに要素を追加

Color 属性が存在しないと想定します。次の AWS CLI の例では、Color を 2 つの要素を持つ文字列セットに設定します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "ADD Color :c" \ --expression-attribute-values '{":c": {"SS":["Orange", "Purple"]}}' \ --return-values ALL_NEW

これで Color が存在するので、さらに要素を追加できます。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "ADD Color :c" \ --expression-attribute-values '{":c": {"SS":["Yellow", "Green", "Blue"]}}' \ --return-values ALL_NEW

DELETE - セットから要素を削除

重要

DELETE アクションは、セットデータ型のみをサポートします。

1 つ以上の要素をセットから削除するには、更新式で DELETE アクションを使用します。複数の DELETE アクションを実行するには、オペレーションをカンマで区切ります。

次の構文の概要について説明します。

  • path 要素は、属性へのドキュメントパスです。属性はセットデータ型である必要があります。

  • サブセットpath から削除する 1 つ以上の要素です。サブセットはセット型として指定する必要があります。

Copy
delete-action ::= path value

セットに要素を追加 で、Colors 文字列セットを作成しました。この例では、セットから要素の一部を削除します。

Copy
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "DELETE Color :p" \ --expression-attribute-values '{":p": {"SS": ["Yellow", "Purple"]}}' \ --return-values ALL_NEW