查询 - Amazon DynamoDB
描述请求响应特殊错误示例相关操作

查询

重要

本节介绍已经弃用的 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 找不到指定表。

示例

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