Query - Amazon DynamoDB
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Query

重要

本节介绍已经弃用的 API 版本 2011-12-05,不应用于新应用程序。

有关当前低级别 API 的文档,请参阅 Amazon DynamoDB API 参考

描述

Query 操作通过主键获取一个或多个项目的值及其属性(Query 仅对 hash-and-range 主键表可用)。您必须提供一个特定 HashKeyValue,并且可以对主键的 RangeKeyValue 使用比较运算符缩小查询范围。使用 ScanIndexForward 参数按 range 键获取正向或反向顺序结果。

不返回结果的查询会根据读取类型消耗最小读取容量单位。

注意

如果满足查询参数的项目总数超过 1MB 限制,则查询将停止,结果将返回给用户,并显示 LastEvaluatedKey,以在后续操作中继续查询。与扫描操作不同,查询操作永远不会返回空结果集 LastEvaluatedKey。仅当结果超过 1MB 或者使用 Limit 参数时提供 LastEvaluatedKey

可以使用 ConsistentRead 参数为一致性读取设置结果。

请求

语法

// This header is abbreviated. // For a sample of a complete header, see DynamoDB 低级 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Limit":2, "ConsistentRead":true, "HashKeyValue":{"S":"AttributeValue1":}, "RangeKeyCondition": {"AttributeValueList":[{"N":"AttributeValue2"}],"ComparisonOperator":"GT"} "ScanIndexForward":true, "ExclusiveStartKey":{ "HashKeyElement":{"S":"AttributeName1"}, "RangeKeyElement":{"N":"AttributeName2"} }, "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}, }
名称 描述 必填
TableName

包含请求项目的表的名称。

类型:字符串

AttributesToGet

属性名称的数组。如果未指定属性名称,则返回所有属性。如果找不到某些属性,则不会出现在结果中。

类型:数组

Limit

要返回的最大项目数(不一定是匹配项目数)。如果 DynamoDB 在查询表时处理的项目数达到限制,将停止查询并返回到此时的匹配值和 LastEvaluatedKey,在后续操作中应用以继续查询。此外,如果在 DynamoDB 达到此限制之前结果集大小超过 1MB,将停止查询并返回匹配值和 LastEvaluatedKey,在后续操作中应用以继续查询。

类型:数字

ConsistentRead

如果设置为 true,则发出一致性读取,否则将使用最终一致性。

类型:布尔值

Count

如果设置为 true,DynamoDB 将返回匹配查询参数的项目总数,而不是匹配项目及其属性的列表。可以对仅计数查询应用 Limit 参数。

提供 AttributesToGet 列表时不要将 Count 设置为 true;否则 DynamoDB 将返回验证错误。有关更多信息,请参阅对结果中的项目进行计数

类型:布尔值

HashKeyValue

复合主键的 hash 部分的属性值。

类型:字符串、数字或二进制

RangeKeyCondition

用于查询的属性值和比较运算符的容器。查询请求不需要 RangeKeyCondition。如果仅提供 HashKeyValue,DynamoDB 将返回具有指定 hash 键元素值的所有项目。

类型:映射

RangeKeyCondition:​ AttributeValueList

为查询参数计算的属性值。AttributeValueList 包含一个属性值,除非指定 BETWEEN 比较。对于 BETWEEN 比较,AttributeValueList 包含两个属性值。

类型:AttributeValueComparisonOperator 的映射。

RangeKeyCondition:​ ComparisonOperator

计算所提供属性的标准,例如等于、大于等于等。以下是查询操作的有效比较运算符。

注意

大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如,a 大于 Aaa 大于 B。有关代码值列表,请参见 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters

对于二进制,DynamoDB 在比较二进制值时将二进制数据的每个字节视为无符号值,例如计算查询表达式时。

类型:字符串或二进制

 

EQ:等于。

对于 EQAttributeValueList 只能包含一个字符串、数字或二进制类型的 AttributeValue(不是集合)。如果项目包含的 AttributeValue 类型与请求中指定的类型不同,则该值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
 

LE:小于或等于。

对于 LEAttributeValueList 只能包含一个字符串、数字或二进制类型的 AttributeValue(不是集合)。如果项目包含的 AttributeValue 类型与请求中指定的类型不同,则该值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
 

LT:小于。

对于 LTAttributeValueList 只能包含一个字符串、数字或二进制类型的 AttributeValue(不是集合)。如果项目包含的 AttributeValue 类型与请求中指定的类型不同,则该值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
 

GE:大于或等于。

对于 GEAttributeValueList 只能包含一个字符串、数字或二进制类型的 AttributeValue(不是集合)。如果项目包含的 AttributeValue 类型与请求中指定的类型不同,则该值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
 

GT:大于。

对于 GTAttributeValueList 只能包含一个字符串、数字或二进制类型的 AttributeValue(不是集合)。如果项目包含的 AttributeValue 类型与请求中指定的类型不同,则该值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
 

