Generic data access is implemented by defining high-level objects as Delphi classes descending from TOrm. These classes serve multiple purposes:

• Database persistence: CRUD operations (SELECT/INSERT/UPDATE/DELETE) without writing SQL
• RESTful resources: Business logic objects accessible via REST/JSON
• UI integration: Automatic form generation, grid binding, and reporting

5.1. TOrm Field Definition

All ORM functionality relies on the TOrm class (defined in mormot.orm.core). This abstract class provides built-in methods for generic ORM processing.

5.1.1. Primary Key

TOrm defines a primary key field as ID: TID (where TID = type Int64):

type
  TID = type Int64;

  TOrm = class(TObject)
    // ...
    property ID: TID read GetID write fID;
  end;

The ORM relies on Int64 primary keys, matching SQLite3's RowID. While you might prefer TEXT or GUID primary keys in traditional RDBMS design, integer keys are more efficient for ORM internals. You can always define secondary unique keys using stored AS_UNIQUE.

5.1.2. Defining a Table

All published properties of TOrm descendants are automatically mapped to database columns:

uses
  mormot.core.base,
  mormot.orm.core;

type
  /// Enumeration for gender
  TSex = (sFemale, sMale);

  /// Table for Baby records
  TOrmBaby = class(TOrm)
  private
    fName: RawUtf8;
    fAddress: RawUtf8;
    fBirthDate: TDateTime;
    fSex: TSex;
  published
    property Name: RawUtf8 read fName write fName;
    property Address: RawUtf8 read fAddress write fAddress;
    property BirthDate: TDateTime read fBirthDate write fBirthDate;
    property Sex: TSex read fSex write fSex;
  end;

By adding TOrmBaby to a TOrmModel, the corresponding Baby table is automatically created. No SQL required.

5.1.3. Supported Property Types

5.1.4. Property Attributes

Use special attributes in property declarations:

type
  TOrmDiaper = class(TOrm)
  private
    fSerialNumber: RawUtf8;
    fModel: TOrmDiaperModel;
    fBaby: TOrmBaby;
  published
    property SerialNumber: RawUtf8
      index 30                    // Max 30 chars for external DB
      read fSerialNumber write fSerialNumber
      stored AS_UNIQUE;           // Creates unique index
    property Model: TOrmDiaperModel read fModel write fModel;
    property Baby: TOrmBaby read fBaby write fBaby;
  end;

• stored AS_UNIQUE: Creates a unique database index
• index N: Maximum character length for external databases
• index N (dynamic arrays): Used for TOrm.DynArray(N) wrapper access

5.2. Text Fields

The preferred type for text storage is RawUtf8. This ensures:

• Consistent UTF-8 encoding across all database engines
• No conversion overhead during JSON serialization
• Compatibility with all Delphi versions

// Business layer: Use RawUtf8
property CustomerName: RawUtf8 read fCustomerName write fCustomerName;

// UI layer: Convert for display
var
  displayName: string;
begin
  displayName := Utf8ToString(Customer.CustomerName);
  Edit1.Text := displayName;
end;

Domain-Driven Tip: Using RawUtf8 in your domain layer prevents accidental coupling between business logic and presentation.

5.3. Date and Time Fields

5.3.1. TDateTime / TDateTimeMS

Stored as ISO 8601 text in the database:

property CreatedAt: TDateTime read fCreatedAt write fCreatedAt;
property PreciseTime: TDateTimeMS read fPreciseTime write fPreciseTime;  // With milliseconds

5.3.2. TTimeLog / TModTime / TCreateTime

Stored as INTEGER for fast comparison:

property LastModified: TModTime read fLastModified write fLastModified;  // Auto-updated
property Created: TCreateTime read fCreated write fCreated;              // Auto-set once
property Timestamp: TTimeLog read fTimestamp write fTimestamp;           // Manual

TModTime and TCreateTime are automatically updated by the server:

• TCreateTime: Set when the record is first inserted
• TModTime: Updated on every modification

5.3.3. TUnixTime / TUnixMSTime

For interoperability with JavaScript/C#/Java:

property UnixTs: TUnixTime read fUnixTs write fUnixTs;        // Seconds
property UnixMsTs: TUnixMSTime read fUnixMsTs write fUnixMsTs; // Milliseconds

5.4. TOrm Foreign Key Fields

5.4.1. TOrm Published Properties (NOT Instances)

