feat(analytics): add useMetricView client experience

[atilafassina]

TL;DR

Delivers the complete Metric Views client experience on top of #512: applications can query typed Metric Views, format results from catalog metadata, and build interactive cross-filtering charts without duplicating query or presentation logic.

Delivered

• Add useMetricView with inferred selected-row types, metadata, loading/error state, cancellation, HMR refresh, and shared warehouse-readiness reporting.
• Consolidate the Analytics SSE lifecycle used by useMetricView and useAnalyticsQuery.
• Add framework-agnostic formatValue, formatLabel, toD3Format, and toMetricFilter utilities.
• Add chart click and controlled-selection APIs (onDataClick and selected) for cross-filter interactions.
• Add an end-to-end Metric Views playground covering metadata-driven labels, formatting, filters, charts, and table output.
• Document hook usage, formatting, filters, and Plotly/ECharts integration.
• Cover hook typing, SSE behavior, format/filter utilities, chart interactions, and the playground integration with focused tests.

Stacked on #512.

[github-actions]

🔬  Run evals on this PR  ·  Go to Evals Monitor →

[github-actions]

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 827 KB (-1.2 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	855 KB (-294 B)	298 KB (-235 B)
Type declarations	313 KB	108 KB (-9 B)
Source maps	1.7 MB (-5.6 KB)	557 KB (-1.5 KB)
Other	11 KB	3.7 KB
Total	2.8 MB (-5.9 KB)	967 KB (-1.7 KB)

Per-entry composition (own code — deps external (as shipped))

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	87 KB	2.5 KB	90 KB	external	285 KB
./beta	48 KB	459 B	48 KB	external	140 KB
./type-generator	20 KB	0 B	20 KB	external	57 KB

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	83 KB
.	utils.js	initial	4.0 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	32 KB
./beta	stream-manager.js	initial	5.8 KB
./beta	wide-event-emitter.js	initial	3.2 KB
./beta	databricks.js	initial	3.0 KB
./beta	configuration.js	initial	2.1 KB
./beta	service-context.js	initial	1.3 KB
./beta	client.js	initial	431 B
./beta	client-options.js	initial	219 B
./beta	supervisor-api.js	lazy	194 B
./beta	databricks.js	lazy	142 B
./beta	index.js	lazy	123 B
./type-generator	index.js	initial	20 KB

@databricks/appkit-ui

npm tarball (packed): 339 KB (+2.0 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	387 KB (+2.2 KB)	130 KB (+603 B)
Type declarations	226 KB	82 KB
Source maps	744 KB (+4.8 KB)	245 KB (+1.3 KB)
CSS	16 KB	3.3 KB
Total	1.3 MB (+7.0 KB)	461 KB (+1.9 KB)

Per-entry composition (consumer bundle — deps bundled, peerDeps external)

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
./js	5.0 KB	49 KB	54 KB	208 KB	14 KB
./js/beta	20 B	0 B	20 B	0 B	0 B
./react	431 KB (+405 B)	49 KB	480 KB (+405 B)	1.3 MB	174 KB (+1.1 KB)
./react/beta	1.0 KB	0 B	1.0 KB	0 B	1.9 KB

Chunks:

Entry	Chunk	Load	Size (gz)
./js	index.js	initial	4.9 KB
./js	chunk	initial	120 B
./js	apache-arrow	lazy	49 KB
./js/beta	beta.js	initial	20 B
./react	index.js	initial	429 KB
./react	tslib	initial	2.1 KB
./react	apache-arrow	lazy	49 KB
./react/beta	beta.js	initial	1.0 KB

[github-actions]

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 31110646227 -R databricks/appkit -n appkit-template-0.55.0-pr.693f431-mv-hook-488 -D appkit-pr-488 \
  && unzip -o "appkit-pr-488/appkit-template-0.55.0-pr.693f431-mv-hook-488.zip" -d "appkit-pr-488" \
  && databricks apps init --template "appkit-pr-488"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.

[Copilot]

Pull request overview

Adds the Metric Views client experience to AppKit UI and shared packages: a new useMetricView React hook (SSE-driven, typed rows + metadata), shared SSE lifecycle handling with useAnalyticsQuery, plus framework-agnostic format/filter utilities and chart interaction APIs. Also wires generated Metric View metadata into the dev-playground server and provides an end-to-end playground page + docs + focused tests.

Changes:

• Introduce shared Metric Filter AST + a toMetricFilter helper, and re-export these types consistently across shared, appkit, and appkit-ui.
• Add useMetricView and consolidate analytics SSE parsing/handling for both metric-view and analytics-query hooks.
• Add chart click + selection emphasis support and a dev-playground Metric Views page demonstrating cross-filtering with metadata-driven formatting/labels.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/shared/src/metric-filter.ts	New shared Metric Filter operator vocabulary + filter AST types.
packages/shared/src/index.ts	Re-export metric-filter from shared barrel.
packages/appkit/src/plugins/analytics/types.ts	Switch metric-filter types to shared source-of-truth; expand analytics SSE error typing.
packages/appkit/src/plugins/analytics/tests/types.test.ts	Type-level test ensuring analytics re-exports shared metric-filter types.
packages/appkit/src/plugins/analytics/tests/analytics.integration.test.ts	Use ephemeral port + wait-for-listening helper to reduce integration-test flakiness.
packages/appkit/src/plugins/analytics/mv/constants.ts	Re-export filter-operator vocab/subsets from shared module.
packages/appkit-ui/src/react/lib/format.ts	Delegate label humanization to JS formatter with input sanitization.
packages/appkit-ui/src/react/lib/format.test.ts	Add coverage for label formatting + sanitization behavior.
packages/appkit-ui/src/react/hooks/use-metric-view.ts	New useMetricView hook implementation using shared analytics SSE lifecycle.
packages/appkit-ui/src/react/hooks/use-analytics-query.ts	Refactor to use shared SSE handlers (analytics-sse.ts).
packages/appkit-ui/src/react/hooks/types.ts	Add Metric View registry-driven typing utilities + UseMetricView* types.
packages/appkit-ui/src/react/hooks/index.ts	Export new Metric View-related types and useMetricView.
packages/appkit-ui/src/react/hooks/analytics-sse.ts	New shared SSE parsing/handling helpers for analytics hooks.
packages/appkit-ui/src/react/hooks/tests/use-metric-view.types.test.ts	Compile-time probe test for useMetricView type inference/correlation.
packages/appkit-ui/src/react/hooks/tests/use-metric-view.test.ts	Behavioral tests for useMetricView (payload, results, errors, abort, warehouse status publishing).
packages/appkit-ui/src/react/hooks/tests/analytics-sse.test.ts	Unit tests for shared analytics SSE parsing/handling helpers.
packages/appkit-ui/src/react/charts/utils.ts	Re-export shared formatLabel; add click datum mapping helper for ECharts.
packages/appkit-ui/src/react/charts/types.ts	Add chart click datum type + onDataClick + controlled selected props.
packages/appkit-ui/src/react/charts/options.ts	Add interactive line clickability + selection emphasis transform for categorical series.
packages/appkit-ui/src/react/charts/index.ts	Export new chart interaction/selection APIs.
packages/appkit-ui/src/react/charts/base.tsx	Wire click handling + selection emphasis into base chart; stabilize event subscription.
packages/appkit-ui/src/react/charts/tests/utils.test.ts	Add tests for click datum normalization.
packages/appkit-ui/src/react/charts/tests/options.test.ts	Add tests for interactive line options + applySelectionEmphasis behavior.
packages/appkit-ui/src/js/metric-filter/index.ts	New JS helper toMetricFilter + re-export shared metric-filter types.
packages/appkit-ui/src/js/metric-filter/index.test.ts	Tests for toMetricFilter behavior and type re-exports.
packages/appkit-ui/src/js/index.ts	Export new JS format + metric-filter modules.
packages/appkit-ui/src/js/format/index.ts	New pure formatting utilities: formatValue, formatLabel, toD3Format (incl bigint-safe paths).
packages/appkit-ui/src/js/format/index.test.ts	Tests for format utilities, including bigint precision and currency-prefix coverage.
docs/docs/plugins/analytics.md	Document useMetricView, metadata injection, and formatting utilities with examples.
bundle-size-baseline.json	Update bundle size baseline after adding new APIs/utilities.
biome.json	Exclude generated metric-views artifact from Biome formatting/linting.
apps/dev-playground/shared/appkit-types/metric-views.ts	Generated registry augmentation + new exported metricViewsMetadata constant.
apps/dev-playground/server/index.ts	Wire generated metricViewsMetadata into analytics({ metricViewsMetadata }).
apps/dev-playground/client/src/routeTree.gen.ts	Add route entry for Metric Views playground page.
apps/dev-playground/client/src/routes/metric-views.route.tsx	New end-to-end Metric Views playground page demonstrating cross-filtering + metadata-driven formatting.
apps/dev-playground/client/src/lib/nav.ts	Add navigation entry for Metric Views page.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pkosiec]

Review: useMetricView client experience

Solid PR — the hook, SSE consolidation, and format/filter utilities are well-built. I verified the feature live in the dev-playground against the dogfood warehouse: labels, currency formatting, all filter paths (dropdowns, table-row, chart-click), multi-dimension filters, chip removal, and Clear all all work.

One thing is broken: the time-series line chart scrambles into spaghetti after any filter (details inline). Everything else is UX polish or API consistency.

Findings

• 🔴 P1 — trend line chart renders unordered → scrambled (reproduced)
• 🟠 P2 — every filter blanks all visuals to skeletons (flash)
• 🟠 P2 — useMetricView doesn't return warehouseStatus (no cold-start UI)
• nit × 6 — charts ignore metadata format (playground), empty-key throw, autoStart parity, selected scope, leftover console.log, dense comments

Third-party (not this PR, FYI): filtering spams the console with TypeError: Cannot read properties of undefined (reading 'disconnect') (×10 in one session). Traced to size-sensor (resizeObserver.js destroy()), a transitive dep of echarts-for-react — not our code. The rapid chart remount-on-filter (see the skeleton-flash finding) is what surfaces it. Fixing that flash likely quiets it; otherwise a separate ticket / dep note.

Non-blocking (COMMENT). Nothing needs to gate merge except your own call on the P1.

[pkosiec]

🔴 P1 — trend line chart renders scrambled after any filter.

Reproduced live: pick a region/segment or click a table row → this line chart tangles into criss-crossing lines. It sometimes looks fine unfiltered — that's luck, not correctness.

Why:

• This query has no orderBy, and the metric route only adds ORDER BY when limit is set. So rows come back in arbitrary order.
• ECharts draws a line in data-array order, so unordered rows zig-zag.
• The client's sortTimeSeriesAscending only helps if the rows are fully reversed, not just shuffled.

This is the documented happy path (useMetricView by time → LineChart), so worth fixing at more than one layer:

• Here (must-fix): add orderBy: [{ field: "created_at", direction: "ASC" }] — one line, and you already have TABLE_ORDER_BY as the pattern.
• Docs: note that time-series charts need orderBy on the time dimension.
• Follow-up (pre-existing): make sortTimeSeriesAscending actually sort ascending, not just reverse a descending array — fixes every consumer.

[pkosiec]

Here's how the graph looks like for me:

[pkosiec]

🟠 P2 — every re-query blanks all visuals to skeletons.

start() calls setData(null) on every requery, so a cross-filter click tears down and re-skeletons all four visuals at once — a full-page flash over the warehouse round-trip. Cross-filter is the headline feature, so this is exactly where it should feel smooth.

Suggestion: stale-while-revalidate — keep the previous data during a refetch, show the skeleton only on first load. One caveat: clear data on a key change (old metric's rows are meaningless), but keep it on a filter/payload change.

[pkosiec]

🟠 P2 — hook doesn't return warehouseStatus, so there's no cold-start affordance.

The hook publishes warehouse status to the provider but doesn't return it, unlike useAnalyticsQuery. Without a ResourceStatusProvider mounted (the playground has none), a cold warehouse is just a long blank skeleton with no "warehouse starting…" signal. Combined with the skeleton-flash above, cold starts feel broken.

Suggestion: return warehouseStatus for parity, or document that a provider is required for the cold-start UX.

[pkosiec]

nit: empty key throws during render. If a metric key comes from a dropdown that's "" for a frame, this crashes the subtree instead of flowing through the existing error state. Consider setting error and skipping the request. Matches useAnalyticsQuery, so it may be intentional — low priority.

[pkosiec]

nit: charts don't apply the metadata number format. Seen live: the bar tooltip shows 849,732,624 while the table shows $849,732,624.00 — same number, same page. The table uses formatValue(row[col], metadata?.[col]?.format), but the chart gets only data.

toD3Format exists for exactly this. Since this file is the API reference, it'd be nice to show the metadata→chart wiring (thread the d3 specifier through options) so users discover it. Playground-only, so low priority.

[pkosiec]

nit: useMetricView has no autoStart option, but useAnalyticsQuery does. The two hooks read as twins, so the asymmetry surprises. Consider adding autoStart (and maybe a returned refetch) for parity, or noting the omission in the docs.

[pkosiec]

nit: selected emphasis only applies to bar/pie/donut; line/area/scatter/heatmap/radar silently ignore it. It's documented on the prop — just worth a line in the chart-integration docs so users don't wire selected to a line chart and wonder why nothing dims.

[pkosiec]

nit: leftover console.log in the reference app. Since this file is the copy-paste template, replace it with a real handler or a commented-out // TODO: cross-filter here showing the intended wiring (the other charts show the pattern).

[pkosiec]

nit: comments are dense in a few spots — worth a trim pass.

The intent-comments are good, but some run long:

• cache.ts here — 12 lines explaining one orderByPart ternary.
• metric-filter/index.ts — ~54% comments.
• use-metric-view.ts:98 and a few chart blocks are essay-length.

These read more like design docs than code comments. Suggestion: keep the "why" (e.g. "orderBy not sorted — sequence is semantic under LIMIT") in 1-2 lines and drop the worked-through reasoning. Leaner diff, same signal. Public-API JSDoc with examples is fine to keep.

[pkosiec]

Review: useMetricView client experience

Solid PR — the hook, SSE consolidation, and format/filter utilities are well-built. I verified the feature live in the dev-playground against the dogfood warehouse: labels, currency formatting, all filter paths (dropdowns, table-row, chart-click), multi-dimension filters, chip removal, and Clear all all work.

One thing is broken: the time-series line chart scrambles into spaghetti after any filter (details inline). Everything else is UX polish or API consistency.

Findings

• 🔴 P1 — trend line chart renders unordered → scrambled (reproduced)
• 🟠 P2 — every filter blanks all visuals to skeletons (flash)
• 🟠 P2 — useMetricView doesn't return warehouseStatus (no cold-start UI)
• nit × 6 — charts ignore metadata format (playground), empty-key throw, autoStart parity, selected scope, leftover console.log, dense comments

Third-party (not this PR, FYI): filtering spams the console with TypeError: Cannot read properties of undefined (reading 'disconnect') (×10 in one session). Traced to size-sensor (resizeObserver.js destroy()), a transitive dep of echarts-for-react — not our code. The rapid chart remount-on-filter (see the skeleton-flash finding) is what surfaces it. Fixing that flash likely quiets it; otherwise a separate ticket / dep note.

Non-blocking (COMMENT). Nothing needs to gate merge except your own call on the P1.

[pkosiec]

🔴 P1 — trend line chart intermittently renders as scrambled spaghetti.

Reproduced live (screenshots in thread). It's non-deterministic — a coin flip per cached result, not reliable on demand. That unpredictability is the bug.

Mechanism (all three confirmed):

1. This query sets no orderBy, and the metric route only emits SQL ORDER BY when limit is set. So rows come back in arbitrary order — verified against the live route: created_at is non-monotonic for both filtered and unfiltered queries.
2. ECharts draws a line in data-array order, so unordered rows zig-zag.
3. The client's sortTimeSeriesAscending (charts/utils.ts:327) only sorts when first > last (first row's timestamp is later than the last row's). If that guard happens to fire, you get a full ascending sort → clean chart. If it doesn't, the shuffled rows render as-is → spaghetti. Whether it fires depends purely on the arbitrary arrival/caching order → ~coin flip.

Repro note: you can't force it from the UI reliably — flip a filter and reload a few times, or clear the metric cache, and the same query alternates clean vs scrambled as the cached row order changes.

This is the documented happy path (useMetricView by time → LineChart), so worth fixing at more than one layer:

• Here (must-fix): add orderBy: [{ field: "created_at", direction: "ASC" }] — one line, and you already have TABLE_ORDER_BY as the pattern.
• Docs: note that time-series charts need orderBy on the time dimension (the route doesn't order by default without limit).
• Follow-up (pre-existing): sortTimeSeriesAscending should always sort ascending by x, not only when first > last. Right now a shuffled series that isn't fully descending is left untouched — fixing this hardens every consumer, not just this demo.

[pkosiec]

🟠 P2 — every re-query blanks all visuals to skeletons.

start() calls setData(null) on every requery, so a cross-filter click tears down and re-skeletons all four visuals at once — a full-page flash over the warehouse round-trip. Cross-filter is the headline feature, so this is exactly where it should feel smooth.

Suggestion: stale-while-revalidate — keep the previous data during a refetch, show the skeleton only on first load. One caveat: clear data on a key change (old metric's rows are meaningless), but keep it on a filter/payload change.

[pkosiec]

🟠 P2 — hook doesn't return warehouseStatus, so there's no cold-start affordance.

The hook publishes warehouse status to the provider but doesn't return it, unlike useAnalyticsQuery. Without a ResourceStatusProvider mounted (the playground has none), a cold warehouse is just a long blank skeleton with no "warehouse starting…" signal. Combined with the skeleton-flash above, cold starts feel broken.

Suggestion: return warehouseStatus for parity, or document that a provider is required for the cold-start UX.

[pkosiec]

nit: empty key throws during render. If a metric key comes from a dropdown that's "" for a frame, this crashes the subtree instead of flowing through the existing error state. Consider setting error and skipping the request. Matches useAnalyticsQuery, so it may be intentional — low priority.

[pkosiec]

nit: charts don't apply the metadata number format. Seen live: the bar tooltip shows 849,732,624 while the table shows $849,732,624.00 — same number, same page. The table uses formatValue(row[col], metadata?.[col]?.format), but the chart gets only data.

toD3Format exists for exactly this. Since this file is the API reference, it'd be nice to show the metadata→chart wiring (thread the d3 specifier through options) so users discover it. Playground-only, so low priority.

[pkosiec]

nit: useMetricView has no autoStart option, but useAnalyticsQuery does. The two hooks read as twins, so the asymmetry surprises. Consider adding autoStart (and maybe a returned refetch) for parity, or noting the omission in the docs.

[pkosiec]

nit: selected emphasis only applies to bar/pie/donut; line/area/scatter/heatmap/radar silently ignore it. It's documented on the prop — just worth a line in the chart-integration docs so users don't wire selected to a line chart and wonder why nothing dims.

[pkosiec]

nit: leftover console.log in the reference app. Since this file is the copy-paste template, replace it with a real handler or a commented-out // TODO: cross-filter here showing the intended wiring (the other charts show the pattern).

[pkosiec]

nit: comments are dense in a few spots — worth a trim pass.

The intent-comments are good, but some run long:

• cache.ts here — 12 lines explaining one orderByPart ternary.
• metric-filter/index.ts — ~54% comments.
• use-metric-view.ts:98 and a few chart blocks are essay-length.

These read more like design docs than code comments. Suggestion: keep the "why" (e.g. "orderBy not sorted — sequence is semantic under LIMIT") in 1-2 lines and drop the worked-through reasoning. Leaner diff, same signal. Public-API JSDoc with examples is fine to keep.