Struct BatchGetCommand<T>

Namespace

DynaSharp

Assembly

DynaSharp.dll

A BatchGetItem under construction: many keys of one table, of any number. Chain the keys and options and end with SendAsync(CancellationToken) in one expression. Reads of another table go through a batch of that table, or through client.BatchGetItemAsync of DynaSharp.Requests.

public readonly ref struct BatchGetCommand<T> : IRetryable<BatchGetCommand<T>> where T : IDynamoDbDocument<T>

Type Parameters

T

How the items are read.

Implements

IRetryable<BatchGetCommand<T>>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

DynamoDB takes 100 keys in a request and returns 16 MB of items in a response. The command cuts the keys into requests of 100, which run one after the other, and asks again for the keys DynamoDB did not get to, so the result is complete. A batch is not one read: each key is read on its own, so the items are not a snapshot, and a read that must be one is a TransactGetCommand. Items come back in no order.

Keys that were left unprocessed are asked for again after a backoff with jitter on TimeProvider. The batch gives up after 8 requests in a row that get nothing done, or as many as MaxStalledRounds(int) says, with BatchGetIncompleteException<T>. A round that reads something, as with a response at its 16 MB, does not count against that. Any other failure after a request went through ends the batch the same way, with the failure as its InnerException, and so does a timeout, a lost connection or a server error of the first request. Any other failure of the first request surfaces as it is, and a cancellation stays an OperationCanceledException, which reports no progress.

DynamoDB rejects a request that holds one key twice with a ValidationException. The command leaves that to DynamoDB and does not look for duplicates: a key that occurs twice in one request fails it, and one that occurs in two requests is read twice.

Telemetry has one span per request, so a batch can make several, and they carry the table and the capacity of their own request. See GetCommand<T> for what a command is and what it cannot do.

Methods

Consistent()

Asks for strongly consistent reads, which see every write that succeeded before them and cost twice the capacity. Reads are eventually consistent otherwise.

public BatchGetCommand<T> Consistent()

Returns

BatchGetCommand<T>

The command, which replaces this one.

GetAll<TKey>(IEnumerable<TKey>)

Adds generated keys, any number of them. They are written here and now, so the sequence is enumerated once, before anything is sent.

public BatchGetCommand<T> GetAll<TKey>(IEnumerable<TKey> keys) where TKey : IKey<T>

Parameters

keys IEnumerable<TKey>

The keys.

Returns

BatchGetCommand<T>

The command, which replaces this one.

Type Parameters

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

keys or one of them is null.

Get<TKey>(TKey)

Adds a key built by the generator, such as Order.Keys.Of(customerId, number).

public BatchGetCommand<T> Get<TKey>(TKey key) where TKey : IKey<T>

Parameters

key TKey

The key.

Returns

BatchGetCommand<T>

The command, which replaces this one.

Type Parameters

TKey

The key. A key of another entity is a compile error.

Exceptions

ArgumentNullException

key is null.

MaxAttempts(int)

Sets the number of attempts of each request including the first, in place of MaxAttempts. It is about one request and says nothing about keys that come back unanswered, which MaxStalledRounds(int) bounds.

public BatchGetCommand<T> MaxAttempts(int attempts)

Parameters

attempts int

The number of attempts.

Returns

BatchGetCommand<T>

The command, which replaces this one.

Exceptions

ArgumentOutOfRangeException

attempts is below 1.

MaxStalledRounds(int)

Sets how many requests in a row may get nothing done before the batch gives up with BatchGetIncompleteException<T>, in place of 8. A request that reads something starts the count again, so this bounds a batch that is stuck and not a long one. With 1 the batch gives up at the first request that reads nothing, without a wait, which suits a caller that has a backoff of its own.

public BatchGetCommand<T> MaxStalledRounds(int rounds)

Parameters

rounds int

The number of requests.

Returns

BatchGetCommand<T>

The command, which replaces this one.

Exceptions

ArgumentOutOfRangeException

rounds is below 1.

Project(params ReadOnlySpan<Attr>)

Reads only some attributes, given as handles: Project(Order.Attrs.Status, Order.Attrs.Total). See Project(params ReadOnlySpan<string>).

public BatchGetCommand<T> Project(params ReadOnlySpan<Attr> attributes)

Parameters

attributes ReadOnlySpan<Attr>

The attributes. A second call adds to the first.

Returns

BatchGetCommand<T>

The command, which replaces this one.

Project(params ReadOnlySpan<string>)

Reads only some attributes. It saves bandwidth, not capacity: DynamoDB charges for the whole items. A read of an entity needs its discriminator and its keys, so they join the projection on their own, and it needs whatever else the entity requires, so a projection is mostly for Item.

public BatchGetCommand<T> Project(params ReadOnlySpan<string> paths)

Parameters

paths ReadOnlySpan<string>

The names or document paths. Reserved words need no care, and a second call adds to the first.

Returns

BatchGetCommand<T>

The command, which replaces this one.

Exceptions

ArgumentException

A path is not valid.

ReturnCapacity(ReturnConsumedCapacity)

Asks for the consumed capacity, which goes to ConsumedCapacity and the capacity metric.

public BatchGetCommand<T> ReturnCapacity(ReturnConsumedCapacity detail = ReturnConsumedCapacity.Total)

Parameters

detail ReturnConsumedCapacity

How much detail to return.

Returns

BatchGetCommand<T>

The command, which replaces this one.

SendAsync(CancellationToken)

Sends the batch, as one request per 100 keys. A batch without keys sends nothing and returns an empty result, and a key without an item is no error.

public ValueTask<BatchGetResult<T>> SendAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels the batch, also while it waits between rounds.

Returns

ValueTask<BatchGetResult<T>>

The result. Await it once.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered.

BatchGetIncompleteException<T>

DynamoDB left keys unanswered after every round, a table stayed throttled on the last attempt of a request, a request timed out, lost its connection or met a server error on its last attempt, or any other failure came after a request went through. The failure is then its InnerException.

ObjectDisposedException

The client is disposed.

ValidationException

DynamoDB rejects the first request, for example because it holds a key twice; the exception shows the projection.

ResourceNotFoundException

The table does not exist, as the first request finds.

DynamoDbMappingException

An item of the first response cannot be read as T.

DynamoDbException

DynamoDB returns any other error on the first request that repeating cannot fix.

OperationCanceledException

cancellationToken was cancelled. This does not report progress: what was read before is dropped.

ToRequestJson()

Renders the body of the first request this command would send, as DynamoDB JSON, without sending it. It ends the command, and is meant for tests and debugging. The text contains the keys.

public string ToRequestJson()

Returns

string

The request body.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered.