Virtual Entities

A virtual entity is an entity that is not persisted to the database. It exists only at runtime and is populated by business logic. Virtual entities are useful for computed views, aggregations, and read-only result sets.

Defining a Virtual Entity

Add [Virtual] at the class level alongside [ApiEntity]:

[Virtual]
[ApiEntity]
public partial class ProductAvailability
{
    [Property<DataTypes.DateOnly>("Ship date")]
    public partial DateOnly? ShipDateToFilter { get; set; }

    [Property<DataTypes.Integer>("Popularity Score")]
    public partial int PopularityScore { get; set; }
}

//TODO: Not sure about this. Also see last section. Note: Virtual entities do not inherit from EntityBase since they have no database table, primary key, or row versioning.

Virtual Reference Properties

Virtual entities use [VirtualReferenceProperty] to reference real entities without creating foreign key columns:

[Virtual]
[ApiEntity]
public partial class ProductAvailability
{
    [VirtualReferenceProperty("Breed")]
    public partial Breed Breed { get; set; }

    [Property<Guid>("Breed guid")]
    public partial Guid BreedGuid { get; set; }

    [VirtualReferenceProperty("Earliest chick type count")]
    public partial ChickTypeCount EarliestChickTypeCount { get; set; }

    [VirtualReferenceProperty("Matched Manufacturing orders")]
    public partial List<ManufacturingOrder> MatchedManufacturingOrders { get; set; }
}

When to Use Virtual Entities

Use Case	Example
Aggregation views	Availability summaries, dashboards
Computed result sets	Combined data from multiple entities
Read-only projections	Flattened views for reports
Filter/search endpoints	Parameter-driven query results

Key Differences from Regular Entities

Aspect	Regular Entity	Virtual Entity
Database table	Yes	No
EntityBase	Required	Not used
Guid primary key	Auto-generated	Not present
RowVersion	Auto-tracked	Not present
CRUD operations	Full create/read/update/delete	Read only
Relationships	[ReferenceProperty] with FK	[VirtualReferenceProperty] only
Business logic	Events system	Custom logic populates the entity