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` 包含两个属性值。类型：`AttributeValue` 到 `ComparisonOperator` 的映射。	否
`RangeKeyCondition`: `ComparisonOperator`	计算所提供属性的标准，例如等于、大于等于等。以下是查询操作的有效比较运算符。注意大于、等于或小于的字符串值比较基于 ASCII 字符代码值。例如，`a` 大于 `A`，`aa` 大于 `B`。有关代码值列表，请参见 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters。对于二进制，DynamoDB 在比较二进制值时将二进制数据的每个字节视为无符号值，例如计算查询表达式时。类型：字符串或二进制	否
	`EQ`：等于。对于 `EQ`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。
	`LE`：小于或等于。对于 `LE`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。
	`LT`：小于。对于 `LT`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。
	`GE`：大于或等于。对于 `GE`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。
	`GT`：大于。对于 `GT`，`AttributeValueList` 只能包含一个字符串、数字或二进制类型的 `AttributeValue`（不是集合）。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。
	`BEGINS_WITH`：检查前缀。对于 `BEGINS_WITH`，`AttributeValueList` 只能包含一个字符串或二进制类型的 `AttributeValue`（不是数字或集合）。比较的目标属性必须是字符串或二进制（不是数字或集合）。
	`BETWEEN`：大于或等于第一个值，小于或等于第二个值。对于 `BETWEEN`，`AttributeValueList` 必须包含两个相同类型的 `AttributeValue` 元素，可以是字符串，数字或二进制（不是集合）。如果目标值大于等于第一个元素，小于等于第二个元素，则目标属性匹配。如果项目包含的 `AttributeValue` 类型与请求中指定的类型不同，则该值不匹配。例如，`{"S":"6"}` 不等于 `{"N":"6"}`。`{"N":"6"}` 不等于 `{"NS":["6", "2", "1"]}`。
`ScanIndexForward`	指定索引的升序或降序遍历。DynamoDB 返回的结果反映由 range 键确定的请求顺序：如果数据类型为数字，则按数字顺序返回结果；否则，遍历基于 ASCII 字符代码值。类型：布尔值默认值为 `true`（升序）。	否
`ExclusiveStartKey`	继续早期查询的项目的主键。如果早期查询操作在完成查询之前因为结果集大小或 `Limit` 参数中断，该查询可能会提供此值作为 `LastEvaluatedKey`。`LastEvaluatedKey` 可以在新的查询请求中传回，从此处开始继续操作。类型：`HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`（对于复合主键）。	否

响应

语法


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`	查询操作停止的项目主键，包括以前的结果集。使用此值可以在新请求中开始不包含此值的新操作。整个查询结果集完成后（即操作处理“最后一页”），`LastEvaluatedKey` 为 `null`。类型：`HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`（对于复合主键）。
`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
}

Query

描述

请求

语法

响应

语法

特殊错误

示例

示例请求

示例响应

示例请求

示例响应

相关操作