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.

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