Table of Contents

Class ScanRequest

Namespace
DynaSharp.Requests
Assembly
DynaSharp.dll

Reads every item of a table or index, optionally filtered (DynamoDB Scan).

public sealed record ScanRequest : IEquatable<ScanRequest>
Inheritance
ScanRequest
Implements
Inherited Members

Remarks

A scan 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.

The read capacity consumed is that of everything read, not of what the filter returns. Scanning a large table is slow and expensive and can starve other requests of provisioned capacity; prefer a query whenever the key is known. To scan faster, split the table into segments with TotalSegments and read each with its own sequence of requests, in parallel.

Constructors

ScanRequest() 

public ScanRequest()

Properties

ConsistentRead

Gets a value indicating whether to use strongly consistent reads. The default eventually consistent read costs half the capacity but may miss recent writes. A consistent scan contains every write that completed before it began, but it is not a snapshot: writes during the scan may or may not be seen. 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. In a parallel scan it must be used with the same Segment that returned it. 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 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 filter expression. A placeholder that the expression does not use, 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". 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 scan instead of the table. A global secondary index is eventually consistent, so it can miss recent writes.

public string? IndexName { get; init; }

Property Value

string

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

Segment

Gets the zero-based segment this request reads, from 0 to TotalSegments minus 1. Set it together with TotalSegments. Each segment is a separate sequence of pages with its own LastEvaluatedKey. null sends nothing.

public int? Segment { get; init; }

Property Value

int?

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

TotalSegments

Gets the number of segments the scan is divided into, from 1 to 1,000,000; one per worker of a parallel scan. 1 is a sequential scan. Set it together with Segment; the same value must be used for all requests of a scan. null sends nothing.

public int? TotalSegments { get; init; }

Property Value

int?

Methods

Equals(ScanRequest?) 

public bool Equals(ScanRequest? other)

Parameters

other ScanRequest

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 ==(ScanRequest?, ScanRequest?) 

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

Parameters

left ScanRequest
right ScanRequest

Returns

bool

operator !=(ScanRequest?, ScanRequest?) 

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

Parameters

left ScanRequest
right ScanRequest

Returns

bool