Carry a relation's filter, sort and limit in RecordGqlFields

Closed
FE
2d ago
+1132-41

Front-end foundation for record column scopes. A relation queried with its own filter, orderBy and first is now an ordinary entry of RecordGqlFields, next to the plain relation. The query builders, the cache readers and the optimistic effects all read that one entry, so there is no separate alias parameter to thread through the hooks. Uses the per-alias nested arguments from #30465. No caller adds such an entry in this PR, so every generated query is unchanged.

Changes

  • Model: RecordGqlFields values can be a RecordGqlFieldsRelationWithArguments (relationFieldName, optional filter / orderBy / first, and the nested recordGqlFields). Its key is the response key, derived from the field and its arguments by computeRelationWithArgumentsResponseKey (people_<hash>). The same field and arguments always land on the same record key, and a key that is not derived is rejected.
  • Query building: getReadableRelationsWithArguments is the single rule for which of these entries a query selects (one-to-many relation, readable field, readable target). Selections, variable definitions and variables are all built from its result, so they cannot disagree. mapObjectMetadataToGraphQLQuery takes that typed list and renders it through the existing one-to-many branch of the field mapper. Arguments go in as variables because some filter values are enums. Only the root of a query's recordGqlFields is considered.
  • Hooks: useFindManyRecordsQuery returns relationsWithArgumentsVariables; useFindManyRecords, useLazyFindManyRecords and useLazyFindManyRecordsWithOffset send them. No new parameter: callers put the entry in recordGqlFields.
  • Optimistic effects: triggerUpdateRelationsWithArgumentsOptimisticEffect keeps cached copies that carry arguments in line with a source record, the way root queries already are: filter match, sort, then limit. It runs on attach, on detach, and when a record stays attached but its values change. Because the response key is derived from the cached arguments, the result is also written to the record store under that key.
  • Known limit: a copy that was full (first reached) cannot be refilled on the client after a removal; only a refetch knows what comes next. The refetch listener in #30349 stays as that backstop.
  • Cache readers: filterRecordOnGqlFields filters such an entry on its nested fields; getRecordNodeFromRecord and cache fragments ignore it, so it is never written back as if it were a field.

Stack

The work is split into short tracks that can be reviewed and merged in parallel. Each PR targets main or the one PR it builds on. Two PRs need several others; they target an integration branch (felix/relaxed-einstein-vxil3q-base-*, not a PR) that merges exactly their dependencies, so their diff shows only their own changes. A PR can merge once everything in its "Builds on" column is merged; retarget it to main at that point.

Size counts changed lines outside tests and generated files: S < 300, M 300–800, L > 800. Sizes are a snapshot and are not kept in sync with every push.

TrackPRWhat it doesSizeCodeTests / generatedBuilds on
Server: views#30339Per-column settings on view fields (label, record limit)S+300 −2+703 −152main
Server: views#30341A view can be owned by a one-to-many view field (scope view)M+584 −56+891 −4main
Server: views#30472Lookup: a view field shows one field of its related recordM+280 −38+428 −4#30339
Server: views#30466upsertViewFieldWithScope: save a column with its settings, lookup and scope in one migration (~600 lines moved out of view-widget-upsert)L+1330 −567+1117 −256#30339, #30341, #30472
Server: views#30450Expose column scopes and lookups in the view AI toolsS+31+222#30339, #30341, #30472
Server: query engine#30347Honor filter / orderBy / first on nested one-to-many relationsM+462 −86+509main
Server: query engine#30473One relation-selection tree through the common query layer (refactor, no behavior change)L+663 −685+277 −46#30347
Server: query engine#30465Each alias of a nested relation gets its own arguments and rowsL+595 −237+727 −21#30473
Front#30468 👈Carry a relation's filter, sort and limit in RecordGqlFieldsM+663 −41+469main
Front#30469Don't recreate a saved sort that comes back under a new idS+21 −17+8main
Front#30348Extra table columns and the Edit column panel, behind IS_COLUMN_SETTINGS_ENABLEDM+718 −76+152 −30#30339
Front#30349Scope one-to-many columns from the Edit column panelL+1053 −92+316 −18#30348, #30466, #30468, #30469, #30465
Front#30439Lookup columns in the table, editable from their cells (absorbs #30440)L+805 −223+283 −30#30349
Front#30458Lookup and scoped columns on boards and calendarsM+404 −284+140 −7#30439

The longest dependency chain is #30339 → #30348 → #30349 → #30439 → #30458; everything else is one or two levels deep. #30339, #30341 and #30472 each add a 2.59 instance command, so whichever merges after another may need a fresh timestamp.

Testing

  • Unit, new: computeRelationWithArgumentsResponseKey; getReadableRelationsWithArguments with its variable definitions and variables (readable, unreadable target, not a one-to-many relation, non-derived key); generateFindManyRecordsQuery with and without such an entry; filterRecordOnGqlFields.
  • Unit, new: triggerUpdateRelationsWithArgumentsOptimisticEffect against a real Apollo cache: attach of a matching record (sorted, within the limit), attach of a non-matching record, detach, and a record that stays attached but stops matching. Each case also checks the record store write under the derived key.
  • Existing suites for the touched modules pass: attach/detach optimistic effects, useFindManyRecords, useFindManyRecordsQuery, mapObjectMetadataToGraphQLQuery, cache utils.
  • Front typecheck, oxlint and knip clean. Not exercised in a browser here; the entries are used end to end by the column-scope feature in #30349.
  • To remove before merge: RecordGqlRelationAlias.ts, getRecordGqlRelationAliasVariables.ts, mapRecordGqlRelationAliasesToGraphQLQuery.ts and its test are now unused.

Generated by Claude Code