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

使用传统参数编写条件

以下部分介绍如何使用编写与传统参数 (如 ExpectedQueryFilterScanFilter) 结合使用的条件。

注意

新应用程序应改为使用表达式参数。有关更多信息,请参阅 在 DynamoDB 中使用表达式

简单条件

利用属性值,可制定表属性对比条件。条件的计算结果始终为 true 或 false,条件包括:

  • ComparisonOperator - 大于、小于、等于等。

  • AttributeValueList (可选) - 比较时所依据的属性值。根据所使用的 ComparisonOperatorAttributeValueList 可能包含一个、两个或更多值;或者它可能根本不存在。

以下几部分介绍各种比较运算符,以及说明如何在条件中使用它们的示例。

无属性值的比较运算符

  • NOT_NULL - 如果属性存在,则为 true。

  • NULL - 如果属性不存在,则为 true。

使用这些运算符检查属性是否存在。由于没有用来对比的值,因此不指定 AttributeValueList

示例

如果存在 Dimensions 属性,则以下表达式的结果为 true。

Copy
... "Dimensions": { ComparisonOperator: "NOT_NULL" } ...

具有一个属性值的比较运算符

  • EQ - 如果属性等于某个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字、二进制、字符串集、数字集或二进制集的值。如果项目包含的值的类型不同于请求中指定的类型,则值不匹配。例如,字符串 "3" 不等于数字 3。并且,数字 3 不等于数字集 [3, 2, 1]

  • NE - 如果属性不等于某个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字、二进制、字符串集、数字集或二进制集的值。如果项目包含的值的类型不同于请求中指定的类型,则值不匹配。

  • LE - 如果属性小于或等于某个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的值。如果项目包含的 AttributeValue 的类型不同于请求中指定的类型,则值不匹配。

  • LT - 如果属性小于某个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的值。如果项目包含的值的类型不同于请求中指定的类型,则值不匹配。

  • GE - 如果属性大于或等于某个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的值。如果项目包含的值的类型不同于请求中指定的类型,则值不匹配。

  • GT - 如果属性大于某个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的值。如果项目包含的值的类型不同于请求中指定的类型,则值不匹配。

  • CONTAINS - 如果集中存在某个值,或者一个值包含另一个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的值。如果比较的目标属性是字符串,则此运算符查找匹配的子字符串。如果比较的目标属性是二进制,则此运算符在目标中查找与输入匹配的子序列。如果比较的目标属性是集,则当运算符找到与集中的任何成员精确匹配的项时,计算结果为 true。

  • NOT_CONTAINS - 如果集中 存在某个值,或者一个值不包含另一个值,则为 true。

    AttributeValueList 只能包含一个类型为字符串、数字或二进制 (非集) 的值。如果比较的目标属性是字符串,则此运算符检查某个子字符串的匹配项是否不存在。如果比较的目标属性是二进制,则此运算符检查目标中是否不存在与输入匹配的子序列。如果比较的目标属性是集,则当运算符找到与集中任何成员精确匹配的项时,计算结果为 true。

  • BEGINS_WITH - 如果属性的前几个字符与提供的值匹配,则为 true。不要使用此运算符比较数字。

    AttributeValueList 只能包含一个类型为字符串或二进制 (非数字或集) 的值。比较的目标属性必须是字符串或二进制 (非数字或集合)。

使用这些运算符比较赋值属性。必须指定包含一个值的 AttributeValueList。对于大部分运算符,此值必须是标量;但是,EQNE 运算符还支持集。

示例

