本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Query
This section refers to API version 2011-12-05,
which is deprecated and should not be used for new
applications.
有关当前低级别 API 的文档,请参阅 Amazon DynamoDB API Reference。
Description
操作按主键获取一个或多个项目及其属性的值(Query
仅适用于哈希和范围主键表)。Query
您必须提供特定的 HashKeyValue
,并且可以使用主键的 RangeKeyValue
上的比较运算符缩小查询范围。使用 ScanIndexForward
参数按范围键的正向或反向顺序获取结果。
未返回结果的查询将根据读取类型消耗最小读取容量单位。
如果满足查询参数的项目总数超过 1MB 限制,则查询会停止,并且结果会返回给具有 LastEvaluatedKey
的用户,以在后续操作中继续执行查询。与扫描操作不同,查询操作从不返回空结果集和。LastEvaluatedKey
仅在结果超过 1MB 或您已使用 LastEvaluatedKey
参数时提供 Limit
。
可以使用 ConsistentRead
参数为一致性读取设置结果。
Requests
Syntax
// 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 处理不超过限制的项目数,则会停止查询并返回直至该点的匹配值,并且 类型: 数字 |
否 |
ConsistentRead
|
如果设置为 类型: Boolean |
否 |
Count
|
如果设置为 不要在提供 类型: Boolean |
否 |
HashKeyValue
|
复合主键的哈希组件的属性值。 类型: 字符串、数字或二进制 |
是 |
RangeKeyCondition
|
要用于查询的属性值和比较运算符的容器。查询请求不需要 类型: 映射 |
否 |
RangeKeyCondition :
AttributeValueList |
要为查询参数计算的属性值。包含一个属性值,除非指定了 类型: 到 |
否 |
RangeKeyCondition :
ComparisonOperator |
评估提供的属性的标准,例如等于、大于等。以下是查询操作的有效比较运算符。 大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如, 对于二进制,DynamoDB 在比较二进制值时将二进制数据的每个字节视为无符号,例如,在评估查询表达式时。 类型: 字符串或二进制 |
否 |
对于 |
||
对于 |
||
对于 |
||
对于 |
||
对于 |
||
对于 |
||
对于 |
||
ScanIndexForward |
指定索引的升序或降序遍历。DynamoDB 返回的结果反映范围键确定的请求顺序:如果数据类型为“数字”,则结果按数字顺序返回;否则,遍历基于 ASCII 字符代码值。 类型: Boolean 默认值为 |
否 |
ExclusiveStartKey |
从其继续之前查询的项目的主键。如果查询操作在完成查询之前中断,则早期的查询可能会将该值作为 类型: |
否 |
Responses
Syntax
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 |
停止查询操作的项目的主键,包括以前的结果集。使用此值启动新操作,但不包括新请求中的此值。
当整个查询结果集完成后, 类型: |
ConsumedCapacityUnits |
操作占用的读取容量单位数。此值显示应用于预置吞吐量的数量。有关更多信息,请参阅 管理 DynamoDB 预置容量表的设置。 类型: 数字 |
特殊错误
错误 | 描述 |
---|---|
ResourceNotFoundException
|
找不到指定的表。 |
Examples
有关使用 AWS 开发工具包的示例,请参阅在 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 }