Amazon DynamoDB
开发人员指南 (API Version 2012-08-10)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

更新表达式

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

更新表达式 指定 UpdateItem 将如何修改项目的属性 - 例如,设置标量值或者删除列表或映射中的元素。

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

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

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

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

本节中的示例基于投影表达式中所示的 ProductCatalog 项目。

SET - 修改或添加项目属性

在更新表达式中使用 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 开始,因此 [0] 表示列表中的第一个元素,[1] 表示第二个元素,依此类推。)

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 会将新元素附加到列表的末尾。

如果在单个 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,请在更新表达式中使用 + 运算符。

将元素附加到列表

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

  • list_append (list1, list2)

该函数将选取两个列表作为输入,并会将 list2 附加到 list1

将元素添加到列表中,我们创建了 RelatedItems 列表并使用以下两个元素填充它:HammerNails。现在我们要将另外两个元素附加到 RelatedItems 的末尾:

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开头。为此,我们将交换 list_append 元素的顺序。(请记住,list_append 将选取两个列表作为输入,并会将第二个列表附加到第一个列表。)

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_exists 的计算结果为 value;否则,计算结果为 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 - 从项目中删除属性

在更新表达式中使用 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 - 更新数字和集合

注意

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

在更新表达式中使用 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 设置为包含两个元素的字符串集:

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 操作仅支持集合数据类型。

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

在以下语法摘要中:

  • path 元素是属性的文档路径。该属性必须是集数据类型。

  • 子网 是您要从 path 中删除的一个或多个元素。一个或多个元素。您必须指定 subset 作为集合类型。

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