A Query operation directly accesses items from a table using the table primary key, or from an index using the index key. You must provide a specific hash key value. You can narrow the scope of the query by using comparison operators on the range key value, or on the index key. You can use the ScanIndexForward parameter to get results in forward or reverse order, by range key or by index key.
Queries that do not return results consume the minimum read capacity units according to the type of read.
If the total number of items meeting the query criteria exceeds the result set size limit of 1 MB, 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 1 MB, or if you have used Limit .
You can query a table, a local secondary index, or a global secondary index. For a query on a table or on a local secondary index, you can set ConsistentRead to true and obtain a strongly consistent result. Global secondary indexes support eventually consistent reads only, so do not specify ConsistentRead when querying a global secondary index.

C# |
public class QueryRequest : AmazonWebServiceRequest

All Members | Constructors | Methods | Properties | ||
Icon | Member | Description |
---|---|---|
![]() | QueryRequest()()()() | Initializes a new instance of the QueryRequest class |
![]() | AttributesToGet |
The names of one or more attributes to retrieve. If no attribute names are specified, then all attributes will be returned. If any of the
requested attributes are not found, they will not appear in the result. Note that AttributesToGet has no effect on provisioned
throughput consumption. DynamoDB determines capacity units consumed based on item size, not on the amount of data that is returned to an
application. You cannot use both AttributesToGet and Select together in a Query request, unless the value for
Select is SPECIFIC_ATTRIBUTES. (This usage is equivalent to specifying AttributesToGet without any value for
Select.) If you are querying a local secondary index and request only attributes that are projected into that index, the operation
will read only the index and not the table. If any of the requested attributes are not projected into the local secondary index, DynamoDB
will fetch each of these attributes from the parent table. This extra fetching incurs additional throughput cost and latency. If you are
querying a global secondary index, you can only request attributes that are projected into the index. Global secondary index queries cannot
fetch attributes from the parent table.
Constraints: |
![]() | ConditionalOperator |
A logical operator to apply to the conditions in the QueryFilter map:
Constraints: |
![]() | ConsistentRead |
If set to true, then the operation uses strongly consistent reads; otherwise, eventually consistent reads are used. Strongly
consistent reads are not supported on global secondary indexes. If you query a global secondary index with ConsistentRead set to
true, you will receive an error message.
|
![]() | Equals(Object) | (Inherited from Object.) |
![]() | ExclusiveStartKey |
The primary key of the first item that this operation will evaluate. Use the value that was returned for LastEvaluatedKey in the
previous operation. The data type for ExclusiveStartKey must be String, Number or Binary. No set data types are allowed.
|
![]() | GetHashCode()()()() | Serves as a hash function for a particular type. (Inherited from Object.) |
![]() | GetType()()()() | Gets the type of the current instance. (Inherited from Object.) |
![]() | IndexName |
The name of an index to query. This can be any local secondary index or global secondary index on the table.
Constraints: |
![]() | KeyConditions |
The selection criteria for the query. For a query on a table, you can only have conditions on the table primary key attributes. You must
specify the hash key attribute name and value as an EQ condition. You can optionally specify a second condition, referring to the
range key attribute. For a query on an index, you can only have conditions on the index key attributes. You must specify the index hash
attribute name and value as an EQ condition. You can optionally specify a second condition, referring to the index key range attribute. If
you specify more than one condition in the KeyConditions map, then by default all of the conditions must evaluate to true. In other
words, the conditions are ANDed together. (You can use the ConditionalOperator parameter to OR the conditions instead. If you do
this, then at least one of the conditions must evaluate to true, rather than all of them.) Each KeyConditions element consists of an
attribute name to compare, along with the following:
|
![]() | Limit |
The maximum number of items to evaluate (not necessarily the number of matching items). If DynamoDB processes the number of items up to the
limit while processing the results, it stops the operation and returns the matching values up to that point, and a LastEvaluatedKey
to apply in a subsequent operation, so that you can pick up where you left off. Also, if the processed data set size exceeds 1 MB before
DynamoDB reaches this limit, it stops the operation and returns the matching values up to the limit, and a LastEvaluatedKey to apply
in a subsequent operation to continue the operation. For more information see Query and Scan in the Amazon DynamoDB Developer
Guide.
Constraints: |
![]() | QueryFilter |
Evaluates the query results and returns only the desired values. If you specify more than one condition in the QueryFilter map, then
by default all of the conditions must evaluate to true. In other words, the conditions are ANDed together. (You can use the
ConditionalOperator parameter to OR the conditions instead. If you do this, then at least one of the conditions must evaluate to
true, rather than all of them.) Each QueryFilter element consists of an attribute name to compare, along with the following:
|
![]() | ReturnConsumedCapacity |
If set to TOTAL, the response includes ConsumedCapacity data for tables and indexes. If set to INDEXES, the response
includes ConsumedCapacity for indexes. If set to NONE (the default), ConsumedCapacity is not included in the response.
Constraints: |
![]() | ScanIndexForward |
Specifies ascending (true) or descending (false) 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. For String, the results are returned in order of
ASCII character code values. For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values. If
ScanIndexForward is not specified, the results are returned in ascending order.
|
![]() | Select |
The attributes to be returned in the result. You can retrieve all item attributes, specific item attributes, the count of matching items, or
in the case of an index, some or all of the attributes projected into the index.
Constraints: |
![]() | TableName |
The name of the table containing the requested items.
Constraints: |
![]() | ToString()()()() | Returns a string that represents the current object. (Inherited from Object.) |
![]() | WithAttributesToGet(array<String>[]()[][]) | Obsolete.
Adds elements to the AttributesToGet collection
|
![]() | WithAttributesToGet(IEnumerable<(Of <<'(String>)>>)) | Obsolete.
Adds elements to the AttributesToGet collection
|
![]() | WithConditionalOperator(String) | Obsolete.
Sets the ConditionalOperator property
|
![]() | WithConsistentRead(Boolean) | Obsolete.
Sets the ConsistentRead property
|
![]() | WithExclusiveStartKey(array<KeyValuePair<(Of <<'(String, AttributeValue>)>>)>[]()[][]) | Obsolete.
Adds the KeyValuePairs to the ExclusiveStartKey dictionary.
|
![]() | WithIndexName(String) | Obsolete.
Sets the IndexName property
|
![]() | WithKeyConditions(array<KeyValuePair<(Of <<'(String, Condition>)>>)>[]()[][]) | Obsolete.
Adds the KeyValuePairs to the KeyConditions dictionary.
|
![]() | WithLimit(Int32) | Obsolete.
Sets the Limit property
|
![]() | WithQueryFilter(array<KeyValuePair<(Of <<'(String, Condition>)>>)>[]()[][]) | Obsolete.
Adds the KeyValuePairs to the QueryFilter dictionary.
|
![]() | WithReturnConsumedCapacity(String) | Obsolete.
Sets the ReturnConsumedCapacity property
|
![]() | WithScanIndexForward(Boolean) | Obsolete.
Sets the ScanIndexForward property
|
![]() | WithSelect(String) | Obsolete.
Sets the Select property
|
![]() | WithTableName(String) | Obsolete.
Sets the TableName property
|

The following example shows how to query items in a table.
Note: the Query operation retrieves items that have the same
hash-key. This means that the Query operation is only supported on tables
with both a hash- and a range-key.
Note: the RangeKeyCondition for Query is limited to indexable comparisons.
These are EQ, LE, LT, GE, GT, BETWEEN, and BEGINS_WITH.
We will now retrieve all items where the hash-key is "Mark Twain" and
the range-key begins with the string "The Adventures".

// Create a client AmazonDynamoDBClient client = new AmazonDynamoDBClient(); // Define item hash-key to be string value "Mark Twain" AttributeValue hashKey = new AttributeValue { S = "Mark Twain" }; // Define query condition to search for range-keys that begin with the string "The Adventures" Condition condition = new Condition { ComparisonOperator = "BEGINS_WITH", AttributeValueList = new List<AttributeValue> { new AttributeValue { S = "The Adventures" } } }; // Create the key conditions from hashKey and condition Dictionary<string, Condition> keyConditions = new Dictionary<string, Condition> { // Hash key condition. ComparisonOperator must be "EQ". { "Author", new Condition { ComparisonOperator = "EQ", AttributeValueList = new List<AttributeValue> { hashKey } } }, // Range key condition { "Title", condition } }; // Define marker variable Dictionary<string, AttributeValue> startKey = null; do { // Create Query request QueryRequest request = new QueryRequest { TableName = "SampleTable", ExclusiveStartKey = startKey, KeyConditions = keyConditions }; // Issue request QueryResult result = client.Query(request).QueryResult; // View all returned items List<Dictionary<string, AttributeValue>> items = result.Items; foreach (Dictionary<string, AttributeValue> item in items) { Console.WriteLine("Item:"); foreach (var keyValuePair in item) { Console.WriteLine("{0} : S={1}, N={2}, SS=[{3}], NS=[{4}]", keyValuePair.Key, keyValuePair.Value.S, keyValuePair.Value.N, string.Join(", ", keyValuePair.Value.SS ?? new List<string>()), string.Join(", ", keyValuePair.Value.NS ?? new List<string>())); } } // Set marker variable startKey = result.LastEvaluatedKey; } while (startKey != null);
The following example shows how to query items in a local secondary index.
Like a standard Query, we must pass in a hash-key value. But since we are querying
against a specific index, we must remember to refer to the correct index attribute.
In the below example that means that we reference the attribute "Years", and since the
attribute is numerical we must pass in a numerical AttributeValue.

// Create a client AmazonDynamoDBClient client = new AmazonDynamoDBClient(); // Define item hash-key to be string value "Mark Twain" AttributeValue hashKey = new AttributeValue { S = "Mark Twain" }; // Define query condition to search for range-keys ("Year", in "YearsIndex") that are less than 1900 Condition condition = new Condition { ComparisonOperator = "LT", AttributeValueList = new List<AttributeValue> { new AttributeValue { N = "1900" } } }; // Create the key conditions from hashKey and condition Dictionary<string, Condition> keyConditions = new Dictionary<string, Condition> { // Hash key condition. ComparisonOperator must be "EQ". { "Author", new Condition { ComparisonOperator = "EQ", AttributeValueList = new List<AttributeValue> { hashKey } } }, // Range key condition { "Year", // Reference the correct range key when using indexes condition } }; // Define marker variable Dictionary<string, AttributeValue> startKey = null; do { // Create Query request QueryRequest request = new QueryRequest { TableName = "SampleTable", ExclusiveStartKey = startKey, KeyConditions = keyConditions, IndexName = "YearsIndex" // Specify the index to query against }; // Issue request QueryResult result = client.Query(request).QueryResult; // View all returned items List<Dictionary<string, AttributeValue>> items = result.Items; foreach (Dictionary<string, AttributeValue> item in items) { Console.WriteLine("Item:"); foreach (var keyValuePair in item) { Console.WriteLine("{0} : S={1}, N={2}, SS=[{3}], NS=[{4}]", keyValuePair.Key, keyValuePair.Value.S, keyValuePair.Value.N, string.Join(", ", keyValuePair.Value.SS ?? new List<string>()), string.Join(", ", keyValuePair.Value.NS ?? new List<string>())); } } // Set marker variable startKey = result.LastEvaluatedKey; } while (startKey != null);

Object | ||
![]() | AmazonWebServiceRequest | |
![]() | QueryRequest |
