Published at: 2026-09-17
Reference field
Overview
The Reference Field retrieves field values from the “one” side of a one-to-many relationship across objects and dynamically displays them on the “many” side. It enables automatic display of related data. Typical use cases include displaying product prices on order details or referencing master record information on child records. Data is maintained as a dynamic link that follows changes to the source object in real time.
Specifications
| Property | Description |
|---|---|
| Use cases | Display product price on order details |
| Per-object limit | Up to 20 (expandable via resource pack) |
| Data synchronization | Dynamic link; follows source object changes in real time |
Key considerations
Reference field vs default value
A Reference Field is a dynamic link. Its data always follows changes to the source object field and synchronizes in real time. In contrast, a default value loads only once during record creation. If the source value changes afterward, the default value does not update.
Reference field calculation timeliness
- Non-filterable reference fields: Calculated and rendered in real time in memory when a user opens a page or queries data. The database does not persist this value.
- Filterable reference fields: Because a database index is required for querying, the value is calculated asynchronously in the back-end queue and written to the database after data is saved. Some synchronization delay exists.
[!WARNING] Reference field filter shows “value exists but cannot be found” issue: You can see the reference field value on the list page, but filtering returns no results. This occurs because the displayed value is calculated and rendered in real time when the page loads, while filtering queries the physical database column. If the back-end calculation queue has not yet written the latest value to the physical column, filtering fails. Wait for the calculation queue to finish after bulk operations.
Usage limitations and disabled-state rules
- Reference fields cannot reference formula fields, roll-up summary fields, or other reference fields. To achieve cross-object references, use the “Advanced mode” of formula fields for nesting.
- Reference fields cannot be used as operands in formula fields, roll-up summary fields, or default value formulas.
- Reference fields do not trigger front-end UI events.
- If a reference field references a
Lookup Relationship,Department,Personnel, orImagefield, the back-end Filterable option is forced to “No” and the field cannot serve as a list page filter condition.
