在 DynamoDB 中使用更新運算式 - Amazon DynamoDB

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

在 DynamoDB 中使用更新運算式

UpdateItem 操作會更新現有項目,如尚不存在,則會將新項目新增到資料表中。您必須提供要更新項目的索引鍵。您也必須提供更新表達式,指出您想要修改的屬性以及您想要指派給它們的值。

更新表達式會指定 UpdateItem 如何修改項目的屬性,例如設定純量值或將元素從清單或映射中刪除。

以下是更新表達式的語法摘要。

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

更新表達式包含一或多個子句。每個子句的開頭是 SETREMOVEADDDELETE 關鍵字。您可以依任意順序在更新表達式中包含其中任何子句。不過,每個動作關鍵字都只能出現一次。

在每個子句內,會有以逗號分隔的一或多個動作。每個動作都會代表資料修改。

本節中的範例是以在 DynamoDB 中使用投影表達式中所顯示的 ProductCatalog 項目為基礎。

以下主題涵蓋了 SET 動作的一些不同使用案例。

SET — 修改或新增項目屬性

在更新表達式中使用 SET 動作,將一或多個屬性新增至項目。這些屬性如已存在,每一個都會為新值所覆寫。如果您想要避免覆寫現有的屬性,您可以SET搭配 使用 if_not_exists functionif_not_exists 函數為 SET 動作專有,而且只能用於更新表達式。

當您使用 SET 更新清單元素時,會將該元素的內容取代為您所指定的新資料。如果元素尚未存在,則 SET 會在清單結尾附加新的元素。

如果您在單一 SET 操作中新增多個元素,則會依元素號碼依序排序元素。

您也可以使用 SET 來加減類型為 Number 的屬性。若要執行多個 SET 動作,請使用逗號分隔它們。

在下列語法摘要中:

  • 所以此 path 元素是項目的文件路徑。

  • 一個 operand 元素可以是項目的文件路徑或函數。

set-action ::= path = value value ::= operand | operand '+' operand | operand '-' operand operand ::= path | function function ::= if_not_exists (path)

如果項目不包含指定路徑的屬性, 會if_not_exists評估為 value。否則,它會評估為 path

下列 PutItem 操作會建立範例參考的範例項目。

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

--item 的引數會存放在 item.json 檔案中。(為求簡化,只會使用一些項目屬性)。

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

修改屬性

範例

更新 ProductCategoryPrice 屬性。

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 檔案中。

{ ":c": { "S": "Hardware" }, ":p": { "N": "60" } }
注意

UpdateItem 操作中,--return-values ALL_NEW 會讓 DynamoDB 傳回在更新後所顯示的項目。

新增清單和映射

範例

新增清單和映射。

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 檔案中。

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

將元素新增至清單

範例

將新的屬性新增至 RelatedItems 清單。(請記住,清單元素的開頭為零,因此 [0] 代表清單中的第一個元素、[1] 代表第二個元素,以此類推)。

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 檔案中。

{ ":ri": { "S": "Nails" } }
注意

當您使用 SET 更新清單元素時,會將該元素的內容取代為您所指定的新資料。如果元素尚未存在,則 SET 會在清單結尾附加新的元素。

如果您在單一 SET 操作中新增多個元素,則會依元素號碼依序排序元素。

新增巢狀映射屬性

範例

新增一些巢狀映射屬性。

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 檔案中。

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

--expression-attribute-values 的引數會存放在 values.json 檔案中。

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

增加和減少數值屬性

您可以新增或扣除現有數值屬性。若要執行此作業,請使用 + (加號) 和 - (減號) 運算子。

範例

減少項目的 Price

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,您要在更新表達式中使用 + 運算子。

將元素附加至清單

您可以將元素新增至清單結尾。若要執行此作業,請搭配使用 SETlist_append 函數 (函數名稱區分大小寫。) list_append 函數為 SET 動作專有,而且只能用於更新表達式。語法如下。

  • list_append (list1, list2)

此函數需要兩個列表作為輸入,並將所有元素從 list2 附加到 list1

範例

