Table of Contents

Class ItemTableExtensions

Namespace
DynaSharp
Assembly
DynaSharp.dll

The verbs of a table or index without a schema that take the values of a key as they are stored, and the attribute-by-attribute Put() with its With. These are extension methods so that a table of an entity does not offer them: a key given as its values would skip its key template, and a put by attribute would write an item without its discriminator.

public static class ItemTableExtensions
Inheritance
ItemTableExtensions
Inherited Members

Examples

var shop = client.Table("Shop", "pk", "sk");
Item? profile = await shop.Get("CUSTOMER#1", "PROFILE").ItemAsync(ct);
await foreach (var item in shop.Query("CUSTOMER#1", SortKeyCondition.BeginsWith("ORDER#")).ItemsAsync(ct))
{
    Console.WriteLine(item["sk"]);
}

Remarks

The values of a key go to Item. shop.Get("CUSTOMER#1", "PROFILE") sends the values as they are written. On a table of an entity, customers.Get("1") would miss the item the entity stores under CUSTOMER#1, so it does not compile there: such a table takes Customer.Keys.Of("1"), see DYNA230. A table without a schema has no template, so it takes the values, and Of<TOther>() turns it into a table of an entity.

Methods

Delete(BatchWriteCommand<Item>, AttributeValue, AttributeValue)

Adds a delete to a batch of a table without a schema, by the values of the key. Deleting what does not exist is no error.

public static BatchWriteCommand<Item> Delete(this BatchWriteCommand<Item> command, AttributeValue partitionKey, AttributeValue sortKey = default)

Parameters

command BatchWriteCommand<Item>

The command.

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.

Returns

BatchWriteCommand<Item>

The command, which replaces this one.

Remarks

As written. The values go out as they are. A table of an entity takes the key its generator built instead, customers.Get(Customer.Keys.Of("1")), which formats them as the entity stores them.

Exceptions

ArgumentException

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

Delete(Table<Item>, AttributeValue, AttributeValue)

Starts a DeleteItem of one item of a table without a schema by the values of its key. Deleting what does not exist is no error unless IfExists() asks for one.

public static DeleteCommand<Item> Delete(this Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey = default)

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.

Returns

DeleteCommand<Item>

The command.

Remarks

As written. The values go out as they are. A table of an entity takes the key its generator built instead, customers.Get(Customer.Keys.Of("1")), which formats them as the entity stores them.

Exceptions

ArgumentNullException

table is null.

ArgumentException

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

Get(BatchGetCommand<Item>, AttributeValue, AttributeValue)

Adds a key to a batch get of a table without a schema, by its values.

public static BatchGetCommand<Item> Get(this BatchGetCommand<Item> command, AttributeValue partitionKey, AttributeValue sortKey = default)

Parameters

command BatchGetCommand<Item>

The command.

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.

Returns

BatchGetCommand<Item>

The command, which replaces this one.

Remarks

As written. The values go out as they are. A table of an entity takes the key its generator built instead, customers.Get(Customer.Keys.Of("1")), which formats them as the entity stores them.

Exceptions

ArgumentException

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

Get(Table<Item>, AttributeValue, AttributeValue)

Starts a GetItem of one item of a table without a schema by the values of its key: shop.Get("CUSTOMER#1", "PROFILE"). A missing item is not an error, and the read is eventually consistent unless Consistent() says otherwise.

public static GetCommand<Item> Get(this Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey = default)

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.

Returns

GetCommand<Item>

The command.

Remarks

As written. The values go out as they are. A table of an entity takes the key its generator built instead, customers.Get(Customer.Keys.Of("1")), which formats them as the entity stores them.

Exceptions

ArgumentNullException

table is null.

ArgumentException

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

Put(Table<Item>)

Starts a put whose attributes follow one by one with With, straight to the request, without an Item: shop.Put().With("pk", "USER#1").With("name", "Alice").SendAsync(ct).

public static PutCommand<Item> Put(this Table<Item> table)

Parameters

table Table<Item>

The table.

Returns

PutCommand<Item>

The command.

Query(Index<Item>, AttributeValue, SortKeyCondition)

Starts a query of one partition of an index of a table without a schema by the value of its partition key: shop.Index("GSI1", "gsi1pk", "gsi1sk").Query("STATUS#open"). See Index<T> for what is different about reading an index.

public static QueryCommand<Item> Query(this Index<Item> index, AttributeValue partitionKey, SortKeyCondition sortKey = default)

Parameters

index Index<Item>

The index.

partitionKey AttributeValue

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

sortKey SortKeyCondition

The condition on the sort key of the index, or the default value to read the whole partition.

Returns

QueryCommand<Item>

The command.

Remarks

As written. The value goes out as it is. An index of an entity takes the partition key its generator built instead, byStatus.Query(Order.Keys.ByStatusPk.Of(status)).

Exceptions

ArgumentNullException

index is null.

ArgumentException

The key is empty, or there is a condition on a sort key and the index has none.

