Interface IUpdatable<TSelf>

Namespace

DynaSharp

Assembly

DynaSharp.dll

A command that changes attributes, for a helper that works on all of them, see IConditional<TSelf>. Audit fields are the usual case: command.Set("updatedBy", user).

public interface IUpdatable<TSelf> where TSelf : IUpdatable<TSelf>, allows ref struct

Type Parameters

TSelf

The command.

Methods

Add(string, AttributeValue)

Adds to a number, or adds elements to a set (ADD). An attribute that does not exist starts from zero or the empty set.

TSelf Add(string path, AttributeValue value)

Parameters

path string

The name or document path.

value AttributeValue

The number or the set.

Returns

TSelf

The command, which replaces this one.

Add<TValue, TConverter>(Attr<TValue, NullableHandleConverter<TValue, TConverter>>, TValue)

Adds to a nullable number (ADD), see Add<TValue, TConverter>(Attr<TValue, TConverter>, TValue).

TSelf Add<TValue, TConverter>(Attr<TValue, NullableHandleConverter<TValue, TConverter>> attribute, TValue value) where TValue : struct where TConverter : IDynamoDbConverter<TValue>, IAddableConverter

Parameters

attribute Attr<TValue, NullableHandleConverter<TValue, TConverter>>

The attribute.

value TValue

The number.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter, of a number: ADD takes nothing else, so an attribute of another type is a compile error.

Add<TValue, TConverter>(Attr<TValue, NullableReferenceHandleConverter<TValue, TConverter>>, TValue)

Adds elements to a nullable set (ADD), see Add<TValue, TConverter>(Attr<TValue, TConverter>, TValue).

TSelf Add<TValue, TConverter>(Attr<TValue, NullableReferenceHandleConverter<TValue, TConverter>> attribute, TValue value) where TValue : class where TConverter : IDynamoDbConverter<TValue>, IAddableConverter

Parameters

attribute Attr<TValue, NullableReferenceHandleConverter<TValue, TConverter>>

The attribute.

value TValue

The set.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter, of a set: ADD takes nothing else, so an attribute of another type is a compile error.

Add<TValue, TConverter>(Attr<TValue, TConverter>, TValue)

Adds to a number, or adds elements to a set (ADD). An attribute that does not exist starts from zero or the empty set, and a negative number subtracts.

TSelf Add<TValue, TConverter>(Attr<TValue, TConverter> attribute, TValue value) where TConverter : IDynamoDbConverter<TValue>, IAddableConverter

Parameters

attribute Attr<TValue, TConverter>

The attribute.

value TValue

The number or the set.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter, of a number or a set: ADD takes nothing else, so an attribute of another type is a compile error.

Remarks

Taking stock. Add(Product.Attrs.Stock, -quantity) with If(Product.Attrs.Stock.Ge(quantity)) takes stock without going below zero.

A retry adds twice. A retry of the client after a lost response repeats the addition to a number, except in a transaction, whose attempts carry one ClientRequestToken, so DynamoDB applies it once. MaxAttempts(1) makes it at most once, not exact: a lost response then reports a failure after the addition was applied. Only a condition, such as a version, makes it exact.

Delete(string, AttributeValue)

Removes elements from a set (DELETE). A set that ends up empty disappears, as DynamoDB has no empty sets.

TSelf Delete(string path, AttributeValue elements)

Parameters

path string

The name or document path.

elements AttributeValue

The elements, as a set.

Returns

TSelf

The command, which replaces this one.

Delete<TValue, TConverter>(Attr<TValue, TConverter>, TValue)

Removes elements from a set (DELETE). A set that ends up empty disappears, as DynamoDB has no empty sets.

TSelf Delete<TValue, TConverter>(Attr<TValue, TConverter> attribute, TValue elements) where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute.

elements TValue

The elements, as a set.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.

Remove(string)

Removes an attribute (REMOVE), or an element of a list, which moves the elements after it. Removing what does not exist is no error.

TSelf Remove(string path)

Parameters

path string

The name or document path.

Returns

TSelf

The command, which replaces this one.

Remove<TValue, TConverter>(Attr<TValue, TConverter>)

Removes an attribute (REMOVE), by its handle. Removing what does not exist is no error. A property that feeds a key of a sparse index takes the key attributes of that index with it, so that the item leaves the index; see Set<TValue, TConverter>(Attr<TValue, TConverter>, TValue?).

TSelf Remove<TValue, TConverter>(Attr<TValue, TConverter> attribute) where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.

Set(string, AttributeValue)

Sets an attribute, creating it if it does not exist (SET).

TSelf Set(string path, AttributeValue value)

Parameters

path string

The name or document path. The parent of a nested path must exist.

value AttributeValue

The value.

Returns

TSelf

The command, which replaces this one.

SetIfNotExists(string, AttributeValue)

Sets an attribute unless it exists (SET a = if_not_exists(a, value)).

TSelf SetIfNotExists(string path, AttributeValue value)

Parameters

path string

The name or document path.

value AttributeValue

The value.

Returns

TSelf

The command, which replaces this one.

SetIfNotExists<TValue, TConverter>(Attr<TValue, TConverter>, TValue)

Sets an attribute unless it exists (SET a = if_not_exists(a, value)).

