feat(analytics): freeze metric-view runtime contracts (PR5 phase 0)

Freeze the three shared seams the metric-view hook/server/generator phases
compile against:
- S1: MetricColumnMeta + MetricViewsMetadata value types in packages/shared
- S2: optional per-column metadata on the SSE result message + makeResultMessage
- S3: base MetricRegistry, MetricKey, Infer* helpers, MetricFilter mirrors, and
  UseMetricViewOptions/UseMetricViewResult in appkit-ui hook types

Types only (plus a makeResultMessage passthrough); existing /query callers are
unchanged since metadata is optional.

Co-authored-by: Isaac
Signed-off-by: Atila Fassina <atila@fassina.eu>

Author: atilafassina

packages/appkit-ui/src/react/hooks/index.ts

@@ -7,18 +7,29 @@ export {
 } from "../resource-status-indicator";
 export type {
   AnalyticsFormat,
+  InferDimensionKeys,
+  InferMeasureKeys,
+  InferMetricRow,
   InferResultByFormat,
   InferRowType,
   InferServingChunk,
   InferServingRequest,
   InferServingResponse,
+  InferTimeGrains,
+  MetricFilter,
+  MetricFilterOperatorName,
+  MetricKey,
+  MetricPredicate,
+  MetricRegistry,
   PluginRegistry,
   QueryRegistry,
   ServingAlias,
   ServingEndpointRegistry,
   TypedArrowTable,
   UseAnalyticsQueryOptions,
   UseAnalyticsQueryResult,
+  UseMetricViewOptions,
+  UseMetricViewResult,
   WarehouseState,
   WarehouseStatus,
 } from "./types";

packages/appkit-ui/src/react/hooks/types.ts

@@ -1,4 +1,5 @@
 import type { Table } from "apache-arrow";
+import type { MetricColumnMeta } from "shared";
 
 // ============================================================================
 // Data Format Types
@@ -247,3 +248,128 @@ export type InferServingRequest<K> =
       ? Req
       : Record<string, unknown>
     : Record<string, unknown>;
+
+// ============================================================================
+// Metric View Registry
+// ============================================================================
+
+/**
+ * Metric view registry for type-safe metric keys, measure/dimension names,
+ * time grains, and row shapes. Extend this interface via module augmentation
+ * to get autocomplete for `useMetricView`:
+ *
+ * @example
+ * ```typescript
+ * // Auto-generated (generated metric-views.ts)
+ * declare module "@databricks/appkit-ui/react" {
+ *   interface MetricRegistry {
+ *     orders: {
+ *       measureKeys: "revenue" | "order_count";
+ *       dimensionKeys: "region" | "order_date";
+ *       timeGrains: "day" | "month";
+ *       measures: { revenue: number; order_count: number };
+ *       dimensions: { region: string; order_date: string };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: intentionally empty — populated via module augmentation (generated metric-views.ts)
+export interface MetricRegistry {}
+
+/** Resolves to registry keys if populated, otherwise string */
+export type MetricKey = AugmentedRegistry<MetricRegistry> extends never
+  ? string
+  : AugmentedRegistry<MetricRegistry>;
+
+/** Infers measure key names from the registry when K is a known key */
+export type InferMeasureKeys<K> = K extends AugmentedRegistry<MetricRegistry>
+  ? MetricRegistry[K] extends { measureKeys: infer M }
+    ? M
+    : string
+  : string;
+
+/** Infers dimension key names from the registry when K is a known key */
+export type InferDimensionKeys<K> = K extends AugmentedRegistry<MetricRegistry>
+  ? MetricRegistry[K] extends { dimensionKeys: infer D }
+    ? D
+    : string
+  : string;
+
+/** Infers time-grain names from the registry when K is a known key */
+export type InferTimeGrains<K> = K extends AugmentedRegistry<MetricRegistry>
+  ? MetricRegistry[K] extends { timeGrains: infer G }
+    ? G
+    : string
+  : string;
+
+/**
+ * Infers the row shape (measures + dimensions) from the registry when K is a
+ * known key, otherwise a total `Record<string, unknown>`. Never resolves to
+ * `never` — always assignable to `Record<string, unknown>`.
+ */
+export type InferMetricRow<K> = K extends AugmentedRegistry<MetricRegistry>
+  ? MetricRegistry[K] extends {
+      measures: infer Meas;
+      dimensions: infer Dim;
+    }
+    ? Meas & Dim
+    : Record<string, unknown>
+  : Record<string, unknown>;
+
+// ────────────────────────────────────────────────────────────────────────────
+// Metric filter vocabulary.
+//
+// **Kept in sync with appkit `plugins/analytics/types.ts`** — appkit-ui cannot
+// depend on appkit, so this mirrors the twelve-operator filter grammar by hand.
+// ────────────────────────────────────────────────────────────────────────────
+
+/** v1 filter operator vocabulary — exactly twelve names. */
+export type MetricFilterOperatorName =
+  | "equals"
+  | "notEquals"
+  | "in"
+  | "notIn"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "contains"
+  | "notContains"
+  | "set"
+  | "notSet";
+
+/** A single filter predicate — the leaf node of the recursive {@link MetricFilter} tree. */
+export interface MetricPredicate {
+  member: string;
+  operator: MetricFilterOperatorName;
+  values?: ReadonlyArray<string | number>;
+}
+
+/** Recursive filter expression: a leaf {@link MetricPredicate} or an `and`/`or` group. */
+export type MetricFilter =
+  | MetricPredicate
+  | { and: ReadonlyArray<MetricFilter> }
+  | { or: ReadonlyArray<MetricFilter> };
+
+/** Options for configuring a `useMetricView` query. */
+export interface UseMetricViewOptions<K extends MetricKey = MetricKey> {
+  measures: ReadonlyArray<InferMeasureKeys<K>>;
+  dimensions?: ReadonlyArray<InferDimensionKeys<K>>;
+  filter?: MetricFilter;
+  timeGrain?: InferTimeGrains<K>;
+  timeDimension?: InferDimensionKeys<K>;
+  limit?: number;
+  autoStart?: boolean;
+}
+
+/** Result state returned by `useMetricView`. */
+export interface UseMetricViewResult<T = Record<string, unknown>[]> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  /** Structured upstream error code, mirroring useAnalyticsQuery. */
+  errorCode: string | null;
+  /** Per-column display metadata for the queried columns, carried in the SSE result payload. `undefined` when the server injected no metadata (dormant / unknown key). */
+  metadata: Record<string, MetricColumnMeta> | undefined;
+}