Query(Index<Item>, IEnumerable<AttributeValue>, SortKeyCondition)

Starts a query of several partitions of an index of a table without a schema, merged by the sort key of the index: the read of a sharded index. It costs at least one read per partition.

public static FanOutQueryCommand<Item> Query(this Index<Item> index, IEnumerable<AttributeValue> partitionKeys, SortKeyCondition sortKey = default)

Parameters

index Index<Item>

The index.

partitionKeys IEnumerable<AttributeValue>

The partitions, enumerated once, here. Their order breaks ties between equal sort keys. With none, the read gives nothing and sends nothing.

sortKey SortKeyCondition

The condition on the sort key of the index, the same for all partitions, or the default value to read them whole.

Returns

FanOutQueryCommand<Item>

The command.

Remarks

As written. The value goes out as it is. An index of an entity takes the partition key its generator built instead, byStatus.Query(Order.Keys.ByStatusPk.Of(status)).

Exceptions

ArgumentNullException

index or partitionKeys is null.

ArgumentException

A partition key is empty or occurs twice, which the message places by position, or there is a condition on a sort key and the index has none.

Query(Index<Item>, IEnumerable<string>, SortKeyCondition)

Starts a query of several partitions of an index of a table without a schema by string keys that are computed. It costs at least one read per partition.

public static FanOutQueryCommand<Item> Query(this Index<Item> index, IEnumerable<string> partitionKeys, SortKeyCondition sortKey = default)

Parameters

index Index<Item>

The index.

partitionKeys IEnumerable<string>

The partitions, enumerated once, here. Their order breaks ties between equal sort keys. With none, the read gives nothing and sends nothing.

sortKey SortKeyCondition

The condition on the sort key of the index, the same for all partitions, or the default value to read them whole.

Returns

FanOutQueryCommand<Item>

The command.

Remarks

Last choice. This overload yields to every other, so a call binds to it only when no other applies. That takes C# 13: a compiler below it ignores the priority, and a string[] needs AsSpan() there.

Exceptions

ArgumentNullException

index or partitionKeys is null.

ArgumentException

A partition key is null, empty or occurs twice, which the message places by position, or there is a condition on a sort key and the index has none.

Query(Index<Item>, scoped ReadOnlySpan<string>, SortKeyCondition)

Starts a query of several partitions of an index of a table without a schema by their string keys, such as ["SHARD#0", "SHARD#1"]. It costs at least one read per partition.

public static FanOutQueryCommand<Item> Query(this Index<Item> index, scoped ReadOnlySpan<string> partitionKeys, SortKeyCondition sortKey = default)

Parameters

index Index<Item>

The index.

partitionKeys ReadOnlySpan<string>

The partitions, read here and not kept. Their order breaks ties between equal sort keys. With none, the read gives nothing and sends nothing.

sortKey SortKeyCondition

The condition on the sort key of the index, the same for all partitions, or the default value to read them whole.

Returns

FanOutQueryCommand<Item>

The command.

Remarks

As written. The value goes out as it is. An index of an entity takes the partition key its generator built instead, byStatus.Query(Order.Keys.ByStatusPk.Of(status)).

Exceptions

ArgumentNullException

index is null.

ArgumentException

A partition key is null, empty or occurs twice, which the message places by position, or there is a condition on a sort key and the index has none.

Query(Table<Item>, AttributeValue, SortKeyCondition)

Starts a query of one partition of a table without a schema by the value of its partition key: shop.Query("CUSTOMER#1", SortKeyCondition.BeginsWith("ORDER#")). Read it as several entities with Of<Customer, Order>().

public static QueryCommand<Item> Query(this Table<Item> table, AttributeValue partitionKey, SortKeyCondition sortKey = default)

Parameters

table Table<Item>

The table.

partitionKey AttributeValue

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

sortKey SortKeyCondition

The condition on the sort key, or the default value to read the whole partition.

Returns

QueryCommand<Item>

The command.

Remarks

As written. The value goes out as it is. A table of an entity takes the partition key its generator built instead, orders.Query(Order.Keys.Pk.Of("1")), which formats it as the entity stores it.

Exceptions

ArgumentNullException

table is null.

ArgumentException

The key is empty, or there is a condition on a sort key and the table has none.

Query(Table<Item>, IEnumerable<AttributeValue>, SortKeyCondition)

Starts a query of several partitions of a table without a schema, merged by sort key, for write shards and time buckets. It costs at least one read per partition, see FanOutQueryCommand<T>.

public static FanOutQueryCommand<Item> Query(this Table<Item> table, IEnumerable<AttributeValue> partitionKeys, SortKeyCondition sortKey = default)

Parameters

table Table<Item>

The table.

partitionKeys IEnumerable<AttributeValue>

The partitions, enumerated once, here. Their order breaks ties between equal sort keys. With none, the read gives nothing and sends nothing.

sortKey SortKeyCondition

The condition on the sort key, the same for all partitions, or the default value to read them whole.