TSelf SetIfNotExists<TValue, TConverter>(Attr<TValue, TConverter> attribute, TValue value) where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute.

value TValue

The value.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.

Exceptions

ArgumentNullException

value is null.

ArgumentException

value is empty, on a property with OmitEmptyAttribute, which counts that as null, or anything else that IsOmitted(T) of the converter counts as null.

SetIfNotNull<TValue, TConverter>(Attr<TValue, TConverter>, TValue?)

Sets an attribute of a value type if the nullable value has a value, and adds nothing if it has none. With a value it costs what Set<TValue, TConverter>(Attr<TValue, TConverter>, TValue?) costs. See SetIfNotNull<TValue, TConverter>(Attr<TValue, TConverter>, TValue?).

TSelf SetIfNotNull<TValue, TConverter>(Attr<TValue, TConverter> attribute, TValue? value) where TValue : struct where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute.

value TValue?

The value, or null to leave the attribute alone.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.

SetIfNotNull<TValue, TConverter>(Attr<TValue, TConverter>, TValue?)

Sets an attribute if there is a value, and leaves it as it is if the value is null, which is what an update of optional fields wants: .SetIfNotNull(Customer.Attrs.Email, request.Email).

TSelf SetIfNotNull<TValue, TConverter>(Attr<TValue, TConverter> attribute, TValue? value) where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute.

value TValue

The value, or null to leave the attribute alone.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.

Remarks

With a value it is Set<TValue, TConverter>(Attr<TValue, TConverter>, TValue?), with all it says about keys. With null the attribute stays as it is, where Set would remove it, and a property that feeds a key counts as untouched. On a property with OmitEmptyAttribute an empty string or collection is no value either. An update that ends up with no action is still an UpdateItem: it checks its conditions, creates the item if none has the key, and writes what the entity owes it, such as its discriminator.

Set<TValue, TConverter>(Attr<TValue, TConverter>, TValue?)

Sets an attribute of a value type from a nullable value, which is what a nullable property holds, or removes it when there is no value: a Nullable<T> with a value is Set<TValue, TConverter>(Attr<TValue, TConverter>, TValue?) at the same cost, and without one it is Remove<TValue, TConverter>(Attr<TValue, TConverter>). The rules of a property that feeds a key are the ones of those two.

TSelf Set<TValue, TConverter>(Attr<TValue, TConverter> attribute, TValue? value) where TValue : struct where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute.

value TValue?

The value, or null to remove the attribute.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.

Set<TValue, TConverter>(Attr<TValue, TConverter>, TValue?)

Sets an attribute, creating it if it does not exist (SET), and keeps every key made from it consistent, or throws when the command ends. A null value is a Remove<TValue, TConverter>(Attr<TValue, TConverter>), for every attribute, because a generated entity writes no attribute for a null property either. On a property with OmitEmptyAttribute an empty string or collection is one too.

TSelf Set<TValue, TConverter>(Attr<TValue, TConverter> attribute, TValue? value) where TConverter : IDynamoDbConverter<TValue>

Parameters

attribute Attr<TValue, TConverter>

The attribute.

value TValue

The value, or null to remove the attribute.

Returns

TSelf

The command, which replaces this one.

Type Parameters

TValue

The type of the attribute.

TConverter

The converter.

Remarks

Key templates. The handle of a property that feeds a key template keeps that key consistent, which a raw path does not. When the command ends, all inputs of the template must be known: then the derived attribute is written in the same SET, and otherwise sending throws InvalidOperationException naming the template and the Set calls to add, because the index would go stale. An update expression can copy an attribute and cannot format one, so an input of a key of several values or with literals that does not change is set as well, to the value the item holds. An input of a key of the table is known from the key the update was given, and it cannot be set, because DynamoDB cannot update a key, so an index key that repeats it needs nothing more: that is the place for an input that never changes. A key given as strings is parsed for that, so a value that its text does not hold, such as a timestamp a key cuts off at the day, comes from a generated key or not at all: then use a Put of the changed entity, or a raw path. A write by handle to a property that a computed input is derived from, see ComputedFromAttribute, also to a path inside it, throws in the same way, because no update can run a getter, and so does a write by handle to such a computed input itself.

Sparse indexes. An index takes an item only with all its keys, so setting one key of a sparse index needs the other one in the same update, or sending throws InvalidOperationException naming it: an update does not read the item, so it cannot tell whether the item holds the other key, and an item without it would stay out of the index without an error. A key of literals, of any index, and a key made only of inputs of the table key are no such keys: they are written in the same SET, and removed with the other key. A key that is the stored text of an attribute, one bare placeholder such as {Owner} over a string, also with :raw, a Guid, a DateOnly, a timestamp in ticks or an enum by name, each with its built-in converter, is copied in the same SET, gsi1pk = Owner, so the update needs no value for it. DynamoDB evaluates the copy on the item: an item without the attribute, also one that the update would create, fails the whole update with ValidationException, "The provided expression refers to an attribute that does not exist in the item", and is left as it was.

Add and SetIfNotExists. By the handle of such a property they throw too: the value they leave is not known here, so the key cannot follow. In a transaction the check runs when the action ends, at the next verb.