使用遗留参数编写条件 - Amazon DynamoDB

使用遗留参数编写条件

注意

我们建议您尽可能使用新的表达式参数,而不是这些旧式参数。有关更多信息,请参阅 在 DynamoDB 中使用表达式

下面的章节介绍如何用遗留参数编写使用条件,例如 ExpectedQueryFilterScanFilter

注意

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

简单条件

使用属性值,您可以编写与表属性进行比较的条件。条件的计算结果始终为 true 或 false,包括:

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

  • AttributeValueList(可选)— 要比较的属性值。这取决于使用的 ComparisonOperatorAttributeValueList 可能包含一个、两个或多个值;或者可能根本不存在。

以下章节介绍各种比较运算符,以及如何在条件中使用的示例。

无属性值的比较运算符

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

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

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

示例

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

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

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

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

    AttributeValueList 只能包含一个 String、Number、Binary、String Set、Number Set 或 Binary Set 类型的值。如果项目包含的值类型与请求中指定的类型不同,则该值不匹配。例如,字符串 "3" 不等于数字 3。此外,数字 3 不等于数字集合 [3, 2, 1]

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

    AttributeValueList 只能包含一个 String、Number、Binary、String Set、Number Set 或 Binary Set 类型的值。如果项目包含的值类型与请求中指定的类型不同,则该值不匹配。

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

    AttributeValueList 只能包含一个 String、Number 或 Binary(不是集合)类型的值。如果项目包含的 AttributeValue 类型与请求中指定的类型不同,则该值不匹配。

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

    AttributeValueList 只能包含一个 String、Number 或 Binary(不是集合)类型的值。如果项目包含的值与请求中指定的类型不同,则该值不匹配。

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

    AttributeValueList 只能包含一个 String、Number 或 Binary(不是集合)类型的值。如果项目包含的值类型与请求中指定的类型不同,则该值不匹配。

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

    AttributeValueList 只能包含一个 String、Number 或 Binary(不是集合)类型的值。如果项目包含的值类型与请求中指定的类型不同,则该值不匹配。

  • CONTAINS - 如果集合中存在值,或者值包含其他值,则为 true。

    AttributeValueList 只能包含一个 String、Number 或 Binary(不是集合)类型的值。如果比较的目标属性是字符串,则运算符将检查子字符串匹配。如果比较的目标属性为 Binary 类型,则运算符将查找匹配输入的目标子序列。如果比较的目标属性是集合,则如果运算符发现与集合中任何成员完全匹配,则计算结果为 true。

  • NOT_CONTAINS - 如果值存在于集合中,或者如果值不包含其他值,则为 true。

    AttributeValueList 只能包含一个 String、Number 或 Binary(不是集合)类型的值。如果比较的目标属性是 String,则运算符检查是否不存在子字符串匹配。如果比较的目标属性是 Binary,则运算符检查是否不存在匹配输入的目标子序列。如果比较的目标属性是集合,则如果运算符发现与集合中任何成员完全匹配,则计算结果为 true。

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

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

使用这些运算符将属性与值进行比较。您必须指定由单个值组成的 AttributeValueList。对于大多数运算符,此值必须是标量;但 EQNE 运算符也支持集合。

示例

在下面的条件下,以下表达式的计算结果为 true:

  • 产品的价格大于 100。

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

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

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

    比较集合数据类型时,元素的顺序并不重要。DynamoDB 将仅返回具有相同值集的项目,与请求中的指定顺序无关。

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

  • BETWEEN - 如果值介于下限和上限(包括端点)之间,则为 true。

    AttributeValueList 必须包含两个相同类型 String、Number 或 Binary(不是集合)元素。如果目标值大于等于第一个元素,小于等于第二个元素,则目标属性匹配。如果项目包含的值类型与请求中指定的类型不同,则该值不匹配。

使用此运算符确定属性值是否在范围内。AttributeValueList 必须包含两个相同类型的标量元素 - String、Number 或 Binary。

示例

如果产品的价格介于 100 和 200 之间,下面表达式的计算结果为 true。

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

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

  • IN - 如果值等于枚举列表中的任何值,则返回 true。只有列表支持标量值,集合不支持。目标属性必须具有相同类型和精确值才能匹配。

    AttributeValueList 可以包含一个或多个 String、Number 或 Binary(不是集合)类型的元素。这些属性与项目的现有非集合类型属性进行比较。如果项目属性存在输入集合的任何元素,则表达式的计算结果为 true。

    AttributeValueList 可以包含一个或多个 String、Number 或 Binary(不是集合)类型的元素。比较的目标属性必须具有相同类型和精确值才能匹配。字符串从不匹配字符串集。

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

示例

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

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

使用多个条件

DynamoDB 允许组合多个条件构成复杂表达式。可以通过提供至少两个表达式和一个可选 ConditionalOperator(遗留) 来实现。

默认情况下,如果指定多个条件,必须所有条件的计算结果都为 true,整个表达式的计算结果才为 true。换句话说,进行隐式 AND 操作。

示例

如果产品是至少有 600 页的书,则下面表达式的计算结果为 true。这两个条件的计算结果必须都为 true,因为隐式 AND 在一起。

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

可以用 ConditionalOperator(遗留) 说明将进行 AND 运算。下面示例的行为与前一个示例相同。

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

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

示例

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

... 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 选项;但仅允许测试等于条件,或者属性是否存在。建议使用 ComparisonOperatorAttributeValueList,因为这些选项可以构造更多条件。

DeleteItem 可以检查书是否不再出版,仅当此条件为 true 时删除。下面是一个使用遗留条件的 AWS CLI 示例:

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

下面的示例执行相同操作,但不使用遗留条件:

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

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

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

下面的示例执行相同操作,但不使用遗留条件:

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

对于 Expected 映射的条件,不要将遗留 ValueExists 选项与 ComparisonOperatorAttributeValueList 一起使用。如果这样做,条件写入将失败。