Published at: 2025-10-30

Lookup Relationship Field

1. Field Basics

Lookup (multi-select) fields allow selecting multiple records.
You can establish a one-to-many relationship between two objects by defining a Lookup field on the “many” side.

1.1 Selectable Data Scope

Used to filter candidate records when filling a lookup field on create/edit pages.

You can set the selectable range for a Lookup field to: All or By condition.

Condition-based filtering supports two forms: field-based filtering and custom APL function filtering.

After you set a data scope, selected records must meet the filter conditions.
When creating related records from the detail page of the lookup target, the system validates whether the new record meets the filter. If it does not, the related record cannot be created.

1.1.1 Field-based Filtering

If two fields have incompatible types you cannot configure an equality comparison between them (for example, a Text field vs. a Lookup field).

Supported field types: - Text, Number, Single-select / Multi-select / Boolean, User / Multi-user, Dept. / Multi-dept., Lookup / Lookup (multi-select), Country/Province/City/District, Location, Roll-up/Stat fields, Calculated fields that are filterable, Reference fields that are filterable

Unsupported field types: - Calculated fields: Calculated fields that are not filterable cannot be used in lookup filters. (Check the formula configuration page for whether a calculated field supports filtering; typically list pages can’t filter such fields, and lookup filtering also doesn’t support them.) - Reference fields: Reference fields that are not marked as “filterable” cannot be used in lookup filters. (Whether a reference field supports filtering depends on the field configuration’s “filterable” option; some reference field types cannot be marked filterable—see tooltip for details.) - Component fields: Payment (Collection) component, Check-in component, Region location, Date range—these are composite components. You must use internal subfields (for example, Country/Province/City/District). If the internal subfield is not available, the component is unsupported. - Business fields: Rating, Videos, Appointment time slot. - Other unsupported types: Rich text, Collaborative rich text, Long text, Images, Attachments, External contacts, Related business data, Related business objects, etc.

1.1.2 Custom-function (APL) Filtering

Each condition group can include only one custom function. The function must return a set (collection) of records.
The function return set must not exceed 500 records; if it does, the system returns the first 500.

1.1.3 Use Cases for Filter Conditions

Lookup fields support using a Lookup field on the Primary Object as a filter condition.

Scenario 1: After a customer places an order and the manufacturer ships, shipping details must only select products from the corresponding order. Example: On a Shipping Order detail, when adding Order Products to Shipping Order Line Items, the selection can be filtered by the related Order.
Scenario 2: When converting a Quotation to an Order, adding Products to the Order must be limited to Products listed on the Quotation lines.

1.2 Target Object Data Scope

Used on the related list of the target (lookup) object when clicking the Link/Add Related button to filter candidate records.

Example: If a Purchase Requisition contains a Lookup field to Account, this setting filters which Purchase Requisition records appear when creating/linking an Account.

Unsupported field types: - Calculated fields: non-filterable calculated fields cannot be used for related-object filtering. - Reference fields: non-filterable reference fields cannot be used. - Component fields: Payment (Collection), Check-in, Region location, Date range—these require internal subfields to filter; if internal subfields are unavailable, they are unsupported. - Business fields: Rating, Videos, Appointment time slot. - Other unsupported types: Rich text, Collaborative rich text, Long text, Images, Attachments, External contacts, Related business data, Related business objects, etc.

1.3 Default Values

You can set default values for Lookup fields. Example: Orders link to Accounts, and Payment Collections link to Orders and Accounts (forming a triangular relationship). When creating a new Payment Collection and selecting an Order, you may want to default the Payment Collection’s Account field from the Order’s Account. Configure the Payment Collection’s Account default to use the Order’s Account field value.

1.4 What is Triangle Filtering (3-way filter) and How to Use It

Scenario: On object A’s Lookup to B, you set a filter B.C = A.C.

1.4.1 Interaction and Data-entry Effects

Configuration: On A’s Lookup to B set filter B.C = A.C Data entry on Create/Edit: Fill field C first, then fill B.

Detail-page association validation: When linking an A record from B’s detail page, the system validates that the C associated on B and the C on A refer to the same record.

Detail-page association auto-fill behavior: When creating A from B’s detail page, the system auto-fills the Lookup to B and sets it read-only. Auto-fill behavior for the associated C depends: - If B’s associated C has a value, the new A’s C is auto-filled and read-only. - If B’s associated C is empty, the new A’s C is empty and editable. If the user selects a C, the system clears the association to B; the B lookup remains read-only (even if selection is possible, an appropriate record may not be available).

Web: After clearing B (middle record), the field remains read-only.
Mobile: After clearing B, the field becomes editable.
Read-only behavior has been adjusted over time; some fields may no longer be strictly read-only—treat the current behavior as authoritative.

1.4.2 Multi-level Triangle Filters Can Break Layout-required Field Enforcement

Configuration example: - On Stock Preparation object, the field Opportunity Forecast is a Lookup to Opportunity, with a filter as shown below.

On Stock Preparation, the field Opportunity 2.0 is a Lookup to Opportunity with another filter:

Result: The expected filter may not take effect.

Cause: 1) When creating a record from an Opportunity Forecast detail, the system populates related fields (Opportunity Forecast, Opportunity 2.0) into the new record and sets them read-only. Read-only fields do not respond to layout-level required rules. 2) The Account (Customer) is required but not populated. When the user selects Account it triggers lookup cascading that clears pre-populated values (Opportunity Forecast).

