Query
Important
This section refers to API version 2011-12-05,
which is deprecated and should not be used for new
applications.
For documentation on the current low-level API, see the Amazon DynamoDB API Reference.
Description
A Query
operation gets the values of one or more items and their
attributes by primary key (Query
is only available for
hash-and-range primary key tables). You must provide a specific
HashKeyValue
, and can narrow the scope of the query using
comparison operators on the RangeKeyValue
of the primary key. Use
the ScanIndexForward
parameter to get results in forward or
reverse order by range key.
Queries that do not return results consume the minimum read capacity units according to the type of read.
Note
If the total number of items meeting the query parameters exceeds the 1MB limit, the
query stops and results are returned to the user with a
LastEvaluatedKey
to continue the query in a subsequent
operation. Unlike a Scan operation, a Query operation never returns an empty result
set and a LastEvaluatedKey
. The
LastEvaluatedKey
is only provided if the results exceed
1MB, or if you have used the Limit
parameter.
The result can be set for a consistent read using the
ConsistentRead
parameter.
Requests
Syntax
// This header is abbreviated. // For a sample of a complete header, see DynamoDB low-level 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"]}, }
Name | Description | Required |
---|---|---|
TableName
|
The name of the table containing the requested items. Type: String |
Yes |
AttributesToGet
|
Array of Attribute names. If attribute names are not specified then all attributes will be returned. If some attributes are not found, they will not appear in the result. Type: Array |
No |
Limit
|
The maximum number of items to return (not necessarily the number of matching items). If
DynamoDB processes the number of items up to the limit while
querying the table, it stops the query and returns the matching
values up to that point, and a
Type: Number |
No |
ConsistentRead
|
If set to Type: Boolean |
No |
Count
|
If set to Do not set Type: Boolean |
No |
HashKeyValue
|
Attribute value of the hash component of the composite primary key. Type: String, Number, or Binary |
Yes |
RangeKeyCondition
|
A container for the attribute values and comparison operators to use for the query. A query
request does not require a
Type: Map |
No |
RangeKeyCondition :
AttributeValueList |
The attribute values to evaluate for the query parameters. The
Type: A map of |
No |
RangeKeyCondition :
ComparisonOperator |
The criteria for evaluating the provided attributes, such as equals, greater-than, etc. The following are valid comparison operators for a Query operation. NoteString value comparisons for greater than, equals, or less than are based on ASCII
character code values. For example, For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values, for example when evaluating query expressions. Type: String or Binary |
No |
For |
||
For |
||
For |
||
For |
||
For |
||
For |
||
For |
||
ScanIndexForward |
Specifies ascending or descending traversal of the index. DynamoDB returns results reflecting the requested order determined by the range key: If the data type is Number, the results are returned in numeric order; otherwise, the traversal is based on ASCII character code values. Type: Boolean Default is |
No |
ExclusiveStartKey |
Primary key of the item from which to continue an earlier query. An earlier query might
provide this value as the Type: |
No |
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 }
Name | Description |
---|---|
Items
|
Item attributes meeting the query parameters. Type: Map of attribute names to and their data types and values. |
Count
|
Number of items in the response. For more information, see Counting the items in the results. Type: Number |
LastEvaluatedKey |
Primary key of the item where the query operation stopped, inclusive of the previous
result set. Use this value to start a new operation excluding this value
in the new request. The Type: |
ConsumedCapacityUnits |
The number of read capacity units consumed by the operation. This value shows the number applied toward your provisioned throughput. For more information see DynamoDB provisioned capacity mode. Type: Number |
Special errors
Error | Description |
---|---|
ResourceNotFoundException
|
The specified table was not found. |
Examples
For examples using the Amazon SDK, see Querying tables in DynamoDB.
Sample request
// This header is abbreviated. For a sample of a complete header, see DynamoDB low-level 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"} } }
Sample response
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 }
Sample request
// This header is abbreviated. For a sample of a complete header, see DynamoDB low-level 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}
Sample response
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 }