Expected(遗留)
注意
建议您尽可能使用新的表达式参数,而不是这些遗留参数。有关更多信息,请参阅 在 DynamoDB 中使用表达式。有关取代此参数的新参数的具体信息,请参阅改用 ConditionExpression。。
遗留条件参数 Expected
是 UpdateItem
操作的条件块。Expected
是属性/条件对的映射。映射的每个元素都包含一个属性名称、一个比较运算符以及一个或多个值。DynamoDB 使用比较运算符将属性与您提供的值进行比较。对于每个 Expected
元素,计算结果为 true 或 false。
如果在 Expected
映射中指定多个元素,则默认所有条件的计算结果都必须为 true。换句话说,即使用 AND
操作符组合这些条件。(可以使用 ConditionalOperator
参数设置为 OR 条件。如果这样做,则必须至少有一个条件的计算结果为 true,而不是所有条件都必须。)
如果 Expected
映射的计算结果为 true,则操作成功;否则操作失败。
Expected
包含以下内容:
-
AttributeValueList
- 对提供的属性计算的一个或多个值。列表中的值取决于使用的ComparisonOperator
。对于 Number 类型,值比较为数字。
大于、等于或小于的字符串值比较基于 UTF-8 二进制编码的 Unicode。例如,
a
大于A
,a
大于B
。对于 Binary 类型,DynamoDB 比较二进制值时将二进制数据的每个字节视为无符号。
-
ComparisonOperator
- 用于计算AttributeValueList
中的属性的比较运算符。执行比较时,DynamoDB 使用强一致性读取。支持下列比较运算符:
EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN
下面介绍每个比较运算符。
-
EQ
:等于。EQ
支持所有数据类型,包括列表和映射。AttributeValueList
只能包含一个 String、Number、Binary、String Set、Number Set 或 Binary Set 类型的AttributeValue
元素。如果项目包含的AttributeValue
元素类型与请求中指定的类型不同,则值不匹配。例如,{"S":"6"}
不等于{"N":"6"}
。{"N":"6"}
不等于{"NS":["6", "2", "1"]}
。 -
NE
:不等于。NE
支持所有数据类型,包括列表和映射。AttributeValueList
只能包含一个 String、Number、Binary、String Set、Number Set 或 Binary Set 类型的AttributeValue
。如果项目包含的AttributeValue
类型与请求中指定的类型不同,则值不匹配。例如,{"S":"6"}
不等于{"N":"6"}
。{"N":"6"}
不等于{"NS":["6", "2", "1"]}
。 -
LE
:小于或等于。AttributeValueList
只能包含一个 String、Number 或 Binary(不是集合类型)的AttributeValue
元素。如果项目包含的AttributeValue
元素类型与请求提供的类型不同,则值不匹配。例如,{"S":"6"}
不等于{"N":"6"}
。{"N":"6"}
不等于{"NS":["6", "2", "1"]}
。 -
LT
:小于。AttributeValueList
只能包含一个 String、Number 或 Binary(不是集合类型)的AttributeValue
。如果项目包含的AttributeValue
元素类型与请求提供的类型不同,则值不匹配。例如,{"S":"6"}
不等于{"N":"6"}
。{"N":"6"}
不等于{"NS":["6", "2", "1"]}
。 -
GE
:大于或等于。AttributeValueList
只能包含一个 String、Number 或 Binary(不是集合类型)的AttributeValue
元素。如果项目包含的AttributeValue
元素类型与请求提供的类型不同,则值不匹配。例如,{"S":"6"}
不等于{"N":"6"}
。{"N":"6"}
不等于{"NS":["6", "2", "1"]}
。 -
GT
:大于。AttributeValueList
只能包含一个 String、Number 或 Binary(不是集合类型)的AttributeValue
元素。如果项目包含的AttributeValue
元素类型与请求提供的类型不同,则值不匹配。例如,{"S":"6"}
不等于{"N":"6"}
。{"N":"6"}
不等于{"NS":["6", "2", "1"]}
。 -
NOT_NULL
:属性存在。NOT_NULL
支持所有数据类型,包括列表和映射。注意
此运算符测试属性是否存在,而不是其数据类型。如果属性“
a
”的数据类型为空,并且使用NOT_NULL
计算,则结果是一个布尔值true
。这是因为属性“a
”存在;其数据类型与NOT_NULL
比较运算符无关。 -
NULL
:属性不存在。NULL
支持所有数据类型,包括列表和映射。注意
此运算符测试属性不存在,而不是其数据类型。如果属性“
a
”的数据类型为空,并且使用NULL
计算,则结果是一个布尔值false
。这是因为属性“a
”存在;其数据类型与NULL
比较运算符无关。 -
CONTAINS
:检查子序列或集合中的值。AttributeValueList
只能包含一个 String、Number 或 Binary(不是集合类型)的AttributeValue
元素。如果比较的目标属性为 String 类型,则运算符将检查子字符串匹配。如果比较的目标属性为 Binary 类型,则运算符将查找匹配输入的目标子序列。如果比较的目标属性是集合(“SS
”、“NS
”或“BS
”),则如果运算符找到集合任何成员的精确匹配,计算结果为 true。CONTAINS 支持列表:如果计算“
a CONTAINS b
”,“a
”可以是列表;但“b
”不能是集合、映射或列表。 -
NOT_CONTAINS
:检查集合是否缺少子序列或值。AttributeValueList
只能包含一个 String、Number 或 Binary(不是集合类型)的AttributeValue
元素。如果比较的目标属性是 String,则运算符检查是否不存在子字符串匹配。如果比较的目标属性是 Binary,则运算符检查是否不存在匹配输入的目标子序列。如果比较的目标属性是集合(“SS
”、“NS
”或“BS
”),则如果运算符does not
找到集合任何成员的精确匹配,计算结果为 true。NOT_CONTAINS 支持列表:如果计算“
a NOT CONTAINS b
”,“a
”可以是列表;但“b
”不能是集合、映射或列表。 -
BEGINS_WITH
:检查前缀。AttributeValueList
只能包含一个 String 或 Binary(不是 Number 或集合类型)的AttributeValue
。比较的目标属性必须是 String 或 Binary 类型(不是 Number 或集合类型)。 -
IN
:检查两个集合中的匹配元素。AttributeValueList
可以包含一个或多个 String、Number 或 Binary(不是集合类型)的AttributeValue
元素。这些属性与项目的现有集合类型属性进行比较。如果项目属性存在输入集合的任何元素,则表达式的计算结果为 true。 -
BETWEEN
:大于或等于第一个值,小于或等于第二个值。AttributeValueList
必须包含两个相同类型的AttributeValue
元素,可以是 String、Number 或 Binary(不是集合类型)。如果目标值大于等于第一个元素,小于等于第二个元素,则目标属性匹配。如果项目包含的AttributeValue
元素类型与请求提供的类型不同,则值不匹配。例如,{"S":"6"}
不等于{"N":"6"}
。{"N":"6"}
不等于{"NS":["6", "2", "1"]}
-
可以使用以下参数代替 AttributeValueList
和 ComparisonOperator
:
-
Value
- DynamoDB 用于与属性进行比较的值。 -
Exists
- 要求 DynamoDB 在尝试条件运算前计算值的布尔值:-
如果
Exists
为true
,DynamoDB 将检查表中是否已经存在该属性值。如果找到,则条件的计算结果为 true;否则条件的计算结果为 false。 -
如果
Exists
为false
,则 DynamoDB 假定属性值not
存在于表中。如果实际上该值不存在,则假设有效,条件的计算结果为 true。如果找到该值,但假定该值不存在,条件的计算结果为 false。
请注意,
Exists
默认值为true
。 -
Value
和 Exists
参数与 AttributeValueList
和 ComparisonOperator
不相容。请注意,如果您同时使用这两组参数,DynamoDB 将返回 ValidationException
异常。
注意
此参数不支持 List 或 Map 类型的属性。
改用 ConditionExpression – 示例
假设仅当特定条件 true 时修改 Music 表的项目。可以使用 UpdateItem
请求和 Expected
参数,如这个 AWS CLI 示例:
aws dynamodb update-item \ --table-name Music \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' \ --attribute-updates '{ "Price": { "Action": "PUT", "Value": {"N":"1.98"} } }' \ --expected '{ "Price": { "ComparisonOperator": "LE", "AttributeValueList": [ {"N":"2.00"} ] } }'
您可以改用 ConditionExpression
:
aws dynamodb update-item \ --table-name Music \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' \ --update-expression 'SET Price = :p1' \ --condition-expression 'Price <= :p2' \ --expression-attribute-values '{ ":p1": {"N":"1.98"}, ":p2": {"N":"2.00"} }'