Class Datum

Namespace: YndigoBlue.Velocity.Model

Assembly: YndigoBlue.Velocity.dll

Abstract base class for working with database row data, providing strongly-typed field access and automatic type conversions.

[Serializable]
public abstract class Datum

Inheritance: object

Datum

Derived: Record

Result

Remarks

Datum is the foundation for all data row handling in Velocity. It provides:

Strongly-typed SetField* and GetField* methods for all supported data types
Automatic type conversions between compatible types
NULL value handling
Indexer access to field values
Support for spatial data (Geometry and Geography) via NetTopologySuite

Datum is inherited by:

Record - For inserting/updating database rows
Result - For reading query results

Supported Data Types:

Datum supports all Velocity data types with automatic conversion between compatible types:

Numeric: Byte, Short, Integer, Long, Float, Double, Decimal
Text: Char, VarChar, String, Clob (automatic conversion between string types)
Binary: Blob (byte arrays)
Date/Time: Date, DateTime, Timestamp (with UNIX epoch conversion)
Boolean: Boolean (converts from numeric 0/1 or string "true"/"false")
Spatial: Geometry, Geography (WKT/WKB support via NetTopologySuite)
Identifiers: Guid (stored as VarChar)

Type Conversions:

Datum automatically converts between compatible types when getting field values:

String fields can be retrieved as numeric types if parseable
Numeric types can be retrieved as other numeric types (with range checks)
DateTime/Date can be retrieved as integers (UNIX epoch seconds)
Integers can be retrieved as DateTime (from UNIX epoch)
Boolean can be retrieved as numeric (0 or 1) and vice versa
Geometry/Geography can be retrieved as WKT strings

Examples

Using Datum through Record (for INSERT/UPDATE):

using (Manager manager = new Manager(connection))
{
    manager.LoadSchema("my_schema");
    Schema schema = manager.GetSchema("my_schema");
    Table usersTable = schema["users"];

    // Create a record and set field values
    Record<Table> record = new Record<Table>(usersTable);
    record.SetFieldInteger("id", 12345);
    record.SetFieldVarChar("username", "john_doe");
    record.SetFieldVarChar("email", "john@example.com");
    record.SetFieldDateTime("created_at", DateTime.UtcNow);
    record.SetFieldBoolean("is_active", true);

    // Insert into database
    manager.AddRecord(record);
}

Using Datum through Result (for SELECT):

Query query = new Query();
query.AddFromItem(usersTable);
query.AddSelectItem(usersTable["id"]);
query.AddSelectItem(usersTable["username"]);
query.AddSelectItem(usersTable["created_at"]);

IEnumerable<Result> results = manager.Retrieve(query);

foreach (Result result in results)
{
    // Get field values with strong typing
    int id = result.GetFieldInteger("id");
    string username = result.GetFieldVarChar("username");
    DateTime createdAt = result.GetFieldDateTime("created_at");

    Console.WriteLine($"{id}: {username} (created {createdAt})");
}

Handling NULL values:

Record<Table> record = new Record<Table>(usersTable);
record.SetFieldInteger("id", 12345);
record.SetFieldVarChar("username", "john_doe");
record.SetFieldVarChar("email", null); // Set NULL

manager.AddRecord(record);

// Check for NULL when reading
Query query = new Query();
query.AddFromItem(usersTable);
query.AddSelectItem(usersTable["email"]);
query.AddWhereClause(new Criterion<int>(usersTable["id"], 12345));

Result result = manager.Retrieve(query).First();

if (result.IsNull("email"))
{
    Console.WriteLine("Email is NULL");
}
else
{
    string email = result.GetFieldVarChar("email");
    Console.WriteLine($"Email: {email}");
}

Automatic type conversions:

Result result = manager.Retrieve(query).First();

// Get boolean from integer column (0 = false, 1 = true)
bool isActive = result.GetFieldBoolean("status_flag");

// Get DateTime as UNIX timestamp
int createdTimestamp = result.GetFieldInteger("created_at");

// Get numeric value as string
string idString = result.GetFieldVarChar("id");

