01 Entities and values

An entity is one record: an entity name (the table, collection or DynamoDB entity it belongs to) and its attributes, a map from attribute name to value. An implementation must expose it as a dictionary-like object (.NET: new ArxEntity("account"); entity["name"] = "Northwind Traders").

• Attribute names are kept as given and matched ignoring letter case, on read and on write: entity["Name"] finds name, and setting entity["Name"] replaces it (the name it was first added with is kept). Reading a name the entity doesn't have gives null.
• Two attribute names on one entity that differ only in letter case (possible only through a collection built over a case-sensitive dictionary) must be refused by the provider (ARX1004 DuplicateAttribute) before anything is sent; a read whose result has two such columns or fields is refused with ARX1004 too.
• A plain .NET enum value is refused (ARX1007 UnsupportedValueType) before anything is sent: its name and its number are both reasonable, so the code says which ((int)value, value.ToString()), or uses a selection set value.
• An entity carries a record id (RecordId, chapter 02) once it was created or read; it is the only id property.
• A special value Ignore (.NET: ArxIgnore) means "leave this attribute out of this write", as if it weren't set.

A provider must accept these values and map each to its database's type for that column or field. The kinds, and what a provider must do with each:

Kind	Notes
text	Stored as given. Text is never parsed into another kind: a text value for a date column is ARX4004 DataTypeMismatch, never converted
integer (8, 16, 32, 64 bits, signed and unsigned)	Out of the column's range: ARX4001 ValueOutOfRange
decimal	Exact. More digits than the column holds: ARX4001
floating point	NaN and infinity only where the database stores them; otherwise ARX4001
boolean
UUID
bytes
JSON (ArxJsonB)	A document or array, stored as the database's JSON type or as an embedded document
a list of the scalar kinds	Where the database has arrays or lists; otherwise ARX8001
date, time, date and time, instant (DateOnly, TimeOnly, DateTime, DateTimeOffset)	See "Dates and times"
a reference (ArxEntityReference)	Stored as the referenced record's id (chapter 02, lookups)
a selection set value (ArxSelectionSetValue)	Stored as its raw code, validated against the catalog (below)
null	Stored as the database's null. On DynamoDB an Update to null removes the attribute; reading either back gives null

A value of any other type must be refused with ARX1007 UnsupportedValueType. Values reach the database only as parameters (chapter 07); a provider must never put a value into the text of a statement or expression.

• The "not set" defaults (default(DateTime), default(DateTimeOffset), default(DateOnly) in .NET: year 1) must be refused with ARX1013 InvalidDateTimeValue: they are never a real date and would be stored as one.
• A date and time with an offset or marked UTC is stored as that instant. One marked local is converted to UTC.
• One with no kind ("unspecified") is stored as the wall time given by the relational providers, and taken as UTC by the document and key-value providers (MongoDB, DynamoDB).
• A provider's own connections should use UTC as the session time zone (PostgreSQL Timezone=UTC, MySQL time_zone = '+00:00') unless the connection string names one.
• A provider must document the precision it keeps (MongoDB milliseconds; DynamoDB every tick as ISO 8601 text).

A selection set (an option set, a picklist) is a named list of options, each with a code, a display name and an order, declared by the developer in the catalog. The raw code is stored, of the kind the column holds: integer, text, character, boolean, decimal, UUID or a database enum. A set may allow one option, an array of options, or flags.

• A write of a selection set value must be checked against the catalog before the database: a set the catalog doesn't have is ARX1012 UnknownSelectionSet; a code it doesn't allow (unknown, of the wrong kind, retired, several for a single-option set, a duplicate) is ARX1011 SelectionSetValueNotAllowed.
• No implementation reads option tables from the database by itself.