Class QueryRequest

Namespace

DynaSharp.Requests

Assembly

DynaSharp.dll

Reads the items of one partition, optionally narrowed by a sort key condition, from a table or an index (DynamoDB Query).

public sealed record QueryRequest : IEquatable<QueryRequest>

Inheritance

object

QueryRequest

Implements

IEquatable<QueryRequest>

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

A query reads at most 1 MB of data per call, and at most Limit items, before the FilterExpression is applied. When it stops early, the response carries a LastEvaluatedKey: pass it as ExclusiveStartKey of the next request to continue. A page can be empty and still have a LastEvaluatedKey, because the filter removed everything that was read; only a response without one is the last page.

Results are ordered by the sort key (numbers numerically, strings and binary by their UTF-8 or unsigned bytes), ascending unless ScanIndexForward is false.

Constructors

QueryRequest()

public QueryRequest()

Properties

ConsistentRead

Gets a value indicating whether to use a strongly consistent read. The default eventually consistent read costs half the capacity but may miss writes from the last second. Not supported on global secondary indexes: DynamoDB rejects it with a ValidationException.

public bool ConsistentRead { get; init; }

Property Value

bool

ExclusiveStartKey

Gets the key of the last item of the previous page: the LastEvaluatedKey of the previous response, unchanged. The query continues with the next item. For an index query it contains the key attributes of the table and of the index; no sets are allowed in it.

public IReadOnlyDictionary<string, AttributeValue>? ExclusiveStartKey { get; init; }

Property Value

IReadOnlyDictionary<string, AttributeValue>

ExpressionAttributeNames

Gets the substitutions for #name placeholders in the key condition, filter and projection expressions. A placeholder that no expression uses makes DynamoDB reject the request. Use it to alias attribute names that are DynamoDB reserved words, such as name, status, size, order or total, which DynamoDB rejects with a ValidationException when an expression uses them directly (the check is case-insensitive), and names with a dot or other special characters. See the list of reserved words.

public IReadOnlyDictionary<string, string>? ExpressionAttributeNames { get; init; }

Property Value

IReadOnlyDictionary<string, string>

ExpressionAttributeValues

Gets the substitutions for :value placeholders in the key condition and filter expressions. A placeholder that no expression uses, or that no value defines, makes DynamoDB reject the request.

public IReadOnlyDictionary<string, AttributeValue>? ExpressionAttributeValues { get; init; }

Property Value

IReadOnlyDictionary<string, AttributeValue>

FilterExpression

Gets a condition that DynamoDB applies to the items after reading them and before returning them, for example "#status = :active". It cannot use the key attributes. Filtering does not reduce the read capacity consumed or the 1 MB read limit, only the data that is returned; a selective filter produces small or empty pages. Attribute names that are DynamoDB reserved words, such as name, status, size, order or total, must be aliased with a #placeholder defined in ExpressionAttributeNames; written directly, DynamoDB rejects the request with a ValidationException. See the list of reserved words.

public string? FilterExpression { get; init; }

Property Value

string

IndexName

Gets the name of the local or global secondary index to query instead of the table. Items are then ordered by the sort key of the index. A global secondary index is eventually consistent, so it can miss recent writes.

public string? IndexName { get; init; }

Property Value

string

KeyConditionExpression

Gets the condition that selects the items: an equality test on the partition key, optionally combined with AND and one test on the sort key (=, <, <=, >, >=, BETWEEN or begins_with), for example "pk = :pk AND begins_with(sk, :prefix)". Use placeholders (#name, :value) for names that are reserved words and for all values. begins_with does not work on numbers. Attribute names that are DynamoDB reserved words, such as name, status, size, order or total, must be aliased with a #placeholder defined in ExpressionAttributeNames; written directly, DynamoDB rejects the request with a ValidationException. See the list of reserved words.

public required string KeyConditionExpression { get; init; }

Property Value

string

Remarks

DynamoDB's own service model leaves this optional because of a legacy parameter that this library does not offer; without it a query is always rejected, so it is required here.

Limit

Gets the maximum number of items to read (not the number of items returned, which the filter can reduce). DynamoDB requires at least 1 and rejects other values with a ValidationException; this library passes the value on. The 1 MB limit applies as well. null sends nothing: the limit is then only the 1 MB.

public int? Limit { get; init; }

Property Value

int?

ProjectionExpression

Gets the attributes to return, for example "#n, Address.City, Tags[0]". All attributes when null. It does not reduce the read capacity consumed, which is based on the size of the items read. Attribute names that are DynamoDB reserved words, such as name, status, size, order or total, must be aliased with a #placeholder defined in ExpressionAttributeNames; written directly, DynamoDB rejects the request with a ValidationException. See the list of reserved words.

public string? ProjectionExpression { get; init; }

Property Value

string

ReturnConsumedCapacity

Gets whether to report consumed capacity in ConsumedCapacity.

public ReturnConsumedCapacity ReturnConsumedCapacity { get; init; }

Property Value

ReturnConsumedCapacity

ScanIndexForward

Gets the direction of the traversal by sort key: true or null ascending (DynamoDB default), false descending. For example, false with a Limit of 1 reads the item with the highest sort key.

public bool? ScanIndexForward { get; init; }

Property Value

bool?

Select

Gets which attributes to return. Unspecified sends nothing; see SelectKind for what DynamoDB then does and which combinations with ProjectionExpression are valid.

public SelectKind Select { get; init; }

Property Value

SelectKind

TableName

Gets the table name (or table ARN). With IndexName, the table the index belongs to.

public required string TableName { get; init; }

Property Value

string

Methods

Equals(QueryRequest?)

public bool Equals(QueryRequest? other)

Parameters

other QueryRequest

Returns

bool

Equals(object?)

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

GetHashCode()

public override int GetHashCode()

Returns

int

ToString()

public override string ToString()

Returns

string

Operators

operator ==(QueryRequest?, QueryRequest?)

public static bool operator ==(QueryRequest? left, QueryRequest? right)

Parameters

left QueryRequest

right QueryRequest

Returns

bool

operator !=(QueryRequest?, QueryRequest?)

public static bool operator !=(QueryRequest? left, QueryRequest? right)

Parameters

left QueryRequest

right QueryRequest

Returns

bool