react-semaphor 0.1.368 → 0.1.370

package/dist/types/data-app-sdk.d.ts

@@ -33,8 +33,295 @@ declare type CalendarContext = {
 
 export declare function createSemaphorQueryExecutor(): SemaphorQueryExecutor;
 
+export declare function defineSemaphorDataApp<TDefinition extends SemaphorDataAppDefinition>(definition: TDefinition): TDefinition;
+
+export declare function defineSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputSpec<TValue>;
+
 export declare function hasSemaphorInputValue(value: unknown): boolean;
 
+declare type MatrixAxisLevelDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    label: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    subtotal?: SemaphorMatrixSubtotalOptions;
+};
+
+declare type MatrixAxisPayload = {
+    id: 'rows' | 'columns';
+    levels: MatrixAxisLevelDescriptor[];
+    nodes: MatrixNode[];
+};
+
+declare type MatrixCapability = 'rowHierarchy' | 'columnHierarchy' | 'rowSubtotals' | 'columnSubtotals' | 'grandTotals' | 'lazyRows' | 'lazyColumns' | 'conditionalFormatting' | 'visualExport' | (string & {});
+
+declare type MatrixCell = {
+    id: string;
+    rowNodeId: string;
+    columnNodeId?: string;
+    measureInstanceId: string;
+    rowPath: MatrixMemberPathSegment[];
+    columnPath: MatrixMemberPathSegment[];
+    rawValue: unknown;
+    presence: MatrixCellPresence;
+    formattedValue?: string;
+    role: MatrixCellRole;
+    aggregateFunction?: SemaphorAggregateFunction;
+    formattingScope: MatrixCellFormattingScope;
+    actions?: MatrixCellAction[];
+};
+
+declare type MatrixCellAction = {
+    kind: 'requestSubgoal' | 'filter' | 'copyValue' | 'explainCalculation' | 'inspectContributingRows' | 'drillThrough' | (string & {});
+    label?: string;
+    payload?: Record<string, unknown>;
+};
+
+declare type MatrixCellFormattingScope = {
+    rowNodeId: string;
+    columnNodeId?: string;
+    measureInstanceId: string;
+    role: MatrixCellRole;
+    rowPath: MatrixMemberPathSegment[];
+    columnPath: MatrixMemberPathSegment[];
+};
+
+declare type MatrixCellPresence = 'present' | 'presentNull' | 'missing' | 'densified';
+
+declare type MatrixCellRole = 'value' | 'rowSubtotal' | 'columnSubtotal' | 'subtotalIntersection' | 'rowGrandTotal' | 'columnGrandTotal' | 'matrixGrandTotal';
+
+declare type MatrixExecutionMetadata = {
+    strategy?: MatrixQueryStrategy;
+    dialect?: SemaphorDialect;
+    rowNodeCount?: number;
+    columnNodeCount?: number;
+    cellCount?: number;
+    groupingSetCount?: number;
+    queryDurationMs?: number;
+    budgetRejected?: boolean;
+    cacheStatus?: 'hit' | 'miss' | 'bypass';
+    [key: string]: unknown;
+};
+
+declare type MatrixExpansionRequest = {
+    axis: 'row' | 'column';
+    path: MatrixMemberPathSegment[];
+    depth?: number;
+};
+
+export declare type MatrixExpansionResponseHints = {
+    rowLazyLoading?: boolean;
+    columnLazyLoading?: boolean;
+    expandableRowNodeIds?: string[];
+    expandableColumnNodeIds?: string[];
+    nextRequests?: MatrixExpansionRequest[];
+};
+
+declare type MatrixFieldDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    field: SemaphorFieldRef;
+    role: 'row' | 'column' | 'measure' | 'sort' | 'filter';
+    label?: string;
+};
+
+declare type MatrixFieldDirectory = {
+    fieldsByInstanceId: Record<string, MatrixFieldDescriptor>;
+};
+
+declare type MatrixFormattingContext = {
+    domains?: Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+    rules?: Array<Record<string, unknown>>;
+};
+
+declare type MatrixGridCell = {
+    id: string;
+    columnId: string;
+    cellId?: string;
+    rawValue: unknown;
+    formattedValue?: string;
+    presence: MatrixCellPresence;
+    role: MatrixCellRole;
+    measureInstanceId: string;
+    rowPath: MatrixMemberPathSegment[];
+    columnPath: MatrixMemberPathSegment[];
+};
+
+declare type MatrixGridColumn = {
+    id: string;
+    label: string;
+    columnNodeId?: string;
+    columnPath: MatrixMemberPathSegment[];
+    measureInstanceId: string;
+    role: 'value' | 'columnSubtotal' | 'columnGrandTotal';
+};
+
+declare type MatrixGridHeaderCell = {
+    id: string;
+    label: string;
+    role: 'rowHeader' | 'columnHeader' | 'measureHeader' | 'subtotal' | 'grandTotal';
+    colSpan: number;
+    rowSpan: number;
+    columnPath: MatrixMemberPathSegment[];
+    measureInstanceId?: string;
+};
+
+declare type MatrixGridHeaderRow = {
+    id: string;
+    cells: MatrixGridHeaderCell[];
+};
+
+export declare type MatrixGridProjection = {
+    schemaVersion: 1;
+    shape: MatrixShape;
+    rowHeaderLevels: MatrixGridRowHeaderLevel[];
+    columnHeaderRows: MatrixGridHeaderRow[];
+    columns: MatrixGridColumn[];
+    rows: MatrixGridRow[];
+};
+
+declare type MatrixGridRow = {
+    id: string;
+    rowNodeId: string;
+    rowPath: MatrixMemberPathSegment[];
+    depth: number;
+    label: string;
+    role: 'value' | 'rowSubtotal' | 'rowGrandTotal';
+    isExpanded?: boolean;
+    hasChildren?: boolean;
+    cells: MatrixGridCell[];
+};
+
+declare type MatrixGridRowHeaderLevel = {
+    id: string;
+    label: string;
+    fieldInstanceId: string;
+};
+
+declare type MatrixMeasureDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    label: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
+declare type MatrixMeasureSemantics = {
+    kind: 'additive';
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'semiAdditive';
+    aggregate?: SemaphorAggregateFunction;
+    grain?: SemaphorTimeGrain;
+} | {
+    kind: 'nonAdditive';
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'ratio';
+    numeratorMeasureInstanceId?: string;
+    denominatorMeasureInstanceId?: string;
+} | {
+    kind: 'custom';
+    expressionId?: string;
+};
+
+declare type MatrixMemberPathSegment = {
+    instanceId: string;
+    fieldKey: string;
+    value: unknown;
+    label: string;
+};
+
+declare type MatrixNode = {
+    id: string;
+    axis: 'row' | 'column';
+    path: MatrixMemberPathSegment[];
+    level: number;
+    label: string;
+    value: unknown;
+    parentId?: string;
+    hasChildren: boolean;
+    isExpanded?: boolean;
+    isSubtotal?: boolean;
+    isGrandTotal?: boolean;
+    subtotalFunction?: SemaphorAggregateFunction;
+    childCount?: number;
+    actions?: MatrixNodeAction[];
+};
+
+declare type MatrixNodeAction = {
+    kind: 'expand' | 'collapse' | 'requestSubgoal' | 'filter' | 'drillThrough' | 'openRelatedRecords' | (string & {});
+    label?: string;
+    payload?: Record<string, unknown>;
+};
+
+declare type MatrixPageInfo = {
+    rowOffset?: number;
+    rowLimit?: number;
+    columnOffset?: number;
+    columnLimit?: number;
+    hasMoreRows?: boolean;
+    hasMoreColumns?: boolean;
+};
+
+export declare type MatrixPayload = {
+    kind: 'matrixPayload';
+    schemaVersion: 1;
+    shape: MatrixShape;
+    capabilities: MatrixCapability[];
+    executionMetadata: MatrixExecutionMetadata;
+    axes: {
+        rows: MatrixAxisPayload;
+        columns: MatrixAxisPayload;
+    };
+    measures: MatrixMeasureDescriptor[];
+    measureSemantics: Record<string, MatrixMeasureSemantics>;
+    fieldDirectory: MatrixFieldDirectory;
+    rowNodes: MatrixNode[];
+    columnNodes: MatrixNode[];
+    cells: MatrixCell[];
+    totals: MatrixTotals;
+    sort: MatrixResolvedSort[];
+    formattingContext: MatrixFormattingContext;
+    pageInfo?: MatrixPageInfo;
+    warnings?: MatrixWarning[];
+};
+
+declare type MatrixQueryStrategy = 'tall' | 'wide' | 'lazy' | 'export';
+
+declare type MatrixResolvedSort = {
+    id: string;
+    axis: 'row' | 'column';
+    targetInstanceId?: string;
+    direction: 'asc' | 'desc';
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+    by: SemaphorMatrixSortRule['by'];
+};
+
+declare type MatrixShape = 'hierarchical' | 'pivot';
+
+declare type MatrixTotals = {
+    rows?: boolean;
+    columns?: boolean;
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+};
+
+declare type MatrixWarning = {
+    code: string;
+    message: string;
+    path?: string;
+    severity?: 'info' | 'warning' | 'error';
+};
+
 export declare function normalizeSemaphorAnalysisPayload(payload: SemaphorAnalysisPayload | undefined | null): SemaphorAnalysisPayload;
 
 export declare function normalizeSemaphorAnalysisQueryOptions(value: unknown, options?: {
@@ -52,6 +339,18 @@ export declare function normalizeSemaphorInputOptions(options?: Array<{
 
 export declare function readWindowRuntime(): SemaphorDataAppWindowRuntime | undefined;
 
+export declare const semaphor: {
+    filter<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: Omit<SemaphorFilterInputSpec<TValue>, "kind">): SemaphorFilterInputSpec<TValue>;
+    control<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorControlBuilderSpec<TValue>): SemaphorControlInputSpec<TValue>;
+    sqlParam<TValue extends SemaphorSqlParameterValue = SemaphorSqlParameterValue>(spec: SemaphorSqlParamInputSpec<TValue>): SemaphorControlInputSpec<TValue>;
+    metric(spec: SemaphorMetricQuerySpec): SemaphorMetricQueryDefinition;
+    analysis(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryDefinition;
+    records(spec: SemaphorRecordsQuerySpec): SemaphorRecordsQueryDefinition;
+    inputOptions(spec: SemaphorInputOptionsQuerySpec): SemaphorInputOptionsQueryDefinition;
+    sql(spec: SemaphorSqlQuerySpec): SemaphorSqlQueryDefinition;
+    matrix(spec: SemaphorMatrixQuerySpec): SemaphorMatrixQueryDefinition;
+};
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -94,6 +393,10 @@ export declare type SemaphorAnalysisPayload = {
     [key: string]: unknown;
 };
 
+export declare type SemaphorAnalysisQueryDefinition = SemaphorAnalysisQuerySpec & {
+    queryKind: 'analysis';
+};
+
 export declare type SemaphorAnalysisQueryOptions = {
     chartTitle?: string;
     chartType?: string;
@@ -178,7 +481,7 @@ declare type SemaphorAnalyticsFilterBase = {
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
-declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
 
 declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
     operator: SemaphorAnalyticsNullFilterOperator;
@@ -203,7 +506,7 @@ declare type SemaphorAnalyticsRepairHint = {
     recommendedNextStep: string;
 };
 
-declare type SemaphorAnalyticsResult = SemaphorMetricResult | SemaphorRecordsResult | SemaphorInputOptionsResult | SemaphorSqlResult;
+declare type SemaphorAnalyticsResult = SemaphorMetricResult | SemaphorRecordsResult | SemaphorInputOptionsResult | SemaphorSqlResult | SemaphorMatrixResult;
 
 declare type SemaphorAnalyticsResultBase = {
     intentId?: string;
@@ -212,6 +515,7 @@ declare type SemaphorAnalyticsResultBase = {
     rowCount?: number;
     rowLimitExceeded?: boolean;
     limit?: number;
+    pagination?: SemaphorPaginationMetadata;
 };
 
 declare type SemaphorAnalyticsValidationCode = 'missing_source' | 'invalid_source_kind' | 'missing_semantic_domain' | 'missing_dataset_name' | 'missing_connection_id' | 'missing_table_name' | 'missing_sql' | 'missing_metric' | 'missing_record_fields' | 'missing_input_options_field' | 'invalid_metric' | 'invalid_metric_list' | 'invalid_date_field' | 'invalid_dimension' | 'invalid_metric_dimensions' | 'conflicting_sql' | 'sql_policy_violation' | 'unsupported_intent_for_adapter' | 'invalid_analytics_kind' | 'invalid_analytics_intent';
@@ -236,6 +540,8 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
+export declare type SemaphorAnyQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryResult<TRecord>;
+
 declare type SemaphorCompiledQuery = {
     kind: 'config';
     queryId: string;
@@ -263,6 +569,10 @@ declare type SemaphorCompiledQuery = {
     analyticsIntent?: SemaphorAnalyticsIntent;
 };
 
+export declare type SemaphorControlBuilderSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = Omit<SemaphorControlInputSpec<TValue>, 'kind'> & {
+    role: SemaphorControlRole;
+};
+
 export declare type SemaphorControlInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorInputBase<TValue> & {
     kind: 'control';
     role: SemaphorControlRole;
@@ -272,34 +582,21 @@ export declare type SemaphorControlRole = 'grain' | 'metric' | 'dimension' | 'ag
 
 export declare const SemaphorDataAppContext: Context<SemaphorDataAppRuntime>;
 
+export declare type SemaphorDataAppDefinition = {
+    id?: string;
+    title?: string;
+    description?: string;
+    inputs?: Record<string, SemaphorInputSpec> | SemaphorInputSpec[];
+    queries?: Record<string, SemaphorQueryDefinition>;
+    views: SemaphorDataAppViewDefinition[];
+};
+
 export declare type SemaphorDataAppFieldCatalog = {
     source: SemaphorSourceRef;
     sourceAliases?: SemaphorSourceRef[];
     fields: SemaphorFieldRef[];
 };
 
-export declare type SemaphorDataAppHookSpec = {
-    hook: 'useSemaphorAnalysis';
-    spec: SemaphorAnalysisQuerySpec;
-} | {
-    hook: 'useSemaphorMetric';
-    spec: SemaphorMetricQuerySpec;
-} | {
-    hook: 'useSemaphorRecords';
-    spec: SemaphorRecordsQuerySpec;
-} | {
-    hook: 'useSemaphorInputOptions';
-    spec: SemaphorInputOptionsQuerySpec;
-};
-
-export declare type SemaphorDataAppHookValidation = {
-    hook: SemaphorDataAppHookSpec['hook'];
-    hookId?: string;
-    intent?: SemaphorAnalyticsIntent;
-    diagnostics: SemaphorDataAppValidationDiagnostic[];
-    executionResult: SemaphorAnalyticsExecutionResult;
-};
-
 export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
 
 export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext & {
@@ -307,17 +604,30 @@ export declare type SemaphorDataAppProviderProps = SemaphorQueryExecutorContext
     children: ReactNode;
 };
 
+export declare type SemaphorDataAppQuerySpecEnvelope = {
+    queryHook: 'useSemaphorQuery';
+    spec: SemaphorQueryDefinition;
+};
+
+export declare type SemaphorDataAppQueryValidation = {
+    queryHook: SemaphorDataAppQuerySpecEnvelope['queryHook'];
+    queryId?: string;
+    intent?: SemaphorAnalyticsIntent;
+    diagnostics: SemaphorDataAppValidationDiagnostic[];
+    executionResult: SemaphorAnalyticsExecutionResult;
+};
+
 export declare type SemaphorDataAppRuntime = SemaphorQueryExecutorContext & {
     executor?: SemaphorQueryExecutor;
 };
 
 export declare type SemaphorDataAppValidationDiagnostic = {
     severity: 'error' | 'warning';
-    code: 'invalid_hook_spec' | 'invalid_analytics_intent' | 'invalid_source_ref' | 'missing_field' | 'unsupported_input_filter_composition' | string;
+    code: 'invalid_query_spec' | 'invalid_analytics_intent' | 'invalid_source_ref' | 'missing_field' | 'unsupported_input_filter_composition' | string;
     message: string;
     path?: string;
-    hook?: SemaphorDataAppHookSpec['hook'];
-    hookId?: string;
+    queryHook?: SemaphorDataAppQuerySpecEnvelope['queryHook'];
+    queryId?: string;
     intentId?: string;
     source?: SemaphorSourceRef;
     field?: SemaphorFieldRef;
@@ -326,11 +636,19 @@ export declare type SemaphorDataAppValidationDiagnostic = {
 export declare type SemaphorDataAppValidationResult = {
     ok: boolean;
     diagnostics: SemaphorDataAppValidationDiagnostic[];
-    hooks: SemaphorDataAppHookValidation[];
+    queries: SemaphorDataAppQueryValidation[];
     intents: SemaphorAnalyticsIntent[];
     executionResults: SemaphorAnalyticsExecutionResult[];
 };
 
+export declare type SemaphorDataAppViewDefinition<TQuery extends SemaphorQueryDefinition = SemaphorQueryDefinition> = {
+    id: string;
+    title?: string;
+    description?: string;
+    query: TQuery;
+    inputs?: SemaphorInputReference[];
+};
+
 declare type SemaphorDataAppWindowRuntime = {
     apiBaseUrl?: string;
     dataApiBaseUrl?: string;
@@ -347,6 +665,14 @@ declare type SemaphorExecutionFieldRef = SemaphorFieldRef & {
     aggregateSource?: SemaphorMetricAggregateSource;
 };
 
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+
 export declare type SemaphorFieldRef = {
     name: string;
     label?: string;
@@ -368,12 +694,17 @@ declare type SemaphorInputBase<TValue extends SemaphorInputValue> = {
     label?: string;
     value?: TValue;
     defaultValue?: TValue;
-    onValueChange?: (value: TValue | undefined) => void;
+    onValueChange?: {
+        bivarianceHack(value: TValue | undefined): void;
+    }['bivarianceHack'];
     options?: Array<SemaphorInputOption | SemaphorOptionValue>;
 };
 
 declare type SemaphorInputBinding = {
     inputId: string;
+    kind?: 'filter' | 'control';
+    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    operator?: SemaphorInputOperator;
     field?: SemaphorFieldRef;
 };
 
@@ -420,6 +751,10 @@ export declare type SemaphorInputOptionsPayload = {
     executionResult?: SemaphorAnalyticsExecutionResult;
 };
 
+export declare type SemaphorInputOptionsQueryDefinition = SemaphorInputOptionsQuerySpec & {
+    queryKind: 'inputOptions';
+};
+
 export declare type SemaphorInputOptionsQueryResult = SemaphorQueryState & SemaphorInputOptionsPayload & {
     id?: string;
     intent?: Extract<SemaphorAnalyticsIntent, {
@@ -444,12 +779,196 @@ declare type SemaphorInputOptionsResult = SemaphorAnalyticsResultBase & {
     }>;
 };
 
-export declare type SemaphorInputReference = SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle;
+export declare type SemaphorInputReference = SemaphorInputSpec | SemaphorInputBinding | SemaphorActiveInput | SemaphorInputHandle;
 
 export declare type SemaphorInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = SemaphorFilterInputSpec<TValue> | SemaphorControlInputSpec<TValue>;
 
 export declare type SemaphorInputValue = SemaphorScalar | SemaphorScalar[];
 
+declare type SemaphorMatrixAxisExpansionOptions = {
+    defaultDepth?: number;
+    lazy?: boolean;
+    expandedPaths?: SemaphorMatrixMemberPathSegment[][];
+};
+
+export declare type SemaphorMatrixAxisLevel = {
+    id?: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    label?: string;
+    subtotal?: boolean | SemaphorMatrixSubtotalOptions;
+    sortBy?: SemaphorMatrixAxisSortRule;
+};
+
+export declare type SemaphorMatrixAxisLevelInput = SemaphorQueryField | SemaphorMatrixAxisLevel;
+
+declare type SemaphorMatrixAxisSortRule = {
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+export declare type SemaphorMatrixDisplayLimitOptions = {
+    rows?: SemaphorMatrixDisplayLimitRule;
+    columns?: SemaphorMatrixDisplayLimitRule;
+};
+
+declare type SemaphorMatrixDisplayLimitRule = {
+    limit: number;
+    by?: 'label' | 'value';
+    direction?: 'top' | 'bottom';
+    others?: boolean | {
+        label?: string;
+    };
+};
+
+export declare type SemaphorMatrixExpansionOptions = {
+    rows?: SemaphorMatrixAxisExpansionOptions;
+    columns?: SemaphorMatrixAxisExpansionOptions;
+};
+
+export declare type SemaphorMatrixIntent = {
+    kind: 'matrix';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorMatrixAxisLevel[];
+    columns?: SemaphorMatrixAxisLevel[];
+    values: SemaphorMatrixValueField[];
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputBinding[];
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixLayoutOptions;
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorMatrixLayoutOptions = {
+    hierarchy?: 'compact' | 'tabular' | 'outline';
+    valuesPlacement?: 'columns' | 'rows';
+    stickyRowHeaders?: boolean;
+    stickyColumnHeaders?: boolean;
+};
+
+declare type SemaphorMatrixMemberPathSegment = {
+    levelId: string;
+    value: unknown;
+};
+
+export declare type SemaphorMatrixPayload = {
+    payload?: MatrixPayload;
+    grid?: MatrixGridProjection;
+    expansion?: MatrixExpansionResponseHints;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+};
+
+export declare type SemaphorMatrixQueryDefinition = SemaphorMatrixQuerySpec & {
+    queryKind: 'matrix';
+};
+
+export declare type SemaphorMatrixQueryResult = SemaphorQueryState & SemaphorMatrixPayload & {
+    id?: string;
+    intent?: SemaphorMatrixIntent;
+};
+
+export declare type SemaphorMatrixQuerySpec = Omit<SemaphorMatrixIntent, 'kind' | 'version' | 'rows' | 'columns' | 'values' | 'source' | 'inputs'> & {
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorNonEmptyArray<SemaphorMatrixAxisLevelInput>;
+    columns?: SemaphorMatrixAxisLevelInput[];
+    values: SemaphorNonEmptyArray<SemaphorMatrixValueFieldInput>;
+    inputs?: SemaphorInputReference[];
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixIntent['layout'];
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
+    kind: 'matrix';
+    intent: SemaphorMatrixIntent;
+    payload: MatrixPayload;
+    grid: MatrixGridProjection;
+    expansion?: MatrixExpansionResponseHints;
+};
+
+export declare type SemaphorMatrixSortRule = {
+    axis: 'row' | 'column';
+    targetId?: string;
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    } | {
+        kind: 'value';
+        valueId: string;
+        rowPath?: SemaphorMatrixMemberPathSegment[];
+        columnPath?: SemaphorMatrixMemberPathSegment[];
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+export declare type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+
+declare type SemaphorMatrixSubtotalOptions = {
+    enabled?: boolean;
+    position?: 'before' | 'after';
+    label?: string;
+};
+
+declare type SemaphorMatrixTotalCalculation = {
+    kind: 'defaultAggregate';
+} | {
+    kind: 'blank';
+} | {
+    kind: 'labelOnly';
+    label?: string;
+} | {
+    kind: 'customAggregate';
+    aggregate: SemaphorAggregateFunction;
+} | {
+    kind: 'percentOfParent';
+} | {
+    kind: 'percentOfGrandTotal';
+} | {
+    kind: 'customExpression';
+    expressionId: string;
+};
+
+export declare type SemaphorMatrixTotalOptions = {
+    rows?: boolean | 'perLevel';
+    columns?: boolean | 'perLevel';
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+    rowPosition?: 'top' | 'bottom';
+    columnPosition?: 'left' | 'right';
+};
+
+export declare type SemaphorMatrixValueField = {
+    id?: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
+export declare type SemaphorMatrixValueFieldInput = SemaphorQueryField | SemaphorMatrixValueField;
+
 declare type SemaphorMetricAggregateSource = 'semantic_model' | 'caller_override' | 'default_sum';
 
 declare type SemaphorMetricAnalysis = {
@@ -500,6 +1019,10 @@ export declare type SemaphorMetricPayload = {
     executionResult?: SemaphorAnalyticsExecutionResult;
 };
 
+export declare type SemaphorMetricQueryDefinition = SemaphorMetricQuerySpec & {
+    queryKind: 'metric';
+};
+
 export declare type SemaphorMetricQueryResult = SemaphorQueryState & SemaphorMetricPayload & {
     id?: string;
     intent?: SemaphorMetricIntent;
@@ -534,6 +1057,20 @@ export declare type SemaphorNonEmptyArray<T> = [T, ...T[]];
 
 export declare type SemaphorOptionValue = string | number | boolean;
 
+export declare type SemaphorPaginationMetadata = {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    totalCount: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+};
+
+export declare type SemaphorPaginationRequest = {
+    page: number;
+    pageSize: number;
+};
+
 declare type SemaphorProtocolIssue = {
     code: string;
     message: string;
@@ -542,6 +1079,8 @@ declare type SemaphorProtocolIssue = {
 
 declare type SemaphorProtocolVersion = 1;
 
+export declare type SemaphorQueryDefinition = SemaphorMetricQueryDefinition | SemaphorAnalysisQueryDefinition | SemaphorRecordsQueryDefinition | SemaphorInputOptionsQueryDefinition | SemaphorSqlQueryDefinition | SemaphorMatrixQueryDefinition;
+
 export declare type SemaphorQueryExecutor = {
     executeAnalysis?(intent: SemaphorMetricIntent, context: SemaphorQueryExecutorContext, options?: SemaphorAnalysisQueryOptions): Promise<SemaphorAnalysisPayload>;
     executeMetric(intent: SemaphorMetricIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorMetricPayload>;
@@ -549,6 +1088,8 @@ export declare type SemaphorQueryExecutor = {
     executeInputOptions(intent: Extract<SemaphorAnalyticsIntent, {
         kind: 'inputOptions';
     }>, context: SemaphorQueryExecutorContext): Promise<SemaphorInputOptionsPayload>;
+    executeSql?<TRecord extends Record<string, unknown> = Record<string, unknown>>(intent: SemaphorSqlIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorSqlPayload<TRecord>>;
+    executeMatrix?(intent: SemaphorMatrixIntent, context: SemaphorQueryExecutorContext): Promise<SemaphorMatrixPayload>;
 };
 
 export declare type SemaphorQueryExecutorContext = {
@@ -566,6 +1107,14 @@ export declare type SemaphorQueryOrderBy = {
 
 declare type SemaphorQueryPath = 'query_spec' | 'sql' | 'sql_python';
 
+export declare type SemaphorQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorMetricQueryResult | SemaphorAnalysisQueryResult | SemaphorRowsQueryResult<TRecord> | SemaphorInputOptionsQueryResult | SemaphorMatrixQueryResult;
+
+export declare type SemaphorQueryResultFor<TQuery extends SemaphorQueryDefinition, TRecord extends Record<string, unknown> = Record<string, unknown>> = TQuery extends SemaphorMetricQueryDefinition ? SemaphorMetricQueryResult : TQuery extends SemaphorAnalysisQueryDefinition ? SemaphorAnalysisQueryResult : TQuery extends SemaphorRecordsQueryDefinition ? SemaphorRecordsQueryResult<TRecord> : TQuery extends SemaphorInputOptionsQueryDefinition ? SemaphorInputOptionsQueryResult : TQuery extends SemaphorSqlQueryDefinition ? SemaphorSqlQueryResult<TRecord> : TQuery extends SemaphorMatrixQueryDefinition ? SemaphorMatrixQueryResult : never;
+
+export declare type SemaphorQueryRuntimeOptions = {
+    inputs?: SemaphorInputReference[];
+};
+
 export declare type SemaphorQuerySourceSpec = {
     source: SemaphorSourceRef;
 };
@@ -588,6 +1137,7 @@ declare type SemaphorRecordsBaseQuerySpec = SemaphorQuerySourceSpec & {
     orderBy?: SemaphorRecordsOrderBy;
     inputs?: SemaphorInputReference[];
     limit?: number;
+    pagination?: SemaphorPaginationRequest;
 };
 
 export declare type SemaphorRecordsField = SemaphorFieldRef & {
@@ -606,6 +1156,7 @@ declare type SemaphorRecordsIntent = {
     timeWindow?: SemaphorTimeWindow;
     filters?: SemaphorAnalyticsFilter[];
     limit?: number;
+    pagination?: SemaphorPaginationRequest;
     orderBy?: {
         field: SemaphorFieldRef;
         direction: 'asc' | 'desc';
@@ -619,9 +1170,14 @@ export declare type SemaphorRecordsPayload<TRecord extends Record<string, unknow
     records: TRecord[];
     columns?: SemaphorResultColumn[];
     rowCount?: number;
+    pagination?: SemaphorPaginationMetadata;
     executionResult?: SemaphorAnalyticsExecutionResult;
 };
 
+export declare type SemaphorRecordsQueryDefinition = SemaphorRecordsQuerySpec & {
+    queryKind: 'records';
+};
+
 export declare type SemaphorRecordsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryState & SemaphorRecordsPayload<TRecord> & {
     id?: string;
     intent?: SemaphorRecordsIntent;
@@ -688,8 +1244,14 @@ export declare type SemaphorResultColumn = {
     source?: SemaphorFieldRef['source'];
 };
 
+export declare type SemaphorRowsQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorRecordsQueryResult<TRecord> | SemaphorSqlQueryResult<TRecord>;
+
 export declare type SemaphorScalar = string | number | boolean | null;
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 export declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -722,14 +1284,53 @@ declare type SemaphorSqlIntent = {
         kind: 'sql';
     }>;
     sql: string;
-    parameters?: Record<string, unknown>;
+    defaultParameters?: Record<string, unknown>;
     pythonCode?: string;
     limit?: number;
+    pagination?: SemaphorPaginationRequest;
     rationale?: string;
     fields?: SemaphorFieldRef[];
     inputs?: SemaphorInputBinding[];
 };
 
+export declare type SemaphorSqlParameterValue = SemaphorScalar | SemaphorScalar[];
+
+export declare type SemaphorSqlParamInputSpec<TValue extends SemaphorInputValue = SemaphorInputValue> = Omit<SemaphorControlInputSpec<TValue>, 'kind' | 'role'> & {
+    defaultValue?: TValue;
+};
+
+export declare type SemaphorSqlPayload<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    records: TRecord[];
+    columns?: SemaphorResultColumn[];
+    rowCount?: number;
+    pagination?: SemaphorPaginationMetadata;
+    output?: string;
+    rowLimitExceeded?: boolean;
+    executionResult?: SemaphorAnalyticsExecutionResult;
+};
+
+export declare type SemaphorSqlQueryDefinition = SemaphorSqlQuerySpec & {
+    queryKind: 'sql';
+};
+
+export declare type SemaphorSqlQueryResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorQueryState & SemaphorSqlPayload<TRecord> & {
+    id?: string;
+    intent?: SemaphorSqlIntent;
+};
+
+export declare type SemaphorSqlQuerySpec = SemaphorSqlSourceSpec & {
+    id?: string;
+    label?: string;
+    sql: string;
+    defaultParameters?: Record<string, SemaphorSqlParameterValue>;
+    pythonCode?: string;
+    fields?: SemaphorFieldRef[];
+    inputs?: SemaphorInputReference[];
+    limit?: number;
+    pagination?: SemaphorPaginationRequest;
+    rationale?: string;
+};
+
 declare type SemaphorSqlResult = SemaphorAnalyticsResultBase & {
     kind: 'sql';
     columns: SemaphorRecordsResult['columns'];
@@ -741,6 +1342,12 @@ declare type SemaphorSqlResult = SemaphorAnalyticsResultBase & {
     };
 };
 
+export declare type SemaphorSqlSourceSpec = {
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+};
+
 declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 
 export declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
@@ -766,26 +1373,37 @@ export declare function toSemaphorInputSpec<TValue extends SemaphorInputValue =
     label?: string;
     field?: SemaphorFieldRef;
     operator?: SemaphorInputOperator;
+    controlRole?: SemaphorControlRole;
 };
 
+export declare function toSemaphorMatrixIntent(spec: SemaphorMatrixQuerySpec): SemaphorMatrixIntent;
+
 export declare function toSemaphorMetricIntent(spec: SemaphorMetricQuerySpec): SemaphorMetricIntent;
 
 export declare function toSemaphorRecordsIntent(spec: SemaphorRecordsQuerySpec): SemaphorRecordsIntent;
 
-export declare function useSemaphorAnalysis(spec: SemaphorAnalysisQuerySpec): SemaphorAnalysisQueryResult;
+export declare function toSemaphorSqlIntent(spec: SemaphorSqlQuerySpec): SemaphorSqlIntent;
 
 export declare function useSemaphorDataAppRuntime(): SemaphorDataAppRuntime;
 
 export declare function useSemaphorInput<TValue extends SemaphorInputValue = SemaphorInputValue>(spec: SemaphorInputSpec<TValue>): SemaphorInputHandle;
 
-export declare function useSemaphorInputOptions(spec: SemaphorInputOptionsQuerySpec): SemaphorInputOptionsQueryResult;
+export declare function useSemaphorInputs(specs: readonly SemaphorInputSpec[]): SemaphorInputHandle[];
+
+export declare function useSemaphorQuery(spec: SemaphorMetricQueryDefinition, options?: SemaphorQueryRuntimeOptions): SemaphorMetricQueryResult;
+
+export declare function useSemaphorQuery(spec: SemaphorAnalysisQueryDefinition, options?: SemaphorQueryRuntimeOptions): SemaphorAnalysisQueryResult;
+
+export declare function useSemaphorQuery<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorRecordsQueryDefinition, options?: SemaphorQueryRuntimeOptions): SemaphorRecordsQueryResult<TRecord>;
+
+export declare function useSemaphorQuery(spec: SemaphorInputOptionsQueryDefinition, options?: SemaphorQueryRuntimeOptions): SemaphorInputOptionsQueryResult;
 
-export declare function useSemaphorMetric(spec: SemaphorMetricQuerySpec): SemaphorMetricQueryResult;
+export declare function useSemaphorQuery<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorSqlQueryDefinition, options?: SemaphorQueryRuntimeOptions): SemaphorSqlQueryResult<TRecord>;
 
-export declare function useSemaphorRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorRecordsQuerySpec): SemaphorRecordsQueryResult<TRecord>;
+export declare function useSemaphorQuery(spec: SemaphorMatrixQueryDefinition, options?: SemaphorQueryRuntimeOptions): SemaphorMatrixQueryResult;
 
-export declare function validateSemaphorDataAppHookSpecs(input: {
-    hooks: SemaphorDataAppHookSpec[];
+export declare function validateSemaphorDataAppQuerySpecs(input: {
+    queries: SemaphorDataAppQuerySpecEnvelope[];
     fieldCatalogs?: SemaphorDataAppFieldCatalog[];
     requireFieldCatalog?: boolean;
     validateTimezone?: SemaphorAnalysisTimezoneValidator;