Function: useMetricView()

useMetricView<K, M, D>(key, options): UseMetricViewResult<PickMetricRow<K, M, D>[]>

Subscribe to a Unity Catalog Metric View and return its latest result.

Type Parameters

K

K extends string = string

M

M extends readonly InferMeasureKeys<K>[] = readonly InferMeasureKeys<K>[]

D

D extends readonly InferDimensionKeys<K>[] = readonly []

Parameters

key

K

Metric view identifier

options

UseMetricViewOptions<K, M, D>

Measures (required) plus optional dimensions, filter, orderBy, timeGrain/timeDimension, and limit

Returns

UseMetricViewResult<PickMetricRow<K, M, D>[]>

Metric result state with typed rows, display metadata, and warehouse readiness

Remarks

orderBy and limit interact. With limit, the route completes the ordering with the remaining dimensions so the capped rows are the same rows on every run — pass orderBy to choose WHICH rows (top-N), since the completion only makes the result stable, not ranked. Without limit, orderBy is presentation ordering over the full result and gets no completion.

When a request refetches with the same metric key, measures, and dimensions, the previous data and metadata remain available while loading is true. Changing any of those result-shaping fields clears the previous result.

Example

const { data, metadata } = useMetricView("orders", {
  measures: ["revenue"],
  dimensions: ["region"],
  filter: { member: "region", operator: "in", values: ["EMEA", "APAC"] },
  orderBy: [{ field: "revenue", direction: "DESC" }],
  limit: 10,
});
// JSON_ARRAY preserves SQL scalar cells as strings and nullable columns as null:
// data: Array<{ revenue: string | null; region: string | null }> | null