以下表达式的结果为 true,如果:

  • 产品的价格大于 100。

    Copy
    ... "Price": { ComparisonOperator: "GT", AttributeValueList: [ {"N":100"} ] } ...
  • 产品类别开头为“Bo”。

    Copy
    ... "ProductCategory": { ComparisonOperator: "BEGINS_WITH", AttributeValueList: [ {"S":"Bo"} ] } ...
  • 产品有红色、绿色或黑色:

    Copy
    ... "Color": { ComparisonOperator: "EQ", AttributeValueList: [ [ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ] ] } ...

    注意

    在比较集数据类型时,这些元素的顺序无关紧要。DynamoDB 将仅返回具有相同数值集的项目,无论您在请求中指定它们的顺序如何。

具有两个属性值的比较运算符

  • BETWEEN - 如果值在下限与上限之间,包括终端节点,则为 true。

    AttributeValueList 必须包含两个相同类型 (字符串、数字或二进制 (非集) ) 的元素。如果目标值大于或等于第一个元素并且小于或等于第二个元素,则目标属性匹配。如果项目包含的值的类型不同于请求中指定的类型,则值不匹配。

使用此运算符可确定属性值是否在范围内。AttributeValueList 必须包含两个相同类型 (字符串、数字或二进制) 的标量元素。

示例

如果产品的价格在 100 到 200 之间,则以下表达式的结果为 true。

Copy
... "Price": { ComparisonOperator: "BETWEEN", AttributeValueList: [ {"N":"100"}, {"N":"200"} ] } ...

具有 N 属性值的比较运算符

  • IN- 如果值等于枚举列表中的任何值,则为 true。该列表中仅支持标量值,而不是集。目标属性必须属于同一类型,并且具有完全相同的值才能匹配。

    AttributeValueList 可包含一个或多个类型为字符串、数字或二进制 (非集) 的元素。这些属性与项目的现有非集类型属性进行比较。如果项目属性中存在输入集的任何 元素,则表达式的结果为 true。

    AttributeValueList 可包含一个或多个类型为字符串、数字或二进制 (非集) 的值。比较的目标属性必须属于同一类型,并且具有完全相同的值才能匹配。字符串从不与字符串集匹配。

使用此运算符可确定提供的值是否在枚举列表中。可在 AttributeValueList 中指定任何数量的标量值,但它们必须都为相同数据类型。

示例

如果 Id 的值为 201、203 或 205,则以下表达式的结果为 true。

Copy
... "Id": { ComparisonOperator: "IN", AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ] } ...

使用多个条件

DynamoDB 允许您组合多个条件,构成复杂表达式。为此,您需要至少提供两个表达式,ConditionalOperator 可选择性提供。

默认情况下,当指定多个条件时,所有条件的计算结果都为 true 才能使整个表达式的结果为 true。换句话说,是执行隐式 AND 运算。

示例

如果产品是至少有 600 页的图书,则以下表达式的结果为 true。这两个条件的计算结果都必须为 true,因为它们是通过隐式 AND 运算组合在一起的。

Copy
... "ProductCategory": { ComparisonOperator: "EQ", AttributeValueList: [ {"S":"Book"} ] }, "PageCount": { ComparisonOperator: "GE", AttributeValueList: [ {"N":600"} ] } ...

您可以使用 ConditionalOperator 明确指出将进行 AND 运算。下例的行为方式与上例相同。

Copy
... "ConditionalOperator" : "AND", "ProductCategory": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"N":"Book"} ] }, "PageCount": { "ComparisonOperator": "GE", "AttributeValueList": [ {"N":600"} ] } ...

您也可以将 ConditionalOperator 设置为 OR,这意味着这些条件中至少有一个 的计算结果必须为 true。

示例

如果产品是山地车,如果产品是特定品牌名称,或者如果价格大于 100,则以下表达式的结果为 true。

Copy
... ConditionalOperator : "OR", "BicycleType": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S":"Mountain" ] }, "Brand": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S":"Brand-Company A" ] }, "Price": { "ComparisonOperator": "GT", "AttributeValueList": [ {"N":"100"} ] } ...

注意

在复杂表达式中,这些条件是按照第一个到最后一个条件的顺序加以处理的。

不能在一个表达式中同时使用 AND 和 OR。

其他条件运算符

在 DynamoDB 的先前版本中,对于条件写入,Expected 参数的行为方式不同。Expected 映射中的每个项目均代表要检查的 DynamoDB 的属性名称,以及以下内容:

  • Value - 进行属性比较的值。

  • Exists - 在尝试操作前确定值是否存在。

DynamoDB 中继续支持 ValueExists 选项;但它们只用于测试相等条件,或者属性是否存在。我们建议您使用 AttributeValueListComparisonOperator,因为通过这些选项可构建更宽泛的条件范围。

DeleteItem 可检查某一图书是否不再出版,并且仅在此条件为 true 时将其删除。下面是使用旧式条件的 AWS CLI 示例:

Copy
aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{ "Id": {"N":"600"} }' \ --expected '{ "InPublication": { "Exists": true, "Value": {"BOOL":false} } }'

以下示例执行相同操作,但不使用传统条件:

Copy
aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{ "Id": {"N":"600"} }' \ --expected '{ "InPublication": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"BOOL":false} ] } }'

PutItem 操作可防止覆盖具有相同主键属性的现有项目。下面是使用传统条件的示例:

Copy
aws dynamodb put-item \ --table-name ProductCatalog \ --item '{ "Id": {"N":"500"}, "Title": {"S":"Book 500 Title"} }' \ --expected '{ "Id": { "Exists": false } }'

以下示例执行相同操作,但不使用传统条件:

Copy
aws dynamodb put-item \ --table-name ProductCatalog \ --item '{ "Id": {"N":"500"}, "Title": {"S":"Book 500 Title"} }' \ --expected '{ "Id": { "ComparisonOperator": "NULL" } }'

注意

对于 Expected 映射中的条件,不要将传统 ValueExists 选项与 AttributeValueListComparisonOperator 一同使用。否则条件写入将失败。