// Get string as integer (if parseable)
int parsedValue = result.GetFieldInteger("numeric_string_field");

Working with spatial data:

using NetTopologySuite.Geometries;

// Insert geometry data
Record<Table> record = new Record<Table>(locationsTable);
record.SetFieldInteger("id", 1);
record.SetFieldVarChar("name", "Home");

Point location = new Point(-122.4194, 37.7749); // San Francisco
record.SetFieldGeometry("coordinates", location);

manager.AddRecord(record);

// Retrieve geometry data
Query query = new Query();
query.AddFromItem(locationsTable);
query.AddSelectItem(locationsTable["coordinates"]);

Result result = manager.Retrieve(query).First();
Point retrievedLocation = result.GetFieldGeometry<Point>("coordinates");

Console.WriteLine($"Lat: {retrievedLocation.Y}, Lon: {retrievedLocation.X}");

Using indexers for dynamic access:

Result result = manager.Retrieve(query).First();

// Access by field name (untyped)
object usernameValue = result["username"];
object idValue = result["id"];

// Access by field index (untyped)
object firstField = result[0];
object secondField = result[1];

Working with GUIDs:

// Insert with GUID
Record<Table> record = new Record<Table>(usersTable);
record.SetFieldGuid("user_guid"); // Generates new GUID
record.SetFieldGuid("session_guid", Guid.NewGuid()); // Use specific GUID

manager.AddRecord(record);

// Retrieve GUID
Result result = manager.Retrieve(query).First();
Guid userGuid = result.GetFieldGuid("user_guid");

Properties

FieldCount: Gets the number of fields (columns) available in this datum.

Fields: Gets the collection of select items (columns) that define the structure of this datum.

this[int]: Gets or sets a field value by zero-based column index. Getting returns an untyped object; use the typed GetField* methods for type-safe access.

this[string]: Gets or sets a field value by column name. Getting returns an untyped object; use the typed GetField* methods for type-safe access.

Methods

GetField(int): Untyped version for retrieving a field value. Try to use the typed versions.

GetField(string): Untyped version for retrieving a field value. Try to use the typed versions.

GetFieldBlob(string): Gets the value of a BLOB field as a byte array.

GetFieldBoolean(string): Gets the value of a boolean field. Also converts from numeric (0/1), string ("true"/"false"), and decimal values.

GetFieldByte(string): Gets the value of a byte field. Also converts from string, boolean, integer, and floating-point values within the byte range.

GetFieldChar(string): Gets the value of a CHAR field as a string. Also returns values stored as string, varchar, or geometry (as WKT).

GetFieldClob(string): Gets the value of a CLOB field as a string. Also returns values stored as string or geometry (as WKT).

GetFieldDate(string): Gets the value of a date field as a DateOnly. Also converts from DateTime, Timestamp, string, and integer (UNIX epoch seconds) fields.

GetFieldDateTime(string): Gets the value of a DateTime field as a DateTime. Also converts from date, timestamp, string, and integer (UNIX epoch seconds) fields.

GetFieldDecimal(string): Gets the value of a decimal field. Also converts from string, integer, long, float, and double fields.

GetFieldDouble(string): Gets the value of a double-precision floating-point field. Also converts from float, string, integer, long, and decimal fields.

GetFieldFloat(string): Gets the value of a single-precision floating-point field. Also converts from string, integer, long, double, and decimal fields.

GetFieldGeography(string): Gets the value of a geography (geodetic/spherical) field as a Geography wrapper.

GetFieldGeography<T>(string): Gets the value of a geography (geodetic/spherical) field as the specified geometry subtype. Parses WKT/WKB if the value is stored as string or blob.

GetFieldGeometry(string): Gets the value of a geometry (planar spatial) field as a NetTopologySuite.Geometries.Geometry base type.

GetFieldGeometry<T>(string): Gets the value of a geometry (planar spatial) field as the specified geometry subtype. Parses WKT/WKB if the value is stored as string or blob.

GetFieldGuid(string): Gets the value of a GUID field. The GUID is stored as a varchar string and parsed on retrieval.

GetFieldInteger(string): Gets the value of a 32-bit integer field. Also converts from string, boolean, DateTime/Date (UNIX epoch), decimal, long, and floating-point fields.

