查询 - Amazon DynamoDB
说明请求响应特殊错误示例相关操作
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

查询

重要

本节引用 API 版本 2011-12-05，此版本已被弃用且不应用于新应用程序。

有关当前低级 API 的文档，请参阅 Amazon DynamoDB API Reference。

说明

Query 操作按主键获取一个或多个项目及其属性的值（Query 只可用于哈希和范围主键表）。您必须提供特定 HashKeyValue，并且您可以通过对主键的 RangeKeyValue 使用比较运算符来缩小查询范围。使用 ScanIndexForward 参数可以按范围键以正向或反向顺序获取结果。

不返回结果的查询会占用最小数量的读取容量单位（具体取决于读取类型）。

注意

如果符合查询参数的项目总数超过 1MB 的限制，则查询将停止，并且会向用户返回结果及 LastEvaluatedKey，以便在后续操作中继续查询。与 Scan 操作不同，Query 操作从不返回空结果集和 LastEvaluatedKey。仅当结果超出 1MB 或者您使用了 LastEvaluatedKey 参数时，才提供 Limit。

可以使用 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

复合主键的哈希组件的属性值。

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

 是
RangeKeyCondition

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

类型：映射

 否
RangeKeyCondition： AttributeValueList

要针对查询参数进行评估的属性值。除非指定了 AttributeValueList 比较，否则 BETWEEN 只包含一个属性值。对于 BETWEEN 比较，AttributeValueList 包含两个属性值。

类型：AttributeValue 到 ComparisonOperator 的映射。

否
RangeKeyCondition： ComparisonOperator

用于评估提供的属性的标准，如“等于”、“大于”等。以下是 Query 操作的有效比较运算符。

注意

大于、等于或小于的字符串值比较基于 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 返回反映所请求顺序（由范围键确定）的结果：如果数据类型是数字，则会按数字顺序返回结果；否则，遍历基于 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 找不到指定的表。

示例

有关使用 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
}