Add aggregate columns to table views

FE
14h ago
+5525-417

An aggregate column shows, per row, an aggregate over the records of a one-to-many relation: a count, or the sum, average, min or max of a field of the related records. Examples: Companies → People › Count, Opportunities › Sum of Amount. It is display-only (no sort, filter or footer total) and needs no new query path: the API already returns nested connection aggregates per parent. Behind IS_LOOKUP_COLUMNS_ENABLED, like lookup columns (#30439).

Anything with a business definition (filtered aggregates, rollups you can sort or filter by, formulas) is meant for the data model later; this column stays a view-level path.

Changes

Server

  • viewField.relationAggregateOperation: nullable AggregateOperations, a plain enum column. Fast instance command 2.59.0_AddViewFieldRelationAggregateOperationFastInstanceCommand_1794783282953. It is unrelated to aggregateOperation, which stays the footer total.
  • Validation, in the existing relation-target validator:
    • only on a non-canonical view field of a ONE_TO_MANY relation;
    • COUNT takes no target;
    • SUM, AVG, MIN, MAX need a target that belongs to the related object, is active, is not a relation, and supports the operation. Supported operations come from getAvailableAggregationsFromObjectFields, the source of the nested aggregates the API returns;
    • other operations are rejected;
    • a target on a one-to-many without an operation is still rejected, so lookups stay many-to-one;
    • on a column owned by an application, only that application can change the operation, as for the relation target in #30472: neither is overridable, so a workspace change would be undone by the application's next sync.
  • Plumbing mirrors relationTargetFieldMetadataId: DTO and inputs, flat entity configuration, manifest (relationAggregateOperation, documented in views.mdx), every place that builds a view field, twenty-cli pull enum bindings. Client SDK and front metadata schema regenerated.
  • Fix on main: a nested connection's totalCount fell back to the number of fetched records (capped at 60), because the per-parent aggregate values were read without the parent id. It now reads the parent's entry, the same one-line fix as in #30347.

Front

  • Picking:
    • The header menu of a one-to-many relation column has Add aggregate column. It opens Count, then the related object's number, currency, rating and date fields; a field opens its operations (Min, Max, Average, Sum; Earliest / Latest for dates), in the footer's order.
    • In the + menu, one-to-many relations open the same pages, with the relation itself first when its column is hidden.
    • Lookup and aggregate columns share one field menu, one field list helper and one add hook (useAddRecordTableRelationColumn, which reads the current view id when it runs). Allowed operations are derived from the footer's existing aggregate map, so the picker can't drift from what the API computes.
  • Query: a relation's selection can carry a reserved __connectionAggregates key (GraphQL forbids names starting with __). The query generator writes those aggregate names at the connection level, next to edges; nothing else reads the key. A relation shown only through aggregate columns selects just the related records' ids.
  • Store: getRecordFromRecordNode still flattens a connection into an array, and in the same pass keeps its aggregate values beside it under __relationAggregateValues. Loaders stay unaware, and upsertRecordsInStore needed no change. A query without aggregates leaves stored values alone, and a reload replaces them.
  • Cell: read-only, formatted like footer totals (currency short-formatted from micros, numbers and dates per user settings). Count shows 0 for no related records. If the user can't read the aggregated field, the column stays an aggregate column, is left out of the query and shows as forbidden.
  • Column descriptor: label "Relation › Count" or "Relation › Sum of Field", the aggregated field's icon; one isRelationTargetColumn flag turns off filter, sort and footer totals for lookup and aggregate columns.

Known limits

  • Values can be stale: an aggregate refreshes on the next table load, not when related records change.
  • Related ids are fetched: the connection still returns its edges, so a relation shown only through aggregate columns fetches up to 60 related ids per row. Requesting only the aggregates would need the server to skip edges when none are selected.
  • Two tables on one object: if both are open with different aggregate columns, the last load wins in the record store.

Stack

Each PR targets the one it builds on; retarget it to main once that one merges.

PRWhat it doesBuilds on
#30472Server: a view field can show one field of its related recordmerged into main
#30450Server: lookup columns in the view field AI toolsmain
#30348Front: tables handle several columns of one fieldmerged into main
#30439Front: lookup columns, picked from a nested field menumain
This PR 👈Server + front: aggregate columns (count, sum, avg, min, max)#30439

Testing

  • Server:
    • Validator unit tests cover every rule (20 tests), and validate-flat-view-field-relation-target-not-overridden covers the application-owned rule for both the target and the operation (6 tests).
    • New integration spec view-field-relation-aggregate, 9/9: COUNT and SUM accepted, an update from COUNT to AVG accepted then to SUM on a text field rejected, and six rejections.
    • nested-relation-per-parent-limit: a company with 65 people reports totalCount: 65 next to its 60 fetched edges (fails before the fix), 5/5.
    • view-field-relation-target passes 7/7, and application sync passes with its updated snapshot.
  • Front: unit tests for the descriptor, field list, operations, query fields (incl. aggregate-only relations), generator, ingestion (keep, update, clear), both pickers, the add hook (save and rollback), and the cell (incl. an unreadable field). The object-record, object-metadata and views suites pass (1717 tests).
  • Typecheck and oxlint. Generated files were regenerated against a running server with no drift.
  • Browser check on Companies (dev seed):
    • + → People → Count shows each company's 2 people.
    • + → Opportunities → Amount → Sum shows each company's total, e.g. Google 4.3m = 1.8m + 2.5m; Average shows half of it (2 opportunities each).
    • The columns persist after reload, and lookup columns on People still add and load.

Screenshots

In the + menu, a one-to-many relation offers Count and its aggregatable fields:

People page

A field opens its operations:

Amount operations

People › Count and Opportunities › Sum of Amount after a reload:

Aggregate columns


Generated by Claude Code