Returns

FanOutQueryCommand<Item>

The command.

Remarks

As written. The value goes out as it is. A table of an entity takes the partition key its generator built instead, orders.Query(Order.Keys.Pk.Of("1")), which formats it as the entity stores it.

Exceptions

ArgumentNullException

table or partitionKeys is null.

ArgumentException

A partition key is empty or occurs twice, which the message places by position, or there is a condition on a sort key and the table has none.

Query(Table<Item>, IEnumerable<string>, SortKeyCondition)

Starts a query of several partitions of a table without a schema by string keys that are computed: shop.Query(Enumerable.Range(0, 8).Select(static shard => $"SHARD#{shard}")). It costs at least one read per partition.

public static FanOutQueryCommand<Item> Query(this Table<Item> table, IEnumerable<string> partitionKeys, SortKeyCondition sortKey = default)

Parameters

table Table<Item>

The table.

partitionKeys IEnumerable<string>

The partitions, enumerated once, here. Their order breaks ties between equal sort keys. With none, the read gives nothing and sends nothing.

sortKey SortKeyCondition

The condition on the sort key, the same for all partitions, or the default value to read them whole.

Returns

FanOutQueryCommand<Item>

The command.

Remarks

Last choice. This overload yields to every other, so a call binds to it only when no other applies. That takes C# 13: a compiler below it ignores the priority, and a string[] needs AsSpan() there.

Exceptions

ArgumentNullException

table or partitionKeys is null.

ArgumentException

A partition key is null, empty or occurs twice, which the message places by position, or there is a condition on a sort key and there is no sort key.

Query(Table<Item>, scoped ReadOnlySpan<string>, SortKeyCondition)

Starts a query of several partitions of a table without a schema by their string keys: shop.Query(["SHARD#0", "SHARD#1"]). It costs at least one read per partition.

public static FanOutQueryCommand<Item> Query(this Table<Item> table, scoped ReadOnlySpan<string> partitionKeys, SortKeyCondition sortKey = default)

Parameters

table Table<Item>

The table.

partitionKeys ReadOnlySpan<string>

The partitions, read here and not kept. Their order breaks ties between equal sort keys. With none, the read gives nothing and sends nothing.

sortKey SortKeyCondition

The condition on the sort key, the same for all partitions, or the default value to read them whole.

Returns

FanOutQueryCommand<Item>

The command.

Remarks

As written. The value goes out as it is. A table of an entity takes the partition key its generator built instead, orders.Query(Order.Keys.Pk.Of("1")), which formats it as the entity stores it.

Exceptions

ArgumentNullException

table is null.

ArgumentException

A partition key is null, empty or occurs twice, which the message places by position, or there is a condition on a sort key and there is no sort key.

Update(Table<Item>, AttributeValue, AttributeValue)

Starts an UpdateItem of one item of a table without a schema by the values of its key. It creates the item if none has the key, unless IfExists() says otherwise.

public static UpdateCommand<Item> Update(this Table<Item> table, AttributeValue partitionKey, AttributeValue sortKey = default)

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.

Returns

UpdateCommand<Item>

The command.

Remarks

As written. The values go out as they are. A table of an entity takes the key its generator built instead, customers.Get(Customer.Keys.Of("1")), which formats them as the entity stores them.

Exceptions

ArgumentNullException

table is null.

ArgumentException

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

With(PutCommand<Item>, string, AttributeValue)

Adds an attribute to the item of a put. The name is the attribute name as it is, not a path. DynamoDB allows a name once in an item, and nothing checks that here.

public static PutCommand<Item> With(this PutCommand<Item> command, string name, AttributeValue value)

Parameters

command PutCommand<Item>

The command.

name string

The attribute name.

value AttributeValue

The value.

Returns

PutCommand<Item>

The command, which replaces this one.

With<TNumber>(PutCommand<Item>, string, TNumber)

Adds a number attribute to the item of a put.

public static PutCommand<Item> With<TNumber>(this PutCommand<Item> command, string name, TNumber value) where TNumber : INumberBase<TNumber>

Parameters

command PutCommand<Item>

The command.

name string

The attribute name.

value TNumber

The number.

Returns

PutCommand<Item>

The command, which replaces this one.

Type Parameters

TNumber

The type of the number.

With<TValue, TConverter>(PutCommand<Item>, Attr<TValue, TConverter>, TValue)

Adds an attribute to the item of a put through its converter. A handle of a property with OmitEmptyAttribute adds nothing for an empty string or collection, and neither does any value that IsOmitted(T) of the converter counts as null.

public static PutCommand<Item> With<TValue, TConverter>(this PutCommand<Item> command, Attr<TValue, TConverter> attribute, TValue value) where TConverter : IDynamoDbConverter<TValue>

Parameters

command PutCommand<Item>

The command.

attribute Attr<TValue, TConverter>

The attribute, whose path must be a plain name.

value TValue

The value.

Returns

PutCommand<Item>

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.