Content / Virtual entities: composed API responses

Virtual entity purpose

A virtual entity reads existing persistent data and composes the response you need. Select ordinary fields, related data and collections. It creates neither its own table/storage migrations nor write operations.

For example, a website can request PageBlock, related Page and BlockItem collection in one projection request rather than querying each separately. Response limits/pagination still apply; one response cannot return unlimited records.

Creation and field selection

1. Create an entity with Kind virtual.
2. Select a persistent Source entity, such as PageBlock.
3. Enable Read operations: List and/or Get by ID.
4. Select source scalar fields.
5. For declared relationships, enable Include relation and select Target fields.
6. Save; edit later with Configure source and fields / Save fields.

Sources must be persistent, not another projection. Supported one-level relationships are available; arbitrary-depth expand is not. Include only fields needed by the client.

Output name and Fields

Output name controls API naming. For example, return bodyMarkdown as body without renaming the database column. Lowercase-starting lowerCamelCase/snake_case are allowed; empty retains the original name.

Fields shows selected types and capabilities. Related entities have badges and Expand fields, revealing nested rows. Clicking a row opens settings. Inspect the response shape directly in this table.

List behavior at different levels

Enable Searchable, Filterable, Sortable on supported selected scalars. Projection settings are independent of persistent sources.

Sorting by belongsTo Page changes root-block order without creating a separate page list. Sorting items changes each collection, not block order.

Collection limits and order

For hasMany, set Default limit, Maximum limit, Order field and Direction. Limits must be positive integers; Maximum must be at least Default. Order field accepts suitable selected target scalars, not image/gallery.

For items, select position, Ascending, Default limit 20 and Maximum limit 100. The server uses this default independently of Sortable; enable Sortable to let clients override order in requests.

Collection responses contain items, total, limit, offset. Compare total with returned count and account for subsequent pages. Child search/filter/sort parameters belong to a specific collection and do not replace root-list parameters.

Publication and visibility

Open Access, enable needed external List/Get and separate server conditions for PageBlock, Page and items. For example: visible block, published page, visible item with nonempty title. Child rules restrict collection contents only: an empty collection does not exclude its parent.

Persistent access does not automatically carry into virtual. Check projection rules and every selected field before Anonymous.

Administrator view

Projections are read-only in the admin. Related data is readable; collections show counts and pages. Administrative media reads require source persistent permissions. External images are variant URLs; see Images.

Changing Source entity with confirmation clears selected fields in the draft. Select new-source fields before saving. Finish/Save fields saves the model; Generate updates code.

See CLI virtual entities.