Add filtered relations: a computed one-to-many relation

Merged
FE
17h ago
+1736-293

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_RELATION joins the computation union. The field's type is RELATION (one-to-many) and it targets the same object as the relation it derives from. orderBy is 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 relation relationFieldName; expression slots filter and each orderBy[].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. The hasInverseRelationField predicate (twenty-shared) tells a relation with an inverse field from one without.
  • Creation: a RELATION create input with a FILTERED_RELATION computation 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. whereInFilteredRelation on the select query builder restricts the nested query to that set (a lateral subquery per parent when there is a limit), and orderByFilteredRelation applies the stored order, with the id as tiebreaker. They replace the expressionFilter nested argument.
    • A query's own filter, orderBy and first (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.
    • totalCount and 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.
  • 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 hasInverseRelationField instead of testing the computation kind;
    • the table shape never joins a filtered relation, and hasComputedColumn says 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.mdx and 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": null key 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

PRWhat it doesBuilds on
#30518The computation property, no storage, write guardsmain
#30498Formulas 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 hasInverseRelationField predicate, and the bindings, rename and shape check of the new kind.
  • Server typecheck and oxlint.