GetFieldInterval(string): Gets the value of an interval field as a TimeSpan. Also converts from time, string, long, integer, and decimal fields.

GetFieldLong(string): Gets the value of a 64-bit integer (long) field. Also converts from string, boolean, DateTime/Date (UNIX epoch), decimal, and floating-point fields.

GetFieldShort(string): Gets the value of a 16-bit integer (short) field. Also converts from string, boolean, decimal, long, and floating-point fields.

GetFieldTime(string): Gets the value of a time field as a TimeOnly. Also converts from interval, string, DateTime, and Timestamp fields.

GetFieldTimestamp(string): Gets the value of a timestamp field as a DateTimeOffset. Also converts from DateTime, Date, string, integer, and long (UNIX epoch) fields.

GetFieldValue(int, DataType): Gets the value of a field at the specified index, returned as the CLR type that corresponds to dataType.

GetFieldValue(string, DataType): Gets the value of a named field, returned as the CLR type that corresponds to dataType.

GetFieldVarChar(string): Gets the value of a VARCHAR field as a string. Also returns values from string, clob, char, and geometry (as WKT) fields.

HasField(string): Determines whether a field with the specified name exists in this datum.

HasFieldValue(string): Determines whether a non-null value has been set for the field with the specified name.

HasValue(ISelectItem): Determines whether a non-null value has been set for the specified select item.

IsNull(string): Determines if the select item with the name passed in is null within this datum either as a result of not being in the datum or being in the datum and being set to null.

IsNull(ISelectItem): Determines if the select item is null within this datum either as a result of not being in the datum or being in the datum and being set to null.

SetField(int, object): Untyped setter method for setting a field value. Try to use the typed versions instead.

SetField(string, object): Untyped setter method for setting a field value. Try to use the typed versions instead.

SetFieldBlob(string, byte[]): Sets the value of a binary large object (BLOB) field.

SetFieldBoolean(string, bool?): Sets the value of a boolean field.

SetFieldByte(string, byte?): Sets the value of a byte field.

SetFieldChar(string, string): Sets the value of a fixed-length character (CHAR) field. The value must not exceed the column's declared size.

SetFieldClob(string, string): Sets the value of a character large object (CLOB) field.

SetFieldDate(string, DateOnly?): Sets the value of a date-only field.

SetFieldDateTime(string): Sets a date/time field to the current UTC date and time.

SetFieldDateTime(string, DateTime?): Sets the value of a date/time field.

SetFieldDecimal(string, decimal?): Sets the value of a decimal (exact numeric) field.

SetFieldDouble(string, double?): Sets the value of a double-precision floating-point field.

SetFieldFloat(string, float?): Sets the value of a single-precision floating-point field.

SetFieldGeography(string, Geometry): Sets the value of a geography (geodetic/spherical) field from a NetTopologySuite.Geometries.Geometry object. The geometry is automatically wrapped in a Geography container.

SetFieldGeography(string, Geography): Sets the value of a geography (geodetic/spherical) field from a Geography wrapper object.

SetFieldGeometry(string, Geometry): Sets the value of a geometry (planar spatial) field.

SetFieldGuid(string): Sets the value of a GUID field to a newly generated Guid.

SetFieldGuid(string, Guid?): Sets the value of a GUID field by storing the provided GUID as a varchar string.

SetFieldInteger(string, int?): Sets the value of a 32-bit integer field.

SetFieldInterval(string, TimeSpan?): Sets the value of a time interval field.

SetFieldLong(string, long?): Sets the value of a 64-bit integer (long) field.

SetFieldShort(string, short?): Sets the value of a 16-bit integer (short) field.

SetFieldTime(string, TimeOnly?): Sets the value of a time-only field.

SetFieldTimestamp(string, DateTimeOffset?): Sets the value of a timestamp (date/time with time zone offset) field.

SetFieldVarChar(string, string): Sets the value of a variable-length character (VARCHAR) field. The value must not exceed the column's declared size.

Table of Contents

Class Datum

Remarks

Examples

Properties

Methods