Critical: TOrm published properties are NOT class instances. They store pointer(RowID):

type
  TOrmOrder = class(TOrm)
  published
    property Customer: TOrmCustomer read fCustomer write fCustomer;  // Stores ID, not instance!
  end;

// WRONG - will cause Access Violation:
WriteLn(Order.Customer.Name);  // AV! Customer is not an instance

// CORRECT - retrieve separately:
var
  cust: TOrmCustomer;
begin
  cust := TOrmCustomer.Create(Client, Order.Customer);  // Load by ID
  try
    WriteLn(cust.Name);
  finally
    cust.Free;
  end;
end;

5.4.2. Setting Foreign Keys

var
  Order: TOrmOrder;
  Customer: TOrmCustomer;
begin
  Customer := TOrmCustomer.Create;
  Order := TOrmOrder.Create;
  try
    Customer.Name := 'ACME Corp';
    Client.Add(Customer, True);  // Customer.ID is now set

    Order.Customer := Customer.AsTOrm;  // Use AsTOrm for cross-platform
    // or: Order.Customer := pointer(Customer.ID);  // 32-bit only
    Client.Add(Order, True);
  finally
    Order.Free;
    Customer.Free;
  end;
end;

5.4.3. CreateJoined for Automatic Loading

Use CreateJoined to auto-instantiate and load all TOrm properties:

var
  Order: TOrmOrder;
begin
  Order := TOrmOrder.CreateJoined(Client, OrderID);
  try
    // Now Order.Customer is a real instance, loaded via JOIN
    WriteLn(Order.Customer.Name);  // Safe!
  finally
    Order.Free;  // Also frees Order.Customer
  end;
end;

5.4.4. Deletion Tracking

The ORM automatically handles foreign key integrity (emulated, not via SQL constraints):

type
  TOrmCustomerID = type TID;              // Reset to 0 on delete
  TOrmCustomerToBeDeletedID = type TID;   // Cascade delete

  TOrmOrder = class(TOrm)
  published
    property Customer: TOrmCustomerID read fCustomer write fCustomer;
    property OwnerCustomer: TOrmCustomerToBeDeletedID read fOwner write fOwner;
  end;

5.5. TRecordReference: Cross-Table References

TRecordReference stores a reference to any table in the model:

type
  TOrmAuditLog = class(TOrm)
  published
    property RelatedRecord: TRecordReference read fRelated write fRelated;
  end;

// Usage
var
  Log: TOrmAuditLog;
  Ref: RecordRef;  // Helper record
begin
  // Store reference to any record
  Log.RelatedRecord := RecordReference(TOrmCustomer, CustomerID);

  // Retrieve via helper
  Ref.Value := Log.RelatedRecord;
  WriteLn('Table: ', Ref.Table(Model).SqlTableName);
  WriteLn('ID: ', Ref.ID);

  // Load the referenced record directly
  Rec := Client.Retrieve(Log.RelatedRecord);
end;

Warning: TRecordReference encodes table index in high bits. Never change table order in TOrmModel after deployment.

5.6. Variant Fields and TDocVariant

Variant fields are stored as JSON TEXT:

type
  TOrmDocument = class(TOrm)
  published
    property Data: Variant read fData write fData;
  end;

// Usage - schema-less storage
var
  Doc: TOrmDocument;
begin
  Doc := TOrmDocument.Create;
  Doc.Data := _ObjFast(['name', 'John', 'tags', _Arr(['admin', 'user'])]);
  Client.Add(Doc, True);

  // Later retrieval
  Doc := TOrmDocument.Create(Client, DocID);
  WriteLn(Doc.Data.name);        // 'John'
  WriteLn(Doc.Data.tags._Count); // 2
end;

For MongoDB ODM, variants are stored as native BSON documents with full query support.

5.7. Dynamic Array Fields

Dynamic arrays are stored as BLOB in binary format:

type
  TIntegerArray = array of Integer;

  TOrmWithArray = class(TOrm)
  private
    fScores: TIntegerArray;
  published
    property Scores: TIntegerArray index 1 read fScores write fScores;
  end;

Access via TDynArray wrapper:

var
  Rec: TOrmWithArray;
  DA: TDynArray;
begin
  DA := Rec.DynArray(1);  // Get wrapper for Scores
  DA.Add(100);
  DA.Add(200);
end;