Reference (cross-entity) field

A polymorphic link to records across different entities. Unlike a Relation field (which always points to the same target entity), a Reference can point to different entity types per record. Stored as JSON — an array of {entity, uuid} tuples.

When to use Reference vs Relation

• Relation is for structured links where you always know the target entity at design time (e.g. "Contact belongs to Company").
• Reference is for polymorphic links where the target entity varies at runtime (e.g. "this file is Attached to a Contact OR a Project OR a Ticket").

Configuration

• Allowed entities: which entity slugs can be referenced. If empty, all entities are allowed.
• Cardinality: one or many.
• Required: no (default) or yes.

Form rendering

An entity-picker that first asks "which entity type?" then presents the usual record search for that entity. For many cardinality, you can add references to multiple entity types in the same field.

List rendering

[EntityType] RecordLabel — clickable link to the target record. For many, a badge "+N".

EQL operators supported

is null, is not null only. Deep-filtering across references is not supported in EQL; use the REST API with explicit JOIN queries for cross-entity analysis.