条件表达式

要操作 Amazon DynamoDB 表中的数据，请使用 PutItem、UpdateItem 和 DeleteItem 操作。(您还可使用 BatchWriteItem 在单个调用中执行多个 PutItem 或 DeleteItem 操作。)

对于这些数据处理操作，您可指定条件表达式 来确定应修改的项目。如果条件表达式的计算结果为 true，则操作成功；否则操作失败。

PutItemUpdateItem、和DeleteItem操作具有一个ReturnValues参数，可用于返回修改属性值之前或之后显示的属性值。有关更多信息，请参阅ReturnValues。

以下是使用条件表达式的一些 AWS Command Line Interface (AWS CLI) 示例。这些示例基于使用表达式时指定项目属性中介绍的 ProductCatalog 表。此表的分区键是 Id；没有排序键。以下 PutItem 操作创建示例所引用的 ProductCatalog 项目例子。


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

--item 的参数存储在文件 item.json 中。(为简单起见，仅使用了几个项目属性。)


{
    "Id": {"N": "456" },
    "ProductCategory": {"S": "Sporting Goods" },
    "Price": {"N": "650" }
}

主题

带条件放置
带条件删除
带条件更新
条件表达式示例
比较运算符和函数引用

带条件放置

PutItem 操作覆盖具有相同主键的项目（如果存在）。如果要避免这种情况，请使用条件表达式。这样，只有当相关的项目还没有相同的主键时，才能继续写入。

以下示例使用 attribute_not_exists() 在尝试写入操作之前检查表中是否存在主键。

注意

如果主键同时包含分区键（pk）和排序键（sk），则参数将在尝试写入操作之前检查 attribute_not_exists(pk) 和 attribute_not_exists(sk) 的计算结果是 true 还是 false。


aws dynamodb put-item \
    --table-name ProductCatalog \
    --item file://item.json \
    --condition-expression "attribute_not_exists(Id)"

如果条件表达式的计算结果为 false，则 DynamoDB 将返回以下错误消息：有条件请求失败。

注意

有关 attribute_not_exists 和其他函数的更多信息，请参阅比较运算符和函数引用。

带条件删除

要执行有条件删除，请将 DeleteItem 操作与条件表达式一起使用。要继续执行操作，条件表达式的求值结果必须为 true；否则操作将失败。

考虑来自条件表达式的项目。


{
    "Id": {
        "N": "456"
    },
    "Price": {
        "N": "650"
    },
    "ProductCategory": {
        "S": "Sporting Goods"
    }
}

假设您要删除该项目，但只能在以下条件下删除：

ProductCategory 为“Sporting Goods”或“Gardening Supplies”。
Price 介于 500 和 600 之间。

以下示例尝试删除该项目。


aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"456"}}' \
    --condition-expression "(ProductCategory IN (:cat1, :cat2)) and (Price between :lo and :hi)" \
    --expression-attribute-values file://values.json

--expression-attribute-values 的参数存储在文件 values.json 中。


{
    ":cat1": {"S": "Sporting Goods"},
    ":cat2": {"S": "Gardening Supplies"},
    ":lo": {"N": "500"},
    ":hi": {"N": "600"}
}

注意

在条件表达式中，:（冒号字符）表示表达式属性值-实际值的占位符。有关更多信息，请参阅表达式属性值。

有关 IN、AND 和其他关键字的更多信息，请参阅比较运算符和函数引用。

在本示例中，ProductCategory 比较的计算结果为 true，但 Price 比较的计算结果为 false。这导致条件表达式的计算结果为 false，并且 DeleteItem 操作失败。

带条件更新

要执行有条件更新，请将 UpdateItem 操作与条件表达式一起使用。要继续执行操作，条件表达式的求值结果必须为 true；否则操作将失败。

注意

UpdateItem 还支持更新表达式，您在其中指定要对项目进行的修改。有关更多信息，请参阅更新表达式。

