Function: useAnalyticsQuery()

useAnalyticsQuery<T, K, F>(queryKey, parameters?, options?): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>>

Subscribe to an analytics query and return its latest result. JSON_ARRAY results stream over SSE (with warehouse-readiness progress); ARROW_STREAM results are fetched as raw Arrow bytes directly from the query endpoint. Integration hook between client and analytics plugin.

Identical requests (same query key, parameters, format, and dev mode) share a single in-flight network request: the first mounting instance starts it, later instances subscribe to the same store entry and see the same result and warehouse-status updates. The request is torn down once its last subscriber unmounts.

The return type is automatically inferred based on the format:

• format: "JSON_ARRAY" (default): Returns typed array from QueryRegistry
• format: "ARROW_STREAM": Returns TypedArrowTable with row type preserved

Note: User context execution is determined by query file naming:

• queryKey.obo.sql: Executes as user (OBO = on-behalf-of / user delegation)
• queryKey.sql: Executes as service principal

Type Parameters

T

T = unknown

K

K extends string = string

F

F extends AnalyticsFormat = "JSON_ARRAY"

Parameters

queryKey

K

Analytics query identifier

parameters?

InferParams<K> | null

Query parameters (type-safe based on QueryRegistry)

options?

UseAnalyticsQueryOptions<F>

Analytics query settings including format

Returns

UseAnalyticsQueryResult<InferResultByFormat<T, K, F>>

Query result state with format-appropriate data type

Examples

JSON_ARRAY format (default)

const { data } = useAnalyticsQuery("spend_data", params);
// data: Array<{ group_key: string; cost_usd: number; ... }> | null

ARROW_STREAM format

const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW_STREAM" });
// data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null