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

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

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 处理不超过限制的项目数，则会停止查询并返回直至该点的匹配值，并且 LastEvaluatedKey 将在后续操作中应用以继续查询。此外，如果在 DynamoDB 达到此限制之前，结果集大小超过 1MB，则会停止查询并返回匹配的值，并在后续操作中应用 LastEvaluatedKey 以继续查询。

类型: 数字

 否
ConsistentRead

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

类型: Boolean

 否
Count

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

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

类型: Boolean

 否
HashKeyValue

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

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

 是
RangeKeyCondition

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

类型: 映射

 否
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 只能包含一个类型为 String、Number 或 Binary（非集合）的 AttributeValue。如果项目包含的 AttributeValue 类型与请求中指定的类型不同，则该值不匹配。例如，{"S":"6"} 不等于 {"N":"6"}。 此外，{"N":"6"} 不等于 {"NS":["6", "2", "1"]}。

 
 

LE：小于或等于。

对于 LE，AttributeValueList 只能包含一个类型为 String、Number 或 Binary（非集合）的 AttributeValue。如果项目包含的 AttributeValue 类型与请求中指定的类型不同，则该值不匹配。例如，{"S":"6"} 不等于 {"N":"6"}。 此外，{"N":"6"} 不与 {"NS":["6", "2", "1"]} 进行比较。

 
 

LT：小于。

对于 LT，AttributeValueList 只能包含一个类型为 String、Number 或 Binary（非集合）的 AttributeValue。如果项目包含的 AttributeValue 类型与请求中指定的类型不同，则该值不匹配。例如，{"S":"6"} 不等于 {"N":"6"}。 此外，{"N":"6"} 不与 {"NS":["6", "2", "1"]} 进行比较。

 
 

GE：大于或等于。

对于 GE，AttributeValueList 只能包含一个类型为 String、Number 或 Binary（非集合）的 AttributeValue。如果项目包含的 AttributeValue 类型与请求中指定的类型不同，则该值不匹配。例如，{"S":"6"} 不等于 {"N":"6"}。 此外，{"N":"6"} 不与 {"NS":["6", "2", "1"]} 进行比较。

 
 

GT：大于。

对于 GT，AttributeValueList 只能包含一个类型为 String、Number 或 Binary（非集合）的 AttributeValue。如果项目包含的 AttributeValue 类型与请求中指定的类型不同，则该值不匹配。例如，{"S":"6"} 不等于 {"N":"6"}。 此外，{"N":"6"} 不与 {"NS":["6", "2", "1"]} 进行比较。

 
 

BEGINS_WITH：检查前缀。

对于 BEGINS_WITH，AttributeValueList 只能包含一个类型为 String 或 Binary 的 AttributeValue（不是数字或集合）。比较的目标属性必须是字符串或二进制 （不是数字或集合）。

 
 

BETWEEN：大于或等于第一个值且小于或等于第二个值。

对于 BETWEEN，AttributeValueList 必须包含两个相同类型的 AttributeValue 元素：String、Number 或 Binary（非集合）。如果目标值大于或等于第一个元素且小于或等于第二个元素，则目标属性匹配。如果项目包含的 AttributeValue 类型与请求中指定的类型不同，则该值不匹配。例如，{"S":"6"} 不与 {"N":"6"} 进行比较。 此外，{"N":"6"} 不与 {"NS":["6", "2", "1"]} 进行比较。

 
ScanIndexForward

指定索引的升序或降序遍历。DynamoDB 返回的结果反映范围键确定的请求顺序：如果数据类型为“数字”，则结果按数字顺序返回；否则，遍历基于 ASCII 字符代码值。

类型: Boolean

默认值为 true（升序）。

否
ExclusiveStartKey

从其继续之前查询的项目的主键。如果查询操作在完成查询之前中断，则早期的查询可能会将该值作为 LastEvaluatedKey 提供；这可能是因为结果集大小或 Limit 参数导致的。可以在新的查询请求中传递回 LastEvaluatedKey 以从那时起继续操作。

类型: HashKeyElement，或对于复合主键为 HashKeyElement 和 RangeKeyElement。

否

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 停止查询操作的项目的主键，包括以前的结果集。使用此值启动新操作，但不包括新请求中的此值。

当整个查询结果集完成后，LastEvaluatedKey 为 null（即操作处理“上一页”）。

类型: HashKeyElement，或对于复合主键为 HashKeyElement 和 RangeKeyElement。

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
}