將元素新增至清單中,您會建立 RelatedItems 清單,並使用兩個元素填入它:HammerNails。現在,您可在 RelatedItems 結尾多附加兩個元素。

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 檔案中。

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

最後,您將另一個元素附加到 RelatedItems開頭。若要執行此作業,請切換 list_append 元素的順序。(請記住,list_append 採用兩份清單做為輸入,並將第二份清單附加至第一份清單。)

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 屬性現在會包含五個元素,順序如下:ChiselHammerNailsScrewdriverHacksaw

防止覆寫現有屬性

範例

設定項目的 Price,但只有在項目還沒有 Price 屬性時。(如果 Price 已存在,則不會發生任何事。)

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 — 從項目刪除屬性

在更新表達式中使用 REMOVE 動作,從而在 Amazon DynamoDB 中移除項目的一或多個屬性。若要執行多個 REMOVE 動作,請使用逗號分隔它們。

下列是更新表達式中 REMOVE 的語法摘要。唯一的運算元是您想要移除的屬性文件路徑。

remove-action ::= path
範例

移除項目中的一些屬性 (如果屬性不存在,則不會發生任何事。)

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

移除清單中的元素

您可以使用 REMOVE 刪除清單中的個別元素。

範例

將元素附加至清單 中,您修改清單屬性 (RelatedItems),讓它包含五個元素:

  • [0]Chisel

  • [1]Hammer

  • [2]Nails

  • [3]Screwdriver

  • [4]Hacksaw

下列 AWS Command Line Interface (AWS CLI) 範例Nails會從清單中刪除 Hammer和 。

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 — 更新數字和集

注意

一般而言,建議使用 SET,而非 ADD

在更新表達式中使用 ADD 動作,將新的屬性及其值新增至項目。

如果屬性已存在,則 ADD 的行為取決於屬性的資料類型:

  • 如果屬性是數字,而您要新增的值也是數字,則此值會以數學方式新增到現有屬性。(如果值是負數,則會從現有屬性減去。)

  • 如果屬性是集合,而您要新增的值也是集合,則此值會附加至現有集合。

注意

ADD 動作只支援數字和集合資料類型。

若要執行多個 ADD 動作,請使用逗號分隔它們。

在下列語法摘要中:

  • 所以此 path 元素是 屬性的文件路徑。屬性必須是 Number 或集合資料類型。

  • 所以此 value 元素是您要新增至屬性 (適用於Number資料類型) 的數字,或要附加至屬性的集合 (適用於集合類型)。

add-action ::= path value

以下主題涵蓋了 ADD 動作的一些不同使用案例。

新增數字

假設 QuantityOnHand 屬性不存在。下列 AWS CLI 範例QuantityOnHand設定為 5。

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 設定為具有兩個元素的字串集。

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,您可以在其中新增更多元素。

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 動作僅支援 Set 資料類型。

在更新表達式中使用 DELETE 動作,移除集合中的一或多個元素。若要執行多個 DELETE 動作,請使用逗號分隔它們。

在下列語法摘要中:

  • 所以此 path 元素是 屬性的文件路徑。屬性必須是集合資料類型。

  • 所以此 subset 是您要從中刪除的一或多個元素 path。 您必須指定 subset 作為設定類型。

delete-action ::= path subset
範例

將元素新增至集合 中,您會建立 Color 字串集。本範例會從該集合中移除一些元素。

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

使用多個更新表達式

您可以在單一陳述式中使用多個更新表達式。

如果您想要修改屬性的值並完全移除另一個屬性,則可以在單一陳述式中使用 SET和 REMOVE動作。此操作會將 Price 值減少為 15,同時也會從項目中移除 InStock 屬性。

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

如果您想要在變更另一個屬性的值的同時,將 新增至清單,您可以在單一陳述式中使用兩個SET動作。此操作會將「釘子」新增到 RelatedItems 清單屬性中,並將 Price 值設定為 21。

aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"789"}}' \ --update-expression "SET RelatedItems[1] = :newValue, Price = :newPrice" \ --expression-attribute-values '{":newValue": {"S":"Nails"}, ":newPrice": {"N":"21"}}' \ --return-values ALL_NEW