AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.
Use the KeyConditionExpression parameter to provide a specific value for the partition key. The Query operation will return all of the items from the table or index with that partition key value. You can optionally narrow the scope of the Query operation by specifying a sort key value and a comparison operator in KeyConditionExpression. You can use the ScanIndexForward parameter to get results in forward or reverse order, by sort key.
Queries that do not return results consume the minimum number of read capacity units for that type of read operation.
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 the LastEvaluatedKey element to continue the query in a subsequent operation. Unlike a Scan operation, a Query operation never returns both an empty result set and a LastEvaluatedKey value. LastEvaluatedKey is only provided if the results exceed 1 MB, or if you have used the Limit parameter.
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 the ConsistentRead
parameter 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.
Namespace: Amazon.DynamoDBv2
Assembly: AWSSDK.dll
Version: (assembly version)
public abstract QueryResponse Query( QueryRequest request )
Container for the necessary parameters to execute the Query service method.
| Exception | Condition |
|---|---|
| InternalServerErrorException | An error occurred on the server side. |
| ProvisionedThroughputExceededException | Your request rate is too high. The AWS SDKs for DynamoDB automatically retry requests that receive this exception. Your request is eventually successful, unless your retry queue is too large to finish. Reduce the frequency of requests and use exponential backoff. For more information, go to Error Retries and Exponential Backoff in the Amazon DynamoDB Developer Guide. |
| ResourceNotFoundException | The operation tried to access a nonexistent table or index. The resource might not be specified correctly, or its status might not be ACTIVE. |
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
var result = client.Query(request);
// 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 && startKey.Count > 0);
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
var result = client.Query(request);
// 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 && startKey.Count > 0);
.NET Framework:
Supported in: 4.5, 4.0, 3.5