Update Expressions - Amazon DynamoDB
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Update Expressions

要更新 Amazon DynamoDB 表中的现有项目,请使用 UpdateItem 操作。您必须提供要更新的项目的键。您还必须提供更新表达式,指示您要修改的属性以及要分配给这些属性的值。

一个 update expression 指定 UpdateItem 将修改项目的属性—例如,设置标量值或从列表或地图中删除元素。

下面是更新表达式的语法摘要。

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

更新表达式包含一个或多个子句。每个子句以 SETREMOVEADDDELETE 关键字开头。您可在更新表达式中按任意顺序包含其中任意子句。但是,每个操作关键字只能出现一次。

每个子句中存在一个或多个操作,用逗号分隔。每个操作表示一个数据修改。

此部分中的示例基于预测表达中所示的 ProductCatalog 项目。

SET—Modifying or Adding Item Attributes

在更新表达式中使用 SET 操作可将一个或多个属性添加到项目。如果任意这些属性已存在,则将由新值覆盖。

您也可以使用 SET 如何从类型的属性中添加或减去 Number。执行多个 SET 操作,使用逗号分隔。

在以下语法摘要中:

  • The path element is the document path to the item.

  • An operand element can be either a document path to an item or a function.

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

以下 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"} }

Modifying Attributes

更新 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 按更新后的情况返回项目。

Adding Lists and Maps

添加新列表和新映射。

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!" } ] } } } }

Adding Elements to a List

将新元素添加到 RelatedItems 列表。(请记住,列表元素从 0 开始,因此 [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 操作中添加多个元素,则元素会按照元素编号的顺序排序。

Adding Nested Map Attributes

添加一些嵌套映射属性。

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" } ] } }

Incrementing and Decrementing Numeric Attributes

您可以对现有数值属性执行加减运算。为此,请使用 +(加号)和 -(减号)运算符。

降低项目的 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,请在更新表达式中使用 + 运算符。

Appending Elements to a List

您可将元素添加到列表的末尾。为此,请将 SETlist_append 函数结合使用。(功能名称区分大小写。)TheThethe list_append 功能特定于 SET 操作并且只能用于更新表达式。语法如下所示。

  • list_append (list1, list2)

该函数将选取两个列表作为输入,并将所有元素从 list2 附加到 list1

Adding Elements to a List,您创建了 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" } ] } }

最后,您将一个元素附加到 beginningRelatedItems。为此,请交换 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.

Preventing Overwrites of an Existing Attribute

如果您要避免覆盖现有属性,则可以将 SETif_not_exists 函数结合使用。(功能名称区分大小写。)TheThethe if_not_exists 功能特定于 SET 操作并且只能用于更新表达式。语法如下所示。

  • if_not_exists (path, value)

如果项目在指定 path 中不包含属性,则 if_not_exists 的计算结果为 value;否则,计算结果为 path

设置项目的 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—Deleting Attributes from an Item

在更新表达式中使用 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

Removing Elements from a List

您可使用 REMOVE 从列表中删除各个元素。

Appending Elements to a List中,您修改了列表属性 (RelatedItems),使它包含 5 个元素:

  • [0]Chisel

  • [1]Hammer

  • [2]Nails

  • [3]Screwdriver

  • [4]Hacksaw

以下 AWS Command Line Interface (AWS CLI) 示例从列表中删除 HammerNails

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—Updating Numbers and Sets

注意

一般而言,我们建议使用 SET 而不是 ADD

在更新表达式中使用 ADD 操作可将新属性及其值添加到项目。

如果属性已存在,则 ADD 的行为取决于属性的数据类型:

  • If the attribute is a number, and the value you are adding is also a number, the value is mathematically added to the existing attribute. (If the value is a negative number, it is subtracted from the existing attribute.)

  • If the attribute is a set, and the value you are adding is also a set, the value is appended to the existing set.

注意

ADD 操作仅支持数字和集合数据类型。

要执行多个 ADD 操作,请使用逗号分隔它们。

在以下语法摘要中:

  • The path element is the document path to an attribute. The attribute must be either a Number or a set data type.

  • The value element is a number that you want to add to the attribute (for Number data types), or a set to append to the attribute (for set types).

add-action ::= path value

Adding a Number

假设 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。

Adding Elements to a Set

假设 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—Removing Elements from a Set

重要

DELETE 操作仅支持 Set 数据类型。

在更新表达式中使用 DELETE 操作可从集合中删除一个或多个元素。要执行多个 DELETE 操作,请使用逗号分隔它们。

在以下语法摘要中:

  • The path element is the document path to an attribute. The attribute must be a set data type.

  • The subset is one or more elements that you want to delete from path. You must specify subset as a set type.

delete-action ::= path value

Adding Elements to a Set中,您创建 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