AWS SDK for .NET Documentation
QueryRequest Class
AmazonAmazon.DynamoDBv2.ModelQueryRequest Did this page help you?   Yes   No    Tell us about it...
Container for the parameters to the Query operation.

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.

Declaration Syntax
C#
public class QueryRequest : AmazonWebServiceRequest
Members
All MembersConstructorsMethodsProperties



IconMemberDescription
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:

Length
1 -


ConditionalOperator
A logical operator to apply to the conditions in the QueryFilter map:
  • AND - If all of the conditions evaluate to true, then the entire map evaluates to true.
  • OR - If at least one of the conditions evaluate to true, then the entire map evaluates to true.
If you omit ConditionalOperator, then AND is used as the default. The operation will succeed only if the entire map evaluates to true.

Constraints:

Allowed Values
AND, OR


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)
Determines whether the specified Object is equal to the current 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:

Length
3 - 255
Pattern
[a-zA-Z0-9_.-]+


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:
  • AttributeValueList - One or more values to evaluate against the supplied attribute. The number of values in the list depends on the ComparisonOperator being used. For type Number, value comparisons are numeric. String value comparisons for greater than, equals, or less than are based on ASCII character code values. For example, a is greater than A, and aa is greater than B. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters. For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values, for example when evaluating query expressions. For information on specifying data types in JSON, see JSON Data Format in the Amazon DynamoDB Developer Guide.
  • ComparisonOperator - A comparator for evaluating attributes. For example, equals, greater than, less than, etc. For KeyConditions, the following comparison operators are supported: EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN For complete descriptions of comparison operators, see API_Condition.html.

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:

Range
1 -


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:
  • AttributeValueList - One or more values to evaluate against the supplied attribute. The number of values in the list depends on the ComparisonOperator being used. For type Number, value comparisons are numeric. String value comparisons for greater than, equals, or less than are based on ASCII character code values. For example, a is greater than A, and aa is greater than B. For a list of code values, see http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters. For Binary, DynamoDB treats each byte of the binary data as unsigned when it compares binary values, for example when evaluating query expressions. For information on specifying data types in JSON, see JSON Data Format in the Amazon DynamoDB Developer Guide.
  • ComparisonOperator - A comparator for evaluating attributes. For example, equals, greater than, less than, etc. The following comparison operators are available: EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN For complete descriptions of all comparison operators, see API_Condition.html.

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:

Allowed Values
INDEXES, TOTAL, NONE


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.
  • ALL_ATTRIBUTES: Returns all of the item attributes from the specified table or index. If you are querying a local secondary index, then for each matching item in the index DynamoDB will fetch the entire item from the parent table. If the index is configured to project all item attributes, then all of the data can be obtained from the local secondary index, and no fetching is required..
  • ALL_PROJECTED_ATTRIBUTES: Allowed only when querying an index. Retrieves all attributes which have been projected into the index. If the index is configured to project all attributes, this is equivalent to specifying ALL_ATTRIBUTES.
  • COUNT: Returns the number of matching items, rather than the matching items themselves.
  • SPECIFIC_ATTRIBUTES : Returns only the attributes listed in AttributesToGet. This is equivalent to specifying AttributesToGet without specifying 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.
If neither Select nor AttributesToGet are specified, DynamoDB defaults to ALL_ATTRIBUTES when accessing a table, and ALL_PROJECTED_ATTRIBUTES when accessing an index. You cannot use both Select and AttributesToGet together in a single request, unless the value for Select is SPECIFIC_ATTRIBUTES. (This usage is equivalent to specifying AttributesToGet without any value for Select.)

Constraints:

Allowed Values
ALL_ATTRIBUTES, ALL_PROJECTED_ATTRIBUTES, SPECIFIC_ATTRIBUTES, COUNT


TableName
The name of the table containing the requested items.

Constraints:

Length
3 - 255
Pattern
[a-zA-Z0-9_.-]+


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

Examples

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".

CopyQuery sample
// 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.

CopyC#
// 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);
Inheritance Hierarchy
See Also

Assembly: AWSSDK (Module: AWSSDK) Version: 1.5.60.0 (1.5.60.0)