Published at: 2026-09-17

Lookup relationship (multi-select)

Overview

The Lookup Relationship (Multi-Select) field allows you to select multiple related object records simultaneously, forming a loose many-to-many relationship. It applies to scenarios where one record needs to reference multiple target records, such as a customer associated with multiple tags or an order linked to multiple products. Most configuration logic is consistent with the Lookup Relationship (single-select) field.

1. Field basics

The Lookup Relationship (Multi-Select) field allows multiple selections.
It supports forming a 1-to-many relationship between 2 objects, with the lookup field defined on the “many” side.
Lookup Relationship (Multi-Select) fields are not supported in the advanced mode of formula fields.

Most configuration logic for the Lookup Relationship (Multi-Select) field is consistent with the Lookup Relationship (single-select) field. The shared configuration details are listed below. For detailed information about the single-select version, see Lookup relationship.

1.1 Selectable data scope

This setting filters data when you fill in the lookup field on the create or edit page.

You can set the selectable data scope for the lookup relationship object: All or Based on conditions.
Condition-based filtering supports two forms: field-based and APL code-based.
After you set the data scope, the selectable related data must meet the filter conditions.
On the detail page of the lookup relationship object, when you create related object data, the system validates whether the data meets the filter conditions. Data that does not meet the conditions cannot be created.

1.1.1 Field-based filtering

When the two fields in a filter condition have different types, you cannot configure field equality (for example, a text field and a lookup relationship field).

Supported field types:

Text, numeric, single-select/multi-select/Boolean, Personnel/Personnel (Multi-Select), Department/Department (Multi-Select), Lookup Relationship/Lookup Relationship (Multi-Select), Country/Province/City/District, Location, Roll-Up Summary Field, filterable formula fields, and filterable reference fields

Unsupported field types:

Formula: Formula fields that do not support filtering cannot serve as lookup filter fields. (Check the prompt on the formula configuration page to determine whether a formula field is filterable. Generally, if a field is not filterable on the data list page, it is also not supported for lookup filtering.)
Reference Field: Reference fields that do not support filtering cannot serve as lookup filter fields. (Check whether the “Filterable” option is selected in the field configuration. Reference fields that reference certain field types do not support the “Filterable” option. See the tooltip for details.)
Component fields: Payment (Collection) component, Check-in component, Area location, Date range. These component fields function as a unit and require internal fields for filtering. For example, Country/Province/City/District — if internal fields are not selectable, filtering is not supported.
Business fields: Star rating, Video, Appointment time slot.
Other unsupported fields: Rich text, Collaborative rich text, Long text, Image, Attachment, External personnel, Related business data, Related business object, and so on.

1.1.2 Custom function-based filtering

Each filter condition supports only one custom function. The function must return a data set.
The function return value must not exceed 500 records. If it exceeds 500, the system returns only the first 500 records.

1.1.3 Filter condition use cases

Lookup relationship fields support filtering based on the lookup relationship field of the master object:

Scenario 1: After a customer places an order, the manufacturer ships products. The shipping details can only select products from the corresponding order. That is, adding order products to the shipping note details supports filtering by the corresponding order.
Scenario 2: When converting a quote to an order, the products added to the order must fall within the product scope of the quote details.

1.2 Data scope of the related object

This setting filters data in the related list page of the related object when you click the Associate button.

For example, if you create a lookup field Account on the Purchase Requisition object, this feature filters the Purchase Requisition data when you create a Account record.

Supported field types:

Text, numeric, single-select/multi-select/Boolean, Personnel/Personnel (Multi-Select), Department/Department (Multi-Select), Lookup Relationship/Lookup Relationship (Multi-Select), Country/Province/City/District, Location, Roll-Up Summary Field, filterable formula fields, and filterable reference fields

Unsupported field types:

Formula: Formula fields that do not support filtering cannot serve as lookup filter fields.
Reference Field: Reference fields that do not support filtering cannot serve as lookup filter fields.
Component fields: Payment (Collection) component, Check-in component, Area location, Date range.
Business fields: Star rating, Video, Appointment time slot.
Other unsupported fields: Rich text, Collaborative rich text, Long text, Image, Attachment, External personnel, Related business data, Related business object, and so on.

1.3 Default value

You can set a default value. For example, an order references a customer, and a payment references both the order and the customer (the order, customer, and payment form a triangular relationship). When you create a payment and select an order, you can automatically populate the account name on the payment with the account name from the order. To achieve this, set the default value of the account name field on the payment to the account name field from the order.

1.4 Triangular filtering

Scenario: Set a filter condition on the Lookup B field of Object A: B.C = A.C

1.4.1 Impact of triangular filter conditions on data operations

Configuration: Set a filter condition on the Lookup B field of Object A: B.C = A.C

Data entry during create/edit: You must fill in C first, then B.

Data relationship validation on the detail page: In the detail view of B, when you associate data from A, the system validates whether the C record associated with B and A is the same record.

Data relationship auto-fill on the detail page: In the detail view of B, when you create a new A record, the system auto-fills the Lookup B field (read-only). The Lookup C field has two scenarios:

If B’s Lookup C has a value, the system auto-fills the Lookup C field of the new A record (read-only).
If B’s Lookup C has no value, the Lookup C field of the new A record is also empty and is not read-only. After you reselect C, the system clears the Lookup B field, but it remains read-only (even if it is set to read-write, no matching data is available).

Platform differences:

Web: After you clear B, the field remains read-only.
Mobile: After you clear B, the field becomes read-write.
The read-only logic has been adjusted in later updates. Some fields are no longer forced to read-only. Refer to the current behavior.