BEGINS_WITH:检查前缀。

对于 BEGINS_WITHAttributeValueList 只能包含一个字符串或二进制类型的 AttributeValue(不是数字或集合)。比较的目标属性必须是字符串或二进制(不是数字或集合)。

 
 

BETWEEN:大于或等于第一个值,小于或等于第二个值。

对于 BETWEENAttributeValueList 必须包含两个相同类型的 AttributeValue 元素,可以是字符串,数字或二进制(不是集合)。如果目标值大于等于第一个元素,小于等于第二个元素,则目标属性匹配。如果项目包含的 AttributeValue 类型与请求中指定的类型不同,则该值不匹配。例如,{"S":"6"} 不等于 {"N":"6"}{"N":"6"} 不等于 {"NS":["6", "2", "1"]}

 
ScanIndexForward

指定索引的升序或降序遍历。DynamoDB 返回的结果反映由 range 键确定的请求顺序:如果数据类型为数字,则按数字顺序返回结果;否则,遍历基于 ASCII 字符代码值。

类型:布尔值

默认值为 true(升序)。

ExclusiveStartKey

继续早期查询的项目的主键。如果早期查询操作在完成查询之前因为结果集大小或 Limit 参数中断,该查询可能会提供此值作为 LastEvaluatedKeyLastEvaluatedKey 可以在新的查询请求中传回,从此处开始继续操作。

类型:HashKeyElementHashKeyElementRangeKeyElement(对于复合主键)。

响应

语法

HTTP/1.1 200 x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 308 {"Count":2,"Items":[{ "AttributeName1":{"S":"AttributeValue1"}, "AttributeName2":{"N":"AttributeValue2"}, "AttributeName3":{"S":"AttributeValue3"} },{ "AttributeName1":{"S":"AttributeValue3"}, "AttributeName2":{"N":"AttributeValue4"}, "AttributeName3":{"S":"AttributeValue3"}, "AttributeName5":{"B":"dmFsdWU="} }], "LastEvaluatedKey":{"HashKeyElement":{"AttributeValue3":"S"}, "RangeKeyElement":{"AttributeValue4":"N"} }, "ConsumedCapacityUnits":1 }
名称 描述
Items

符合查询参数的项目属性。

类型:属性名称映射及其数据类型和值。

Count

响应中的项目数。有关更多信息,请参阅对结果中的项目进行计数

类型:数字

LastEvaluatedKey 查询操作停止的项目主键,包括以前的结果集。使用此值可以在新请求中开始不包含此值的新操作。

整个查询结果集完成后(即操作处理“最后一页”),LastEvaluatedKeynull

类型:HashKeyElementHashKeyElementRangeKeyElement(对于复合主键)。

ConsumedCapacityUnits

操作消耗的读取容量单位数。此值显示应用于预置吞吐量的数字。有关更多信息,请参阅 管理 DynamoDB 预调配容量表的吞吐量设置

类型:数字

特殊错误

错误 描述
ResourceNotFoundException 找不到指定表。

示例

有关使用 Amazon SDK 的示例,请参阅 DynamoDB 中的查询操作

示例请求

// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable", "Limit":2, "HashKeyValue":{"S":"John"}, "ScanIndexForward":false, "ExclusiveStartKey":{ "HashKeyElement":{"S":"John"}, "RangeKeyElement":{"S":"The Matrix"} } }

示例响应

HTTP/1.1 200 x-amzn-RequestId: 3647e778-71eb-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 308 {"Count":2,"Items":[{ "fans":{"SS":["Jody","Jake"]}, "name":{"S":"John"}, "rating":{"S":"***"}, "title":{"S":"The End"} },{ "fans":{"SS":["Jody","Jake"]}, "name":{"S":"John"}, "rating":{"S":"***"}, "title":{"S":"The Beatles"} }], "LastEvaluatedKey":{"HashKeyElement":{"S":"John"},"RangeKeyElement":{"S":"The Beatles"}}, "ConsumedCapacityUnits":1 }

示例请求

// This header is abbreviated. For a sample of a complete header, see DynamoDB 低级 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable", "Limit":2, "HashKeyValue":{"S":"Airplane"}, "RangeKeyCondition":{"AttributeValueList":[{"N":"1980"}],"ComparisonOperator":"EQ"}, "ScanIndexForward":false}

示例响应

HTTP/1.1 200 x-amzn-RequestId: 8b9ee1ad-774c-11e0-9172-d954e38f553a content-type: application/x-amz-json-1.0 content-length: 119 {"Count":1,"Items":[{ "fans":{"SS":["Dave","Aaron"]}, "name":{"S":"Airplane"}, "rating":{"S":"***"}, "year":{"N":"1980"} }], "ConsumedCapacityUnits":1 }