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

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");

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

Fields

_valueFields

Properties

FieldCount

Fields

this[int]

this[string]

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.

GetField(ISelectItem)

GetFieldBlob(string)

GetFieldBoolean(string)

GetFieldByte(string)

GetFieldChar(string)

GetFieldClob(string)

GetFieldDate(string)

GetFieldDateTime(string)

GetFieldDecimal(string)

GetFieldDouble(string)

GetFieldFloat(string)

GetFieldGeography(string)

GetFieldGeography<T>(string)

GetFieldGeometry(string)

GetFieldGeometry<T>(string)

GetFieldGuid(string)

GetFieldInteger(string)

GetFieldLong(string)

GetFieldShort(string)

GetFieldTimestamp(string)

GetFieldValue(int, DataType)

GetFieldValue(string, DataType)

GetFieldVarChar(string)

GetSelectItem(int)

GetSelectItem(string)

HasField(string)

HasFieldValue(string)

HasSelectItem(string)

HasValue(ISelectItem)

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.