1.4.2 Multi-level triangular filtering may cause layout required rules to fail

Configuration example:

The Opportunity Forecast field on the Stock Order object references the Opportunity object with a filter scope.
The Opportunity 2.0 field on the Stock Order object also references the Opportunity object with a filter scope.

In this case, the filter may not take effect.

Cause:

When you create a record from the “Opportunity Forecast” detail page, the system brings related field values (Opportunity Forecast, Opportunity 2.0) into the create page and sets them as read-only. Read-only fields do not respond to layout required rules.
Because the customer value is not carried over and the account field is required, selecting a customer triggers a lookup cascade that clears the carried-over value (Opportunity Forecast).

Solution:

Add a filter condition “Account Name = Stock Order.Account Name” to the Opportunity Forecast field on the Stock Order. This ensures that the customer is automatically carried over when you create a record from the “Opportunity Forecast” detail page.

1.5 Quadrangular filtering

Quadrangular filtering extends triangular filtering and involves filter relationships among four objects.

1.6 Pentagonal filtering

Configuration constraint: The primary attribute of E must be a text type. Auto Number is not supported.

1.7 Front-end constraints for lookup filter conditions

1.7.1 Function filter constraints

Function filtering refers to using custom functions when configuring filter conditions for lookup relationship fields.

When function filtering is configured, validation is not performed when you create data from the related list.
Function filtering applies only when you select data on the create/edit page.

1.7.2 Filtering issues when adding detail records from a lookup field

Common issue: On the create/edit page, you cannot select detail data through the detail object’s lookup relationship field, but you can select data using “Add a row.”

In the detail object table, you can fill in the lookup field for each row individually or use the batch add button to populate values.

If the lookup field on the detail object has filter conditions configured using another lookup condition on the detail object, the filtered data from the two approaches may differ:

For individual row entry, the prerequisite is that the other lookup field on the detail object must have a value. The filter checks whether Object C on the lookup target equals Object C on the detail object.
For batch add, because the detail records are newly added and have no existing detail data, the system can only filter records where Object C on the lookup target is empty.

1.8 Validation issues when saving lookup fields

When multiple OR groups exist and the value field belongs to triangular, quadrangular, pentagonal, function, master object, or current object filter conditions, the rule is skipped.
When only one group exists, the system removes triangular, quadrangular, pentagonal, function, master object, and current object conditions, and validates the remaining conditions.
On the master-detail create page, lookup relationship fields on the detail object are not validated against filter conditions when data is saved.
These limitations may cause the selected value of a lookup field to not comply with the filter conditions in some cases.

1.9 Multi-level filter and standard filter coexistence issues

Scenario 1: A filter condition group contains both multi-level and standard filters.

In this scenario, when you create data from the related list, the validation logic removes multi-level filters and validates only standard filter conditions. The same logic applies when saving data.

Scenario 2: Two filter condition groups: multi-level filter & standard filter

standard filter.

In this scenario, when you create or save data from the related list, the validation removes multi-level filter conditions, which is equivalent to no validation.

1.10 Related external data permission configuration

The “Related external data permission” option applies only to lookup fields whose related object is “Customer” or “Partner.”
Only one lookup relationship field per object can enable this option.
Detail objects cannot configure “Related external data permission.” If you encounter this error when modifying a detail object description, edit the related field to disable the option.
“Related external data permission” takes effect only during data creation. If the lookup field is filled in or modified after creation, this option no longer applies.

2. FAQ

2.1 What do “Current object field,” “Related object field,” and “Master object field” mean in filter configuration?

Consider the following object relationship: “Object B” is a detail object of “Object A,” and “Object B” references “Object E.”

Current object field: Represents Object B itself.
Related object field: Represents the fields on the object referenced by this lookup field — in this example, Object E.
Master object field: Represents the master object of the current object. This option appears only when the current object is a detail object — in this example, Object A.

2.2 Why is the lookup field unselectable after configuring it in a condition?

There are constraints when combining multiple filter conditions:

Each filter condition allows only one quadrangular/pentagonal filter branch.
Triangular/quadrangular/pentagonal filter conditions cannot coexist in the same filter group.
Triangular, quadrangular, and pentagonal filters cannot exist in different groups simultaneously.
Multiple triangular filters can exist in OR and AND relationships (in the same or different groups).

2.3 Why can I not configure “OR” conditions or add only one condition group?

To add “OR” conditions, you need to purchase the License → “Object list filter and scenario settings support OR” (0 RMB). After purchase, custom objects support this by default. If standard objects still do not support “OR” after purchasing the license, contact the corresponding module owner.

2.4 How to display content beyond the primary attribute when selecting data in a lookup field

The quick selection list displays: the primary attribute when display fields are not enabled on the object, or the display field values when display fields are enabled.

If the primary attribute of the related object is a code, and you want to see more specific content when quickly selecting related data, enable display fields on the related object.

How to enable display fields: Go to Object > Basic Information > Enable display field. You can configure a formula for the display field to show custom content. After configuration, wait for the calculation to complete. Before the calculation finishes, the quick selection list shows “–”.

2.5 Lookup field shows “–” and editing data indicates the relationship does not exist

If the data referenced by a lookup field is deleted, the field cannot retrieve the data name and displays “–”. Note that this “–” differs from the empty value “–”.

The “–” displayed after related data deletion is blue and is clickable. The field value is actually the related data ID. You can use a function to query data and retrieve this field value.
To process historical data, you can only use functions. The list page cannot filter this type of data.
Function processing approach: Use a function to retrieve the current data and obtain the related value (data ID), then use another function to query whether the related data still exists using the data ID.