Add filtered relations: a computed one-to-many relation
Merged
FE
17h ago+1736+1736+0123456789012345678901234567890123456789-293-293-012345678901234567890123456789
A filtered relation is a one-to-many relation field that shows some of the records of another one-to-many relation: a stored filter, order and limit. It is the third kind of computed field, after formulas and rollups (#30498). Example: Upcoming tasks on a project, its tasks that are not done and due today or later, soonest first, at most 3. Server only; no UI. Creating one is behind IS_COMPUTED_FIELDS_ENABLED.
{
name: 'upcomingTasks',
type: FieldMetadataType.RELATION,
computation: {
kind: 'FILTERED_RELATION',
relationFieldName: 'tasks',
filter: "status != 'DONE' and dueAt >= today",
orderBy: [{ expression: 'dueAt', direction: 'AscNullsLast' }],
limit: 3,
},
}
How to review
This branch also contains #30347 (nested filter / orderBy / first), merged in because filtered relations run on it. Until #30347 merges, the diff against #30498 shows both; this PR's own change is the filtered-relation code listed below.
Changes
- Model:
FILTERED_RELATIONjoins thecomputationunion. The field's type isRELATION(one-to-many) and it targets the same object as the relation it derives from.orderByis a list of{ expression, direction }: each sort is an expression in the computed-field language, evaluated on the related record. - One more kind description: the filtered relation is a
ComputedFieldKindDescription(source relationrelationFieldName; expression slotsfilterand eachorderBy[].expression, evaluated on the related record). Shape check, bindings, rename, cycle detection and type validation come from the generic code of #30498; the description adds only the relation, direction and limit rules. A slot can now be a list (listItemProperty). - No inverse field: the database allows one relation per inverse field, so a filtered relation has none of its own. It is loaded through the relation named by
relationFieldName, under its own name. ThehasInverseRelationFieldpredicate (twenty-shared) tells a relation with an inverse field from one without. - Creation: a
RELATIONcreate input with aFILTERED_RELATIONcomputation creates that single field; no relation pair, no column, no foreign key. - Read path:
- The stored filter, order and limit define the set of records first, per parent record.
whereInFilteredRelationon the select query builder restricts the nested query to that set (a lateral subquery per parent when there is a limit), andorderByFilteredRelationapplies the stored order, with the id as tiebreaker. They replace theexpressionFilternested argument. - A query's own
filter,orderByandfirst(the nested arguments of #30347) apply inside that set: with a limit of 3, a query filter narrows the three stored records and never picks others. Without an order of its own, a query gets the stored order. totalCountand the nested aggregates count inside the stored set.- The stored filter and sort expressions are compiled by the query builder with the same pipeline as a computed column, and bind their parameters in the same context.
- The permission rule of #30498 applies: a filter that reads a field or object its reader cannot read shows no record, a sort it cannot read is skipped, and the relation is empty for a reader who cannot read the relation it derives from.
- The stored filter, order and limit define the set of records first, per parent record.
- Relation machinery that assumes an inverse field:
- the relation validator skips a computed relation, which is validated through its computation;
- the manifest converters and the places that look up a relation's counterpart on field update, field delete and object delete ask
hasInverseRelationFieldinstead of testing the computation kind; - the table shape never joins a filtered relation, and
hasComputedColumnsays which computed fields have a column.
- Validation: the field is a one-to-many relation without an inverse field, to the same object as its source relation; the limit is between 1 and 60; each sort direction is a known one; the filter type-checks to a boolean and each sort expression type-checks on the related object. Renaming the source relation or a field the filter or a sort reads rewrites the computation; deleting one is refused.
- Docs:
objects.mdxand the agent skills data-model reference describe the sort expressions and the limit.
Known limits
- Filtering records by a filtered relation is not available, as for any one-to-many relation in the API today.
- Deleting the related object is refused while a filtered relation targets it; the filtered relation has to be deleted first.
Not covered by a test yet
- Creating a filtered relation through an app manifest sync.
Found while testing, not fixed here
- A nested relation selected with arguments returns a stray
"__arguments": nullkey in its connection, e.g.tasks(first: 1) { totalCount }gives{ "__arguments": null, "totalCount": 3 }. It reproduces on a plain relation, so it belongs to #30347.
Stack
| PR | What it does | Builds on |
|---|---|---|
| #30518 | The computation property, no storage, write guards | main |
| #30498 | Formulas and rollups | #30518 |
| This PR 👈 | Filtered relations | #30498 and #30347 |
Testing
- Integration
computed-field(39 tests), with seven for filtered relations:- the filtered, sorted and limited records per parent;
- a query filter applied inside the stored limit, never picking other records;
- the stored order kept with a limit, and a query order applied inside it;
- deleting a field read by a sort expression is refused; an unknown sort field or direction is rejected, and a renamed sort field is followed;
- the field is listed by the metadata API without an inverse relation, and the source relation is left untouched.
- Teardown deletes both objects, which covers deleting an object that has a filtered relation.
- Integration
computed-field-permissions(6 tests), with one for a filtered relation: it is empty for a member who cannot read its source relation or what its filter reads. - Integration
nested-relation-*pass with it. - Unit: the select query builder's filtered relation SQL, the
hasInverseRelationFieldpredicate, and the bindings, rename and shape check of the new kind. - Server typecheck and oxlint.