# 遗留 DynamoDB 条件参数 本文档概述了 DynamoDB 中的遗留条件参数，并建议改用新的表达式参数。其中详细介绍了诸如 AttributesToGet、AttributeUpdates、ConditionalOperator、Expected、KeyConditions、QueryFilter 和 ScanFilter 等参数，并提供了如何使用新的表达式参数作为替换参数的示例。 **重要** 建议您尽可能使用新的表达式参数，而不是这些遗留参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。 此外，DynamoDB 不允许在单次调用中混合遗留条件参数和新表达式参数。例如，用 `AttributesToGet` 和 `ConditionExpression` 调用 `Query` 操作将导致错误。 下表显示仍支持这些遗留参数的 DynamoDB API 操作，以及要改用的表达式参数。如果考虑更新应用程序以使其使用表达式参数，则此表将非常有用。 **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/LegacyConditionalParameters.html) 以下章节提供遗留条件参数的更多信息。 **Topics** + [AttributesToGet（遗留）](LegacyConditionalParameters.AttributesToGet.md) + [AttributeUpdates（遗留）](LegacyConditionalParameters.AttributeUpdates.md) + [ConditionalOperator（遗留）](LegacyConditionalParameters.ConditionalOperator.md) + [Expected（遗留）](LegacyConditionalParameters.Expected.md) + [KeyConditions（遗留）](LegacyConditionalParameters.KeyConditions.md) + [QueryFilter（遗留）](LegacyConditionalParameters.QueryFilter.md) + [ScanFilter（遗留）](LegacyConditionalParameters.ScanFilter.md) + [使用遗留参数编写条件](LegacyConditionalParameters.Conditions.md) # AttributesToGet（遗留） **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。有关取代此参数的新参数的具体信息，请参阅[改用 *ProjectionExpression*](#ProjectionExpression.instead)。 遗留条件参数 `AttributesToGet` 是从 DynamoDB 检索的一个或多个属性的数组。如果未提供属性名称，则返回所有属性。如果找不到任何请求的属性，则不会出现在结果中。 `AttributesToGet` 支持检索 List 或 Map 类型的属性；但无法检索 List 或 Map 中的单个元素。 请注意，`AttributesToGet` 对预调配吞吐量消耗没有影响。DynamoDB 将依据项目大小确定消耗的容量单位，而不是依据返回应用程序的数据量。 ## 改用 *ProjectionExpression* – 示例 假设要从 *Music* 表检索一个项目，但只希望返回部分属性。可以使用 `GetItem` 请求和 `AttributesToGet` 参数，如这个 AWS CLI 示例： ``` aws dynamodb get-item \ --table-name Music \ --attributes-to-get '["Artist", "Genre"]' \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' ``` 您可以改用 `ProjectionExpression`： ``` aws dynamodb get-item \ --table-name Music \ --projection-expression "Artist, Genre" \ --key '{ "Artist": {"S":"No One You Know"}, "SongTitle": {"S":"Call Me Today"} }' ``` # AttributeUpdates（遗留） **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。有关取代此参数的新参数的具体信息，请参阅[改用 *UpdateExpression*。](#UpdateExpression.instead)。 在 `UpdateItem` 操作中，遗留条件参数 `AttributeUpdates` 包含要修改的属性的名称、要对每个属性执行的操作，以及每个属性的新值。如果要更新的属性是该表上任何索引的索引键属性，则属性类型必须与 `AttributesDefinition` 表说明中定义的索引键类型匹配。可以使用 `UpdateItem` 更新任何非键属性。 属性值不能为空。字符串和二进制类型属性的长度必须大于零。集合类型属性不得为空。具有空值的请求将被拒绝，并显示 `ValidationException` 异常。 每个 `AttributeUpdates` 元素包含要修改的属性名称以及以下内容： + `Value` - 此属性的新值（如果适用）。 + `Action` - 指定如何执行更新的值。此操作仅对数据类型为 Number 或集合的现有属性有效；不要将 `ADD` 用于其他数据类型。 如果在表中找到具有指定主键的项目，则以下值执行以下操作： + `PUT` - 将指定的属性添加到项目。如果属性已存在，则将替换为新值。 + `DELETE` - 如果没有为 指定值，则删除属性及其值。`DELETE`指定值的数据类型必须匹配现有值的数据类型。 如果指定了一组值，则将从旧集中减去这些值。例如，如果属性值是集合 `[a,b,c]`，`DELETE` 操作指定 `[a,c]`，则最终属性值为`[b]`。指定空集是错误。 + `ADD` - 如果属性尚不存在，则将指定值添加到项目。如果属性已存在，则 `ADD` 的行为取决于属性的数据类型： + 如果现有属性是数字，并且 `Value` 也是数字，则将 `Value` 与现有属性数学相加。如果 `Value` 为负数，则从现有属性减去该值。 **注意** 如果使用 `ADD` 为更新前不存在的项目递增或递减数值，则 DynamoDB 使用 0 作为初始值。 同样，如果使用 `ADD` 为现有项目递增或递减更新前不存在的属性值，则 DynamoDB 使用 `0` 作为初始值。例如，假设要更新的项目没有名为 *itemcount* 的属性，仍决定将数字 `3` `ADD`到该属性。DynamoDB 将创建 *itemcount* 属性，将初始值设置为 `0`，最后加上 `3`。结果将是一个新的 *itemcount* 属性，值为 `3`。 + 如果现有数据类型为集合，并且 `Value` 也是集合，则将 `Value` 附加到现有集合。例如，如果属性值是集合 `[1,2]`，`ADD` 操作指定 `[3]`，则最终属性值为 `[1,2,3]`。如果为集合属性指定 `ADD` 操作，并且指定的属性类型与现有集类型不匹配，则出错。 两个集合必须具有相同的基元数据类型。例如，如果现有数据类型是一组字符串，`Value` 也必须是一组字符串。 如果在表中找不到具有指定键的项目，则以下值将执行以下操作： + `PUT` - 使 DynamoDB 创建具有指定主键的新项目，然后添加属性。 + `DELETE` - 不进行任何操作，因为无法从不存在的项目删除属性。操作成功，但 DynamoDB 不创建新项目。 + `ADD` - 使 DynamoDB 创建具有提供的主键和属性值数字（或数字集合）的项目。唯一允许的数据类型是 Number 和 Number Set。 如果提供属于索引键的任何属性，则这些属性的数据类型必须与表属性定义中的架构数据类型匹配。 ## 改用 *UpdateExpression* – 示例 假设要修改 *Music* 表中的项目。可以使用 `UpdateItem` 请求和 `AttributeUpdates` 参数，如这个 AWS CLI 示例： ``` aws dynamodb update-item \ --table-name Music \ --key '{ "SongTitle": {"S":"Call Me Today"}, "Artist": {"S":"No One You Know"} }' \ --attribute-updates '{ "Genre": { "Action": "PUT", "Value": {"S":"Rock"} } }' ``` 您可以改用 `UpdateExpression`： ``` aws dynamodb update-item \ --table-name Music \ --key '{ "SongTitle": {"S":"Call Me Today"}, "Artist": {"S":"No One You Know"} }' \ --update-expression 'SET Genre = :g' \ --expression-attribute-values '{ ":g": {"S":"Rock"} }' ``` # ConditionalOperator（遗留） **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。 遗留条件参数 `ConditionalOperator` 是一个逻辑运算符，用来应用于 `Expected`、`QueryFilter` 或 `ScanFilter` 映射中的条件： + AND - 如果所有条件的计算结果都为 true，则整个映射的计算结果为 true。 + OR - 如果至少有一个条件的计算结果为 true，则整个映射的计算结果为 true。 如果忽略 `ConditionalOperator`，则默认为 `AND`。 仅当整个映射的计算结果为 true 时，操作才成功。 **注意** 此参数不支持 List 或 Map 类型的属性。 # Expected（遗留） **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。有关取代此参数的新参数的具体信息，请参阅[改用 *ConditionExpression*。](#Expected.instead)。 遗留条件参数 `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\$1CONTAINS 支持列表：如果计算“`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"} }' ``` # KeyConditions（遗留） **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。有关取代此参数的新参数的具体信息，请参阅[改用 *KeyConditionExpression*。](#KeyConditionExpression.instead)。 遗留条件参数 `KeyConditions` 包含 `Query` 操作的选择标准。对于表的查询，只能对表主键属性设置条件。必须提供分区键名称和值作为 `EQ` 条件。可以选择提供排序键作为另一个条件。 **注意** 如果不提供排序键条件，则将检索与分区键匹配的所有项目。如果存在 `FilterExpression` 或 `QueryFilter`，将在检索项目后应用。 对于索引查询，只能对索引键属性设置条件。必须提供索引键名称和值作为 `EQ` 条件。可以选择提供索引排序键作为另一个条件。 每个 `KeyConditions` 元素包含要比较的属性名称以及以下内容： + `AttributeValueList` - 对提供的属性计算的一个或多个值。列表中的值取决于使用的 `ComparisonOperator`。 对于 Number 类型，值比较为数字。 大于、等于或小于的字符串值比较基于 UTF-8 二进制编码的 Unicode。例如，`a` 大于 `A`，`a` 大于 `B`。 对于 Binary，DynamoDB 比较二进制值时将二进制数据的每个字节视为无符号。 + `ComparisonOperator` - 用于计算属性的比较运算符。例如：等于、大于、小于等。 对于 `KeyConditions`，支持下列比较运算符： `EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN` 下面介绍每个比较运算符。 + `EQ`：等于。 `AttributeValueList` 只能包含一个 String、Number 或 Binary（不是集合类型）的 `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"]}`。 + `BEGINS_WITH`：检查前缀。 `AttributeValueList` 只能包含一个 String 或 Binary（不是 Number 或集合类型）的 `AttributeValue`。比较的目标属性必须是 String 或 Binary 类型（不是 Number 或集合类型）。 + `BETWEEN`：大于或等于第一个值，小于或等于第二个值。 `AttributeValueList` 必须包含两个相同类型的 `AttributeValue` 元素，可以是 String、Number 或 Binary（不是集合类型）。如果目标值大于等于第一个元素，小于等于第二个元素，则目标属性匹配。如果项目包含的 `AttributeValue` 元素类型与请求提供的类型不同，则值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。 ## 改用 *KeyConditionExpression*– 示例 假设要用相同分区键从 *Music* 表检索多个项目。可以使用 `Query` 请求和 `KeyConditions` 参数，如这个 AWS CLI 示例： ``` aws dynamodb query \ --table-name Music \ --key-conditions '{ "Artist":{ "ComparisonOperator":"EQ", "AttributeValueList": [ {"S": "No One You Know"} ] }, "SongTitle":{ "ComparisonOperator":"BETWEEN", "AttributeValueList": [ {"S": "A"}, {"S": "M"} ] } }' ``` 您可以改用 `KeyConditionExpression`： ``` aws dynamodb query \ --table-name Music \ --key-condition-expression 'Artist = :a AND SongTitle BETWEEN :t1 AND :t2' \ --expression-attribute-values '{ ":a": {"S": "No One You Know"}, ":t1": {"S": "A"}, ":t2": {"S": "M"} }' ``` # QueryFilter（遗留） **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。有关取代此参数的新参数的具体信息，请参阅[改用 *FilterExpression*。](#FilterExpression.instead)。 在 `Query` 操作中，遗留条件参数 `QueryFilter` 是读取项目后计算查询结果的条件，仅返回所需值。 此参数不支持 List 或 Map 类型的属性。 **注意** 读取项目后应用 `QueryFilter`；筛选过程不消耗任何额外的读取容量单位。 如果在 `QueryFilter` 映射中提供多个条件，则默认所有条件的计算结果都必须为 true。换句话说，即使用 `AND` 操作符组合这些条件。（可以使用 [ConditionalOperator（遗留）](LegacyConditionalParameters.ConditionalOperator.md) 参数设置为 OR 条件。如果这样做，则必须至少有一个条件的计算结果为 true，而不是所有条件都必须。） 请注意，`QueryFilter` 不允许键属性。不能在分区键或排序键上定义筛选条件。 每个 `QueryFilter` 元素包含要比较的属性名称以及以下内容： + `AttributeValueList` - 对提供的属性计算的一个或多个值。列表中的值数量取决于 `ComparisonOperator` 中指定的运算符。 对于 Number 类型，值比较为数字。 大于、等于或小于的字符串值比较基于 UTF-8 二进制编码。例如，`a` 大于 `A`，`a` 大于 `B`。 对于 Binary 类型，DynamoDB 比较二进制值时将二进制数据的每个字节视为无符号。 有关在 JSON 中指定数据类型的信息，请参见 [DynamoDB 低级 API](Programming.LowLevelAPI.md)。 + `ComparisonOperator` - 用于计算属性的比较运算符。例如：等于、大于、小于等。 支持下列比较运算符： `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` ## 改用 *FilterExpression*– 示例 假设要查询 *Music* 表，并对匹配项目应用条件。可以使用 `Query` 请求和 `QueryFilter` 参数，如这个 AWS CLI 示例： ``` aws dynamodb query \ --table-name Music \ --key-conditions '{ "Artist": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S": "No One You Know"} ] } }' \ --query-filter '{ "Price": { "ComparisonOperator": "GT", "AttributeValueList": [ {"N": "1.00"} ] } }' ``` 您可以改用 `FilterExpression`： ``` aws dynamodb query \ --table-name Music \ --key-condition-expression 'Artist = :a' \ --filter-expression 'Price > :p' \ --expression-attribute-values '{ ":p": {"N":"1.00"}, ":a": {"S":"No One You Know"} }' ``` # ScanFilter（遗留） **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。有关取代此参数的新参数的具体信息，请参阅[改用 *FilterExpression*。](#FilterExpression2.instead)。 在 `Scan` 操作中，遗留条件参数 `ScanFilter` 是计算扫描结果的条件，仅返回所需值。 **注意** 此参数不支持 List 或 Map 类型的属性。 如果在 `ScanFilter` 映射中指定多个条件，则默认所有条件的计算结果都必须为 true。换句话说，条件 AND 在一起。（可以使用 [ConditionalOperator（遗留）](LegacyConditionalParameters.ConditionalOperator.md) 参数设置为 OR 条件。如果这样做，则必须至少有一个条件的计算结果为 true，而不是所有条件都必须。） 每个 `ScanFilter` 元素包含要比较的属性名称以及以下内容： + `AttributeValueList` - 对提供的属性计算的一个或多个值。列表中的值数量取决于 `ComparisonOperator` 中指定的运算符。 对于 Number 类型，值比较为数字。 大于、等于或小于的字符串值比较基于 UTF-8 二进制编码。例如，`a` 大于 `A`，`a` 大于 `B`。 对于 Binary，DynamoDB 比较二进制值时将二进制数据的每个字节视为无符号。 有关在 JSON 中指定数据类型的信息，请参阅 [DynamoDB 低级 API](Programming.LowLevelAPI.md)。 + `ComparisonOperator` - 用于计算属性的比较运算符。例如：等于、大于、小于等。 支持下列比较运算符： `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` ## 改用 *FilterExpression*– 示例 假设要扫描 *Music* 表并对匹配项目应用条件。可以使用 `Scan` 请求和 `ScanFilter` 参数，如这个 AWS CLI 示例： ``` aws dynamodb scan \ --table-name Music \ --scan-filter '{ "Genre":{ "AttributeValueList":[ {"S":"Rock"} ], "ComparisonOperator": "EQ" } }' ``` 您可以改用 `FilterExpression`： ``` aws dynamodb scan \ --table-name Music \ --filter-expression 'Genre = :g' \ --expression-attribute-values '{ ":g": {"S":"Rock"} }' ``` # 使用遗留参数编写条件 **注意** 我们建议您尽可能使用新的表达式参数，而不是这些旧式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。 下面的章节介绍如何用遗留参数编写使用条件，例如 `Expected`、`QueryFilter` 和 `ScanFilter`。 **注意** 新应用程序应使用表达式参数。有关更多信息，请参阅 [在 DynamoDB 中使用表达式](Expressions.md)。 ## 简单条件 使用属性值，您可以编写与表属性进行比较的条件。条件的计算结果始终为 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（遗留）](LegacyConditionalParameters.ConditionalOperator.md) 来实现。 默认情况下，如果指定多个条件，必须*所有*条件的计算结果都为 true，整个表达式的计算结果才为 true。换句话说，进行隐式 *AND* 操作。 **示例** 如果产品是至少有 600 页的书，则下面表达式的计算结果为 true。这两个条件的计算结果必须都为 true，因为隐式 *AND* 在一起。 ``` ... "ProductCategory": { ComparisonOperator: "EQ", AttributeValueList: [ {"S":"Book"} ] }, "PageCount": { ComparisonOperator: "GE", AttributeValueList: [ {"N":600"} ] } ... ``` 可以用 [ConditionalOperator（遗留）](LegacyConditionalParameters.ConditionalOperator.md) 说明将进行 *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`，因为这些选项可以构造更多条件。 **Example** `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} ] } }' ``` **Example** `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` 一起使用。如果这样做，条件写入将失败。