假定您从条件表达式中所示的项目开始。


{
    "Id": { "N": "456"},
    "Price": {"N": "650"},
    "ProductCategory": {"S": "Sporting Goods"}
}

以下示例执行 UpdateItem 操作。它试图将产品的 Price 减少 75，但是如果当前 Price 小于或等于 500，条件表达式会阻止更新。


aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --update-expression "SET Price = Price - :discount" \
    --condition-expression "Price > :limit" \
    --expression-attribute-values file://values.json

--expression-attribute-values 的参数存储在文件 values.json 中。


{
    ":discount": { "N": "75"},
    ":limit": {"N": "500"}
}

如果起始 Price 为 650，则 UpdateItem 操作会将 Price 降至 575。如果您再次运行 UpdateItem 操作，Price 将降至 500。如果您第三次运行该操作，则条件表达式的计算结果为 false，并且更新失败。

注意

在条件表达式中，:（冒号字符）表示表达式属性值-实际值的占位符。有关更多信息，请参阅表达式属性值。

有关“>”和其他运算符的更多信息，请参阅比较运算符和函数引用。

条件表达式示例

有关以下示例中使用的函数的更多信息，请参阅比较运算符和函数引用。若要详细了解如何在表达式中指定不同的属性类型，请参阅使用表达式时指定项目属性。

检查项目中的属性

您可以检查任何属性是否存在。如果条件表达式的计算结果为 true，则操作成功；否则操作失败。

以下示例使用了 attribute_not_exists，以便仅当产品没有 Price 属性时才删除产品。


aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "attribute_not_exists(Price)"

DynamoDB 还提供了一个 attribute_exists 函数。以下示例仅当收到不好的评价时删除产品。


aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "attribute_exists(ProductReviews.OneStar)"

检查属性类型

您可以使用 attribute_type 函数检查属性值的数据类型。如果条件表达式的计算结果为 true，则操作成功；否则操作失败。

以下示例使用 attribute_type 删除具有类型为“字符串集”的 Color 属性的产品。


aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "attribute_type(Color, :v_sub)" \
    --expression-attribute-values file://expression-attribute-values.json

的参数存储--expression-attribute-values在 expression-attribute-values .json 文件中。


{
    ":v_sub":{"S":"SS"}
}

检查字符串的起始值

您可以使用 begins_with 函数检查字符串属性值是否以特定子字符串开头。如果条件表达式的计算结果为 true，则操作成功；否则操作失败。

以下示例使用 begins_with 删除 Pictures 映射的 FrontView 元素以特定值开头的产品。


aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "begins_with(Pictures.FrontView, :v_sub)" \
    --expression-attribute-values file://expression-attribute-values.json

的参数存储--expression-attribute-values在 expression-attribute-values .json 文件中。


{
    ":v_sub":{"S":"http://"}
}

检查集中的元素

您可以使用 contains 函数检查集中的元素或在字符串内查找子字符串。如果条件表达式的计算结果为 true，则操作成功；否则操作失败。

以下示例使用 contains 删除 Color 字符串集中包含具有特定值的元素的产品。


aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "contains(Color, :v_sub)" \
    --expression-attribute-values file://expression-attribute-values.json

的参数存储--expression-attribute-values在 expression-attribute-values .json 文件中。


{
    ":v_sub":{"S":"Red"}
}

检查属性值的大小

您可以使用 size 函数检查属性值的大小。如果条件表达式的计算结果为 true，则操作成功；否则操作失败。

以下示例使用 size 删除 VideoClip 二进制属性的大小超过 64000 字节的产品。


aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{"Id": {"N": "456"}}' \
    --condition-expression "size(VideoClip) > :v_sub" \
    --expression-attribute-values file://expression-attribute-values.json

的参数存储--expression-attribute-values在 expression-attribute-values .json 文件中。


{
    ":v_sub":{"N":"64000"}
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

表达式属性值

比较运算符和函数引用