Struct TransactGetCommand

Namespace

DynaSharp

Assembly

DynaSharp.dll

A TransactGetItems under construction: up to 100 gets, of any tables and types, that see one snapshot. Chain them and end with SendAsync(CancellationToken) in one expression. Each get hands out a slot, which reads its item from the result.

public readonly ref struct TransactGetCommand : IRetryable<TransactGetCommand>

Implements

IRetryable<TransactGetCommand>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

Every get is strongly consistent, and the items are read as of one point in time, which a batch does not give. That costs twice the capacity of a strongly consistent read, and DynamoDB cancels the transaction with a TransactionCanceledException when it runs into a write in progress, so a read that must not fail is better off as a batch. DynamoDB limits a transaction to 4 MB of items and rejects one that holds a key twice.

Telemetry has one span for the request. See GetCommand<T> for what a command is and what it cannot do.

Methods

Get(Table<Item>, AttributeValue, AttributeValue, out TransactSlot<Item>)

Adds a get on a table without a schema, by the values of the key. A table of an entity takes a generated key instead.

public TransactGetCommand Get(Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey, out TransactSlot<Item> slot)

Parameters

table Table<Item>

The table.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

sortKey AttributeValue

The sort key as it is stored, which a table with a sort key needs.

slot TransactSlot<Item>

What reads the item from the result.

Returns

TransactGetCommand

The command, which replaces this one.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A key is empty, or the table has no sort key.

InvalidOperationException

The transaction holds 100 gets already.

Get(Table<Item>, AttributeValue, out TransactSlot<Item>)

Adds a get on a table without a schema and without a sort key, by the value of the partition key. DynamoDB rejects a key without its sort key on a table that has one.

public TransactGetCommand Get(Table<Item> table, AttributeValue partitionKey, out TransactSlot<Item> slot)

Parameters

table Table<Item>

The table.

partitionKey AttributeValue

The partition key as it is stored. Strings and binary values must not be empty.

slot TransactSlot<Item>

What reads the item from the result.

Returns

TransactGetCommand

The command, which replaces this one.

Exceptions

ArgumentNullException

table is null.

ArgumentException

The key is empty.

InvalidOperationException

The transaction holds 100 gets already.

Get<T, TKey>(Table<T>, TKey, out TransactSlot<T>)

Adds a get by a generated key.

public TransactGetCommand Get<T, TKey>(Table<T> table, TKey key, out TransactSlot<T> slot) where T : IDynamoDbDocument<T> where TKey : IKey<T>

Parameters

table Table<T>

The table.

key TKey

The key.

slot TransactSlot<T>

What reads the item from the result.

Returns

TransactGetCommand

The command, which replaces this one.

Type Parameters

T

How the item is read.

TKey

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

Exceptions

ArgumentNullException

table or key is null.

InvalidOperationException

The transaction holds 100 gets already.

MaxAttempts(int)

Sets the number of attempts of this call including the first, in place of MaxAttempts. A retry after a lost response repeats a write that may have been applied, so 1 makes an ADD count at most once, and a lost response then reports a failure after the write was applied.

public TransactGetCommand MaxAttempts(int attempts)

Parameters

attempts int

The number of attempts.

Returns

TransactGetCommand

The command, which replaces this one.

Exceptions

ArgumentOutOfRangeException

attempts is below 1.

ReturnCapacity(ReturnConsumedCapacity)

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

public TransactGetCommand ReturnCapacity(ReturnConsumedCapacity detail = ReturnConsumedCapacity.Total)

Parameters

detail ReturnConsumedCapacity

How much detail to return.

Returns

TransactGetCommand

The command, which replaces this one.

SendAsync(CancellationToken)

Sends the transaction. A key without an item is no error: its slot reads as not found. DynamoDB rejects a transaction without gets.

public ValueTask<TransactGetResult> SendAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels the call.

Returns

ValueTask<TransactGetResult>

The result. Await it once.

Exceptions

InvalidOperationException

The command was already sent, extended or rendered.

ObjectDisposedException

The client is disposed.

TransactionCanceledException

DynamoDB cancelled the transaction, for example for a conflict with a write in progress. It may pass on a retry of your own.

ValidationException

DynamoDB rejects the request, for example because it holds a key twice.

ResourceNotFoundException

A table does not exist.

DynamoDbException

DynamoDB returns any other error; a throttling or server error only after the last attempt.

ToRequestJson()

Renders the body 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.