Solution: - Adjust user configuration: add an extra filter on the Opportunity Forecast field such that Account Name = Stock Preparation.Account Name. This ensures that when creating from Opportunity Forecast details the Account is automatically populated.

1.5 What is Quadrilateral Filtering (4-way) and How to Use It

1.6 What is Pentagonal Filtering (5-way) and How to Use It

Configuration restriction: The primary attribute of object E must be Text type; auto-increment Codes are not supported.

1.7 Front-end Limitations for Lookup Filter Conditions

1.7.1 Limitations for Function-based Filtering

Function-based filtering uses a custom function in the lookup filter configuration.

If you configure a function filter, the system cannot validate the condition when creating a record from a related list (see image).

Function filters only apply on create/edit pages and take effect when selecting records.

1.7.2 Filtering When Adding Sub-object Rows via Lookup

Common issue: On a create/edit page, you cannot find records when adding a Lookup from the Sub-object inline table, but you can find records when using “Add a row” and manually filling fields.

A Sub-object’s table can accept lookups per row or via a bulk “Add rows” button.

If the lookup on the Sub-object has a filter that references another Lookup on the Sub-object, the filtered results can differ between per-row entry and bulk-add behavior.

Filter example:

When filling the lookup on a single row, the prerequisite is that the other Lookup on this row has a value. The filter will compare Object C on the related object to the Sub-object’s Object C for that row.

When bulk-adding rows there is no existing Sub-object row context, so the system can only filter related objects where Object C is empty.

1.8 Validation Issues When Saving Lookup Fields

When multiple condition groups or relationship types exist, and some filter conditions rely on triangle, quadrilateral, pentagonal, function-based, Primary Object, or Current Object filtering, those conditions may be skipped during validation. - If only a single condition group exists, the system removes triangle/quadrilateral/pentagonal/function/Primary Object/Current Object conditions and validates remaining simple conditions. - On Parent-Child (Primary Object/Sub-object) create pages, Sub-object lookup fields are not validated against their filters when saving. These limitations can cause selected Lookup values to bypass filter conditions in some cases.

1.9 Why Mixed Multi-level Filters and Simple Filters Can Fail

Example symptom: 1) Single condition group that combines multi-level filtering and simple filtering. In this case, when creating from a related list the system strips multi-level filter conditions and only validates the simple filter conditions. The same applies to save-time validation.

2) Two condition groups: (multi-level & simple) | (simple) In this case the system removes multi-level filter conditions during related-list create and save-time validation; effectively these conditions are not validated.

1.8 External Data Linking Permission Configuration

The “External Data Link Permission” option applies only to Lookup fields whose target object is Account or Partner.
Only one Lookup field per object may enable this option.
Sub-objects cannot configure “External Data Link Permission.” If you see an error when editing a Sub-object descriptor, open the related field and disable this option.
“External Data Link Permission” only takes effect during record creation. If the Lookup is set after create or is edited later, this permission does not apply.

2. Common Questions

Given object relationships: Object B is a Sub-object of Object A, and Object B has a Lookup to Object E.

Fields under This Object: refers to fields on object B itself.

Fields under Related Object: refers to fields on the object that the Lookup connects to (in this example, object E).

Fields under Primary Object: refers to the Primary Object of the current object; this menu appears only when the current object is a Sub-object. In this example, it refers to object A.

2.2 Why does a Lookup stop returning results after configuring a certain condition?

When combining multiple filter conditions, the UI enforces these constraints: 1) Each filter group may contain at most one quadrilateral/pentagonal branch. 2) Triangle/quadrilateral/pentagonal filters cannot coexist in the same filter group. 3) Triangle filters cannot be used together with quadrilateral or pentagonal filters in different groups. 4) Multiple triangle filters can coexist across OR or AND relationships (in same or different groups).

2.3 Why can’t I add an OR condition (only one condition group allowed)?

To add OR condition support you must purchase the License feature: Object List Filtering and Scene Settings support [OR] (free license). After purchase custom objects support OR by default. If you still cannot add OR for prebuilt objects after purchasing, contact the module owner.

2.4 Displaying more than the Primary Attribute in Quick-select for Lookup fields

Quick-select list content: - If the object has not enabled Display Fields, the quick-select shows the Primary Attribute. - If Display Fields are enabled, quick-select shows the Display Field values.

If the related object’s Primary Attribute is a Code and you want more descriptive quick-select results, enable Display Fields on that object.

How to enable: Object -> Basic Info -> Enable Display Fields. Display Fields can be formulas to present custom content; after configuration, wait for calculation to complete. While calculation runs, quick-select will show “–”.

If the related record has been deleted, the lookup will display “–”. Note: this “–” differs from an empty value.

Deleted-related-record “–” is blue and clickable. The field’s stored value is the related record ID; you can use a function to query the record by ID.
To fix historical data you must use functions; list pages cannot filter these orphaned relations.

Function-based remediation approach: - Use a function to fetch the current record and obtain the stored related ID. - Use a function to query whether the related record exists by that ID, and then handle or update accordingly.

Submit Feedback

Digital Field

Country/Province/City/District