使用遗留参数编写条件
注意
我们建议您尽可能使用新的表达式参数,而不是这些旧式参数。有关更多信息,请参阅 在 DynamoDB 中使用表达式。
下面的章节介绍如何用遗留参数编写使用条件,例如 Expected
、QueryFilter
和 ScanFilter
。
注意
新应用程序应使用表达式参数。有关更多信息,请参阅 在 DynamoDB 中使用表达式。
简单条件
使用属性值,您可以编写与表属性进行比较的条件。条件的计算结果始终为 true 或 false,包括:
-
ComparisonOperator
― 大于、小于、等于等。 -
AttributeValueList
(可选)— 要比较的属性值。这取决于使用的ComparisonOperator
,AttributeValueList
可能包含一个、两个或多个值;或者可能根本不存在。
以下章节介绍各种比较运算符,以及如何在条件中使用的示例。
无属性值的比较运算符
-
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
。对于大多数运算符,此值必须是标量;但 EQ
和 NE
运算符也支持集合。
示例
在下面的条件下,以下表达式的计算结果为 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 继续支持 Value
和 Exists
选项;但仅允许测试等于条件,或者属性是否存在。建议使用 ComparisonOperator
和 AttributeValueList
,因为这些选项可以构造更多条件。
例
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
映射的条件,不要将遗留 Value
和 Exists
选项与 ComparisonOperator
和 AttributeValueList
一起使用。如果这样做,条件写入将失败。