Struct AttributeValue
- Namespace
- DynaSharp
- Assembly
- DynaSharp.dll
A single DynamoDB attribute value: string, number, binary, boolean, null, list, map or set.
public readonly struct AttributeValue : IEquatable<AttributeValue>- Implements
- Inherited Members
Examples
var item = new Item { ["pk"] = "USER#alice", ["age"] = 42, ["active"] = true };
AttributeValue tags = AttributeValue.FromStringSet(["keyboards", "mice"]);
AttributeValue settings = AttributeValue.FromJson("""{"theme":"dark","columns":[1,2]}"""u8);Remarks
This is the representation used by the low-level API (for example Key) and by Item.
Entities mapped by the source generator are serialized directly and never go through it. Strings, int,
long, decimal, double, bool and byte[] convert implicitly,
so ["pk"] = "user-1", ["age"] = 42, ["active"] = true works in an item initializer. Other number types go through
FromNumber<T>(T); the other kinds (lists, maps, sets, null) have factory methods. A char becomes a string, not
a number.
Numbers are kept as text, exactly as DynamoDB transfers them, so no precision is lost: DynamoDB numbers have up
to 38 significant digits, more than decimal or double can hold. Equality of numbers is
therefore textual: 1 and 1.0 are different values here, although DynamoDB treats them as equal.
Values are immutable: factory methods copy mutable inputs. The collections returned by AsList(), AsMap() and the set accessors are the stored collections themselves, read-only: do not cast them to a mutable type and change them. Equality is structural (deep) for lists and maps; sets compare without regard to order. A default instance has None and cannot be sent to DynamoDB.
Properties
IsNull
Gets a value indicating whether this is the DynamoDB null value ({"NULL": true}).
public bool IsNull { get; }Property Value
Null
Gets the DynamoDB null value.
public static AttributeValue Null { get; }Property Value
Type
Gets the data type of this value.
public AttributeType Type { get; }Property Value
Methods
AsBinary()
Gets the bytes of a Binary value.
public ReadOnlyMemory<byte> AsBinary()Returns
- ReadOnlyMemory<byte>
The bytes.
Exceptions
- InvalidOperationException
The value has another type.
AsBinarySet()
Gets the elements of a BinarySet value.
public IReadOnlyList<ReadOnlyMemory<byte>> AsBinarySet()Returns
- IReadOnlyList<ReadOnlyMemory<byte>>
The elements. The order carries no meaning.
Exceptions
- InvalidOperationException
The value has another type.
AsBool()
Gets the boolean of a Boolean value.
public bool AsBool()Returns
- bool
The boolean.
Exceptions
- InvalidOperationException
The value has another type.
AsList()
Gets the elements of a List value.
public IReadOnlyList<AttributeValue> AsList()Returns
- IReadOnlyList<AttributeValue>
The elements in order.
Exceptions
- InvalidOperationException
The value has another type.
AsMap()
Gets the entries of a Map value.
public IReadOnlyDictionary<string, AttributeValue> AsMap()Returns
- IReadOnlyDictionary<string, AttributeValue>
The entries.
Exceptions
- InvalidOperationException
The value has another type.
AsNumber()
Gets the text of a Number value, as transferred.
public string AsNumber()Returns
- string
The number as text.
Exceptions
- InvalidOperationException
The value has another type.
AsNumberSet()
Gets the elements of a NumberSet value as text.
public IReadOnlyList<string> AsNumberSet()Returns
- IReadOnlyList<string>
The elements. The order carries no meaning.
Exceptions
- InvalidOperationException
The value has another type.
AsNumber<T>()
Parses a Number value with the invariant culture.
public T AsNumber<T>() where T : INumberBase<T>Returns
- T
The parsed number. Exponent notation such as
1E+2is accepted, also for integer types.
Type Parameters
TThe target number type.
Exceptions
- InvalidOperationException
The value has another type.
- FormatException
The text cannot be represented as
T.- OverflowException
The number is outside the range of
T, has a fractional part andTis an integer type, orTis decimal and cannot hold its exact value, which takes 28 to 29 significant digits at most, where DynamoDB has 38. A binary floating-point type counts a number that rounds to infinity, andNaN, as out of range; it rounds any other number to the nearest value it holds, and one below its range reads as 0.
AsString()
Gets the string of a String value.
public string AsString()Returns
- string
The string.
Exceptions
- InvalidOperationException
The value has another type.
AsStringSet()
Gets the elements of a StringSet value.
public IReadOnlyList<string> AsStringSet()Returns
- IReadOnlyList<string>
The elements. The order carries no meaning.
Exceptions
- InvalidOperationException
The value has another type.
Equals(AttributeValue)
public bool Equals(AttributeValue other)Parameters
otherAttributeValue
Returns
Equals(object?)
public override bool Equals(object? obj)Parameters
objobject
Returns
FromBinary(ReadOnlySpan<byte>)
Creates a binary value. The bytes are copied.
public static AttributeValue FromBinary(ReadOnlySpan<byte> value)Parameters
valueReadOnlySpan<byte>The bytes.
Returns
- AttributeValue
The value.
FromBinarySet(IEnumerable<byte[]>)
Creates a binary set. Sequence and bytes are copied.
public static AttributeValue FromBinarySet(IEnumerable<byte[]> values)Parameters
valuesIEnumerable<byte[]>The binary values. DynamoDB requires a set to be non-empty and free of duplicates.
Returns
- AttributeValue
The value.
Exceptions
- ArgumentNullException
valuesor an element is null.- ArgumentException
valuesis empty or contains duplicates by content.
FromBool(bool)
Creates a boolean value.
public static AttributeValue FromBool(bool value)Parameters
valueboolThe boolean.
Returns
- AttributeValue
The value.
FromJson(ReadOnlySpan<byte>)
Creates the value that holds JSON text as DynamoDB stores it natively, as FromJson(JsonElement) does, without a document in between, for example from
JsonSerializer.SerializeToUtf8Bytes(value, context.Type).
public static AttributeValue FromJson(ReadOnlySpan<byte> utf8Json)Parameters
utf8JsonReadOnlySpan<byte>One JSON value as UTF-8, by RFC 8259: no comments, no trailing commas, nothing after the value but white space.
Returns
- AttributeValue
The value.
Exceptions
- JsonException
utf8Jsonis not one JSON value.- ArgumentException
DynamoDB cannot store the JSON, see FromJson(JsonElement), or a string or a name is not valid UTF-8.
FromJson(JsonElement)
Creates the value that holds a JSON value as DynamoDB stores it natively: an object is a map, an array a list, a string a string, a number a number with its digits as written,
true and false a boolean, and null Null. Filters, projections and updates then reach into it by path, which a JSON string in one attribute does not allow.
public static AttributeValue FromJson(JsonElement json)Parameters
jsonJsonElementThe JSON, for example from
JsonSerializer.SerializeToElement(value, context.Type).
Returns
- AttributeValue
The value.
Remarks
A null in an object is left out of the map, so a field that was null reads back missing. A null in an array is Null, which keeps the positions of the others. Empty strings, arrays and objects stay, as DynamoDB allows them outside keys. JSON has no sets and no binary, so neither comes out of this, and ToJson() gives a set as an array.
DynamoDB stores a number in a canonical form, so 1.50 reads back as 1.5, and 1E+2 as 100: the value stays, its text can change on a round trip.
Exceptions
- ArgumentException
DynamoDB cannot store the JSON, and the message names the place, such as
$.lines[2].weight, never a value: a number with more than 38 significant digits or a magnitude outside 1E-130 to below 1E+126, a value nested deeper than 32 levels (a string is one level, an object of a string two), an empty name, a name twice in one object, text with a lone surrogate, or a defaultjson, which holds no JSON. The levels count from this value: DynamoDB counts from the attribute, so a value stored inside a map has fewer.
FromList(IEnumerable<AttributeValue>)
Creates a list value. The sequence is copied; elements may have different types.
public static AttributeValue FromList(IEnumerable<AttributeValue> values)Parameters
valuesIEnumerable<AttributeValue>The elements, possibly none.
Returns
- AttributeValue
The value.
Exceptions
- ArgumentNullException
valuesis null.- ArgumentException
An element has None.
FromMap(IEnumerable<KeyValuePair<string, AttributeValue>>)
Creates a map value. The entries are copied.
public static AttributeValue FromMap(IEnumerable<KeyValuePair<string, AttributeValue>> values)Parameters
valuesIEnumerable<KeyValuePair<string, AttributeValue>>The entries, possibly none.
Returns
- AttributeValue
The value.
Exceptions
- ArgumentNullException
valuesor a key is null.- ArgumentException
A key is duplicated, or a value has None.
FromNumber(string)
Creates a number value from its textual representation, sent to DynamoDB unchanged.
public static AttributeValue FromNumber(string value)Parameters
valuestringThe number as text, for example
"42"or"-1.5E-10". DynamoDB validates the format.
Returns
- AttributeValue
The value.
Exceptions
- ArgumentNullException
valueis null.- ArgumentException
valueis empty.
FromNumberSet(IEnumerable<string>)
Creates a number set from textual numbers, sent to DynamoDB unchanged. The sequence is copied.
public static AttributeValue FromNumberSet(IEnumerable<string> values)Parameters
valuesIEnumerable<string>The numbers as text. DynamoDB requires a set to be non-empty and free of duplicates.
Returns
- AttributeValue
The value.
Exceptions
- ArgumentNullException
valuesor an element is null.- ArgumentException
valuesis empty, contains an empty element, or contains textual duplicates.
FromNumber<T>(T)
Creates a number value, formatted with the invariant culture. A char counts as a number type in .NET but not here: it becomes a string value, as its implicit conversion does.
public static AttributeValue FromNumber<T>(T value) where T : INumberBase<T>Parameters
valueTThe number.
Returns
- AttributeValue
The value.
Type Parameters
Exceptions
- ArgumentOutOfRangeException
valueis NaN or infinite; DynamoDB cannot store either.
FromString(string)
Creates a string value.
public static AttributeValue FromString(string value)Parameters
valuestringThe string. Empty strings are allowed except in key attributes, which DynamoDB validates.
Returns
- AttributeValue
The value.
Exceptions
- ArgumentNullException
valueis null.
FromStringSet(IEnumerable<string>)
Creates a string set. The sequence is copied.
public static AttributeValue FromStringSet(IEnumerable<string> values)Parameters
valuesIEnumerable<string>The strings. DynamoDB requires a set to be non-empty and free of duplicates.
Returns
- AttributeValue
The value.
Exceptions
- ArgumentNullException
valuesor an element is null.- ArgumentException
valuesis empty or contains duplicates.
GetHashCode()
public override int GetHashCode()Returns
ToJson()
Converts the value to plain JSON: a map becomes an object, a list an array, and a number keeps its text. A set becomes an array and a binary value a base64 string, which FromJson(JsonElement) does not turn back; see WriteJson(Utf8JsonWriter).
public JsonElement ToJson()Returns
- JsonElement
A JSON element that owns its memory.
Exceptions
- InvalidOperationException
The value is a default instance, which has no type.
- FormatException
A number made with FromNumber(string) is not in the form of a JSON number.
- ArgumentException
A string made by hand holds a lone surrogate, which is no text.
ToString()
Returns the value in DynamoDB JSON, for example {"S":"abc"}. Intended for debugging; the debugger shows this text, without quotes.
public override string ToString()Returns
- string
The DynamoDB JSON text, with U+FFFD for a lone surrogate, which no write takes, or an empty string for a default instance.
WriteJson(Utf8JsonWriter)
Writes the value as plain JSON, the reverse of FromJson(JsonElement): a map is an object, a list an array, a string a string, a number a number with its text as stored,
never through a double, a boolean a boolean, and Null null. To read it into a type, deserialize what this writes, or what ToJson() gives,
with a source-generated JsonSerializerContext.
public void WriteJson(Utf8JsonWriter writer)Parameters
writerUtf8JsonWriterThe destination, positioned where a value is expected. Its settings decide the escaping and the indentation.
Remarks
What JSON has no form for goes one way: a string set and a number set are written as an array, and a binary value and a binary set as the base64 text of the bytes, which FromJson(JsonElement) reads back as strings. A Null in a map is written as null, where FromJson(JsonElement) leaves a null out.
Exceptions
- ArgumentNullException
writeris null.- InvalidOperationException
The value is a default instance, which has no type.
- FormatException
A number made with FromNumber(string) is not in the form of a JSON number.
- ArgumentException
A string made by hand holds a lone surrogate, which is no text.
Operators
operator ==(AttributeValue, AttributeValue)
Compares two values structurally.
public static bool operator ==(AttributeValue left, AttributeValue right)Parameters
leftAttributeValueThe first value.
rightAttributeValueThe second value.
Returns
implicit operator AttributeValue(bool)
Converts a boolean to a boolean value, see FromBool(bool).
public static implicit operator AttributeValue(bool value)Parameters
valueboolThe boolean.
Returns
implicit operator AttributeValue(byte[])
Converts bytes to a binary value, see FromBinary(ReadOnlySpan<byte>). The bytes are copied.
public static implicit operator AttributeValue(byte[] value)Parameters
valuebyte[]The bytes.
Returns
Exceptions
- ArgumentNullException
valueis null.
implicit operator AttributeValue(char)
Converts a character to a string value. Declared because a char would otherwise widen to int, so 'a' would become the number 97.
public static implicit operator AttributeValue(char value)Parameters
valuecharThe character.
Returns
implicit operator AttributeValue(decimal)
Converts a decimal to a number value, see FromNumber<T>(T). The text keeps the scale: 1.50m becomes 1.50.
public static implicit operator AttributeValue(decimal value)Parameters
valuedecimalThe number.
Returns
implicit operator AttributeValue(double)
Converts a double to a number value, see FromNumber<T>(T).
public static implicit operator AttributeValue(double value)Parameters
valuedoubleThe number, which must be finite.
Returns
Exceptions
- ArgumentOutOfRangeException
valueis NaN or infinite; DynamoDB cannot store either.
implicit operator AttributeValue(int)
Converts an integer to a number value, see FromNumber<T>(T).
public static implicit operator AttributeValue(int value)Parameters
valueintThe number.
Returns
implicit operator AttributeValue(long)
Converts an integer to a number value, see FromNumber<T>(T).
public static implicit operator AttributeValue(long value)Parameters
valuelongThe number.
Returns
implicit operator AttributeValue(string)
Converts a string to a string value, see FromString(string).
public static implicit operator AttributeValue(string value)Parameters
valuestringThe string.
Returns
operator !=(AttributeValue, AttributeValue)
Compares two values structurally.
public static bool operator !=(AttributeValue left, AttributeValue right)Parameters
leftAttributeValueThe first value.
rightAttributeValueThe second value.