Evaluate computed fields: formulas and rollups

FE
13h ago
+10682-545

A computed field stores nothing: the database calculates its value each time it is read. #30518 added the computation property; this PR evaluates it, for two kinds. Server only; no UI. Creating a computed field is behind IS_COMPUTED_FIELDS_ENABLED (on in the dev seed).

  • Formula: an expression over the record's own fields, e.g. round(budget / totalPoints, 2).
  • Rollup: a count, sum, average, minimum or maximum over the records of a one-to-many relation, with an optional filter, e.g. open tasks of a project, or the earliest due date among them.

A computed field can be selected, filtered and sorted like a stored field, and it cannot be written. Filtered relations ("upcoming tasks") from #30499 are included in this branch.

Model

A field keeps its type, which says what shape its value has; computation says where the value comes from.

{ kind: 'FORMULA', expression: "concat(upper(name), ': ', if(openTaskCount > 0, 'open', 'idle'))" }
{ kind: 'ROLLUP', relationFieldName: 'tasks', operation: 'MIN', expression: 'dueAt', filter: "status != 'DONE'" }
  • One type axis, not new field types. A rollup returning a number stays NUMBER, so every reader (API schema, filters, sorting, display) works unchanged. Only write paths ask whether a field is computed.
  • One expression language for formulas, rollup expressions and rollup filters. It reads a composite sub-field as amount.amountMicros, a field of a to-one relation as project.budget, and other computed fields by name.
  • Fields are referenced by name, as in an API query, so a computation reads the same in every workspace and in an app manifest. Renaming a field rewrites the computed fields that read it.
  • Types: a formula or rollup field is NUMBER, TEXT, BOOLEAN, DATE or DATE_TIME.

Changes

  • Read path, in the ORM:
    • The table shape knows computed columns; the default projection and writes never include them.
    • When a query references one, the table is read through a derived table that keeps the table's alias and adds the computed column. SELECT, WHERE, ORDER BY, GROUP BY and cursors then reference it like a stored column, so no parser changed. Joins, including deduped to-many joins, and EXISTS filters read the same source.
    • A computed column that reads another one sits one level above it. What a column reads is tracked structurally (ComputedColumnSql.readComputedColumnNames), not found by scanning its SQL.
    • The SQL is built just before execution, per request. A rollup or a to-one read is a subquery built with the related object's own query builder, so its row-level permissions apply. Parameters are allocated from one context (ComputedColumnSqlContext) owned by the root query builder and shared with the subqueries it embeds.
    • WorkspaceRepository.prepareForExecution is the single preparation entry point: row-level permissions, read validation, then computed-column resolution. For a mutation whose filter needs an id subquery, that subquery gets the write row-level permissions and computed-column resolution only, as a filter on stored columns always did.
  • Permissions, one rule: a computed value is null as soon as it reads a field or an object its reader cannot read. The query does not fail. It applies the same way to a formula, a rollup's expression, a rollup's filter and a read through a to-one relation.
  • Expressions: parse → typed tree → SQL.
    • The parser (expr-eval-fork), the tree, the type checker and the function catalogue live in twenty-shared (utils/computed-field, constants/ComputedFieldExpressionFunctions.ts). The server only emits SQL from the typed tree (emit-computed-field-expression-sql.util.ts).
    • The type checker tracks the type of every operand and rejects mismatches (amount + name, a non-boolean condition…).
    • Text values are bound as parameters, never written into the SQL.
    • != is IS DISTINCT FROM, so a missing value is different from any value. A division by zero gives null.
    • today uses the UTC day. dateDiff, dateAdd, dateTrunc, and datePart include computed-field type checking and SQL emission; JS/Postgres parity tests cover the date operations. The standalone validation-rule evaluators, editor, and SDK support are in #30527, targeting main. daysSince is removed.
  • One description per kind: ComputedFieldKindDescription names a kind's source relation and its expression slots (which property holds an expression, whether it is evaluated on the record or on a related record, what it may return). Shape check, bindings, rename, cycle detection and type validation are generic over it; a kind adds only the rules slots cannot express.
  • Validation parses and type-checks; it no longer builds SQL:
    • the stored JSON has the shape of a formula or a rollup;
    • every expression type-checks, every field it reads exists, and its value fits: the field's type for a formula, a number for SUM and AVG, a boolean for a filter;
    • a rollup's relation is a stored one-to-many relation; COUNT takes no expression, the others need one;
    • a computed field cannot be unique, searchable or have a default value;
    • a field cannot read itself, directly or through other computed fields;
    • a stored field cannot become computed, or the other way around;
    • deleting a field is refused while a computed field still reads it.
  • Bindings: a computation stores the universal identifier of each field it reads. They are filled when the field is saved, including from an app manifest, and replace whatever a client sent.
  • Renames: a side effect on field update rewrites the source relation and every expression slot of the computed fields that read the renamed field, reusing the validation rules' expression rename.
  • Writes: a write never returns a computed column; when its response selects one, it is read right after by LoadComputedFieldsHelper, called by the write query runners and the record event publisher.
  • Shared with validation rules: the list of disabled parser operators and the parse memoizer. The least-recently-used helpers (readLruEntry, writeLruEntry, memoizeLeastRecentlyUsed) moved from the server to twenty-shared/utils/cache, so there is one implementation.
  • Feature flag: IS_COMPUTED_FIELDS_ENABLED gates creation only. Without it a new field with a computation is rejected; existing computed fields keep being read, renamed and edited. Front schemas and client SDK regenerated for the flag.
  • Docs: objects.mdx and the agent skills data-model reference.