packages/shared/src/index.ts

@@ -2,6 +2,7 @@ export * from "./agent";
 export * from "./cache";
 export * from "./execute";
 export * from "./genie";
+export * from "./metric-metadata";
 export * from "./plugin";
 export * from "./sql";
 export * from "./sse/analytics";

packages/shared/src/metric-metadata.ts

@@ -0,0 +1,18 @@
+/** Per-column display metadata for a UC Metric View column, sourced from the
+ *  YAML 1.1 display_name/format attributes + SQL type. Loose enough that an
+ *  `as const` generated literal assigns to it. */
+export interface MetricColumnMeta {
+  type: string;
+  display_name?: string;
+  format?: string;
+  description?: string;
+}
+/** Build-time-generated metadata for every registered metric view, keyed by
+ *  metric key. Injected into the analytics plugin via `analytics({ metricViewsMetadata })`. */
+export type MetricViewsMetadata = Record<
+  string,
+  {
+    measures: Record<string, MetricColumnMeta>;
+    dimensions: Record<string, MetricColumnMeta>;
+  }
+>;

packages/shared/src/sse/analytics.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { MetricColumnMeta } from "../metric-metadata";
 
 /**
  * Wire protocol for analytics SSE messages emitted by `/api/analytics/query`.
@@ -37,22 +38,31 @@ export const AnalyticsResultMessage = z.object({
   // `unknown` so we don't bake the SDK's detailed shape into the contract.
   status: z.unknown().optional(),
   statement_id: z.string().optional(),
+  // Per-column display metadata for a metric-view result (display_name /
+  // format / type). Kept loose (`z.record(z.string(), z.unknown())`) for the
+  // same "keep client validation cheap" reason as `data` — the server
+  // constructs it via the typed builder, so the per-column shape is enforced
+  // at the source. Absent for plain `/query` results.
+  metadata: z.record(z.string(), z.unknown()).optional(),
 });
 
 /**
  * TS-level shape of a successful row-shaped result message.
  *
  * **Kept in sync by hand** with `AnalyticsResultMessage` above. The Zod
- * schema is intentionally loose (`z.array(z.unknown())`) to keep client
+ * schema is intentionally loose (`z.array(z.unknown())` for `data`,
+ * `z.record(z.string(), z.unknown())` for `metadata`) to keep client
  * validation cheap; this interface narrows `data` to
- * `Record<string, unknown>[]` so consumers don't have to cast at every
+ * `Record<string, unknown>[]` and `metadata` to
+ * `Record<string, MetricColumnMeta>` so consumers don't have to cast at every
  * call site. If you add a field to the Zod schema, add it here too.
  */
 export interface AnalyticsResultMessage {
   type: "result";
   data?: Record<string, unknown>[];
   status?: unknown;
   statement_id?: string;
+  metadata?: Record<string, MetricColumnMeta>;
 }
 
 /**
@@ -72,7 +82,11 @@ export type AnalyticsSseMessage = z.infer<typeof AnalyticsSseMessage>;
 
 export function makeResultMessage(
   data: Record<string, unknown>[] | undefined,
-  extras: { status?: unknown; statement_id?: string } = {},
+  extras: {
+    status?: unknown;
+    statement_id?: string;
+    metadata?: Record<string, MetricColumnMeta>;
+  } = {},
 ): AnalyticsResultMessage {
   return { type: "result", data, ...extras };
 }