Carry a relation's filter, sort and limit in RecordGqlFields
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:
RecordGqlFieldsvalues can be aRecordGqlFieldsRelationWithArguments(relationFieldName, optionalfilter/orderBy/first, and the nestedrecordGqlFields). Its key is the response key, derived from the field and its arguments bycomputeRelationWithArgumentsResponseKey(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:
getReadableRelationsWithArgumentsis 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.mapObjectMetadataToGraphQLQuerytakes 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'srecordGqlFieldsis considered. - Hooks:
useFindManyRecordsQueryreturnsrelationsWithArgumentsVariables;useFindManyRecords,useLazyFindManyRecordsanduseLazyFindManyRecordsWithOffsetsend them. No new parameter: callers put the entry inrecordGqlFields. - Optimistic effects:
triggerUpdateRelationsWithArgumentsOptimisticEffectkeeps 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 (
firstreached) 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:
filterRecordOnGqlFieldsfilters such an entry on its nested fields;getRecordNodeFromRecordand 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.
| Track | PR | What it does | Size | Code | Tests / generated | Builds on |
|---|---|---|---|---|---|---|
| Server: views | #30339 | Per-column settings on view fields (label, record limit) | S | +300 −2 | +703 −152 | main |
| Server: views | #30341 | A view can be owned by a one-to-many view field (scope view) | M | +584 −56 | +891 −4 | main |
| Server: views | #30472 | Lookup: a view field shows one field of its related record | M | +280 −38 | +428 −4 | #30339 |
| Server: views | #30466 | upsertViewFieldWithScope: 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 | #30450 | Expose column scopes and lookups in the view AI tools | S | +31 | +222 | #30339, #30341, #30472 |
| Server: query engine | #30347 | Honor filter / orderBy / first on nested one-to-many relations | M | +462 −86 | +509 | main |
| Server: query engine | #30473 | One relation-selection tree through the common query layer (refactor, no behavior change) | L | +663 −685 | +277 −46 | #30347 |
| Server: query engine | #30465 | Each alias of a nested relation gets its own arguments and rows | L | +595 −237 | +727 −21 | #30473 |
| Front | #30468 👈 | Carry a relation's filter, sort and limit in RecordGqlFields | M | +663 −41 | +469 | main |
| Front | #30469 | Don't recreate a saved sort that comes back under a new id | S | +21 −17 | +8 | main |
| Front | #30348 | Extra table columns and the Edit column panel, behind IS_COLUMN_SETTINGS_ENABLED | M | +718 −76 | +152 −30 | #30339 |
| Front | #30349 | Scope one-to-many columns from the Edit column panel | L | +1053 −92 | +316 −18 | #30348, #30466, #30468, #30469, #30465 |
| Front | #30439 | Lookup columns in the table, editable from their cells (absorbs #30440) | L | +805 −223 | +283 −30 | #30349 |
| Front | #30458 | Lookup and scoped columns on boards and calendars | M | +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;getReadableRelationsWithArgumentswith its variable definitions and variables (readable, unreadable target, not a one-to-many relation, non-derived key);generateFindManyRecordsQuerywith and without such an entry;filterRecordOnGqlFields. - Unit, new:
triggerUpdateRelationsWithArgumentsOptimisticEffectagainst 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.tsand its test are now unused.
Generated by Claude Code