Analytics: preserve raw dimension values so report drill-down can filter lookup/select dims precisely

[os-zhuang]

Context

ADR-0021 report drill-down shipped in objectui#1649: clicking an aggregated row/cell in a dataset-bound report navigates to the object list scoped by the clicked dimension bucket (?filter[field]=value).

The analytics service (packages/services/service-analytics/src/dimension-labels.ts) resolves dimension bucket values to display labels in place (select option label, lookup record name) — resolveDimensionLabels overwrites row[dimension.name] with the human label. This is correct for rendering, but it means the raw stored value is lost by the time a drill click happens.

objectui's drill handler (ReportView.handleDatasetDrill) currently works around this per field kind:

• select — reverse-maps the label back to the stored option value via the object's field options. Works, but fragile (depends on objectui re-deriving the mapping).
• lookup / master_detail — the resolved label is a record name, not the FK id; objectui skips the dimension entirely, so the drill lands on a superset (all records, not the clicked account/owner).
• date-granularity — see sibling issue.

Proposal

Have the analytics response carry the raw grouped value alongside the display label, e.g. a parallel __raw map or { value, label } cells, so the dataset query result is self-describing. Then the drill consumer can filter on the exact stored value (FK id, option value) without re-deriving anything — and lookup drill-down becomes precise instead of a superset.

Affected

• framework: packages/services/service-analytics/src/{analytics-service,dimension-labels}.ts
• objectui (consumer): packages/app-shell/src/views/ReportView.tsx handleDatasetDrill — drop the label→value reverse-map once raw values arrive.

Found during the ADR-0021 report epic; browser-verified the select-field workaround against app-showcase.

[os-zhuang]

Re-evaluated 2026-07-18 — this shipped. Closing as completed.

The proposal here was implemented (in the "parallel raw sidecar" variant) by #2080 (merged 2026-06-20, released as @objectstack/service-analytics@9.12.0 via #2081):

• queryDataset now attaches drill-through metadata to the result before label resolution runs: the base object, a drillable dimensionFields name→field map, and a parallel drillRawRows array holding each row's raw grouped values (FK id, stored option value). Rows themselves still carry display labels — no shape change for existing consumers. See packages/services/service-analytics/src/analytics-service.ts (ADR-0021 D2 block, ~L488–508).
• Consumer side: objectui/objectui#1842 switched ReportView.handleDatasetDrill to filter on the raw sidecar values — the select label→value reverse-map workaround is gone, and lookup / master_detail drill now filters by the stored FK id instead of skipping the dimension (no more superset).
• Coverage: query-dataset.test.ts asserts the metadata shape, the raw-value sidecar, and that a lookup dimension is drillable; test(example-crm): lookup-dimension report fixture (sales by account) #2107 added the SalesByAccountReport lookup-dimension fixture to example-crm exercising the path end-to-end.

Out of scope / follow-ups:

• Date-granularity dims are deliberately excluded from drill metadata (a humanized bucket can't be equality-matched) — that's sibling issue Report drill-down: date-granularity dimensions need a range filter, not equality #1752, which remains open and valid.
• Minor residual gap noticed during re-evaluation: drillRawRows is only snapshotted for result.rows; the totals/subtotal rows (Matrix reports: server-side totals row/column (subtotals + grand total) #1753) get their labels resolved but have no raw sidecar, so a drill from a subtotal row would still lack the raw value. If subtotal drill ever becomes a requirement, that deserves its own small issue rather than keeping this one open.

---

Generated by Claude Code