Known limits

  • Deleting an object is refused while a computed field on another object reads it. The computed field has to be deleted first.
  • Multi-column types (currency, full name…) cannot be computed. Sum the micros into a NUMBER instead.
  • Performance: values are computed at read time, with no index. A filter or sort on a rollup runs its subquery for every candidate row.
  • REST selects every field by default, so a list request computes every computed field of the object.
  • Time zone: today is the UTC day, not the reader's.

Not covered by a test yet

  • Group-by and aggregates over a computed field.

Stack

PRWhat it doesBuilds on
#30518The computation property, no storage, write guardsmain
#30527Standalone date evaluators, validation rules, editor, and SDKmain
This PR 👈Formulas, rollups, filtered relations (including #30499), and computed date SQL support#30518; date helpers also ship independently in #30527

Formulas and rollups stay in one PR: they share the parser, the type checker, the SQL emitter and the permission rule, and a rollup is one more kind description over the same files.

Testing

  • Integration computed-field (32 tests, on custom objects):
    • rollups: count, count with a filter, sum, earliest date with a filter, and values following a change to a related record;
    • formulas: over stored and computed fields, text functions and conditions, a field read through a to-one relation;
    • querying: filter and sort by a computed field, filter by one that is not selected, computed fields of nested records, computed fields in the response of a write, an update filtered by a computed field, writes refused;
    • long names: nested to-one reads and rollups whose aliases exceed the Postgres identifier limit;
    • validation: each rule above, including values that do not fit their field, renamed fields and relations followed by their computed fields, and the feature flag off (rename and edit allowed, creation refused).
  • Integration computed-field-permissions (5 tests, as a member with a restricted role): full access; an unreadable field read by a formula and through a to-one relation; an unreadable field read by a rollup's expression and by a rollup's filter; an unreadable related object; a field hidden on a record by a row-level rule. Each returns null without failing the query.
  • Integration computed-field-manifest-sync (3 tests): a computed field created by an app manifest sync gets its bindings, follows a workspace rename, and gets its manifest name back.
  • Unit: in twenty-shared, the parser and the type checker (types, rejected syntax and rejected types) and the LRU helpers; on the server, SQL emission and parameters, bindings and rename, the shape check, the derived-table rendering and the query builder's computed columns.
  • Server typecheck and oxlint.

Date consolidation validation

The original date PR's 27 compiler/SQL/parity files are preserved unchanged here, alongside the reviewed shared date implementation from #30674 (now #30527). After combining them: 394 tests across 30 shared/server suites passed; scoped shared TypeScript checks, the shared build, formatting, and Oxlint passed. The database-backed parity integration suite was preserved but not rerun during this consolidation.