react-semaphor 0.1.309 → 0.1.311

package/dist/types/types.d.ts

@@ -4,7 +4,17 @@ import { JSX } from 'react';
 
 export declare type AggregateCalc = 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'COUNT' | 'COUNT_DISTINCT';
 
-declare type AggregateFunction = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+/**
+ * Configuration for which aggregate functions to use and at which levels (by Field.id)
+ */
+export declare interface AggregateConfig {
+    functions: AggregateFunction[];
+    levels?: string[];
+}
+
+export declare type AggregateFunction = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+export declare type AggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
 
 declare type AIContext = {
     selectedEntities: SelectedEntities;
@@ -347,6 +357,30 @@ export declare type CacheConfig = {
     status: 'on' | 'on-refresh' | 'off';
 };
 
+/**
+ * Special entity name marker for calculated fields.
+ *
+ * Calculated fields are virtual/derived fields created from SQL expressions
+ * combining other metrics. They don't belong to any physical table/dataset.
+ *
+ * This marker is used to:
+ * 1. Identify calculated fields throughout the application
+ * 2. Exclude them from join resolution (since they're expressions, not table columns)
+ * 3. Distinguish them from actual table names in the system
+ *
+ * The join resolver filters out any fields with this entityName to avoid
+ * attempting to join to a non-existent "calculated" table.
+ *
+ * @example
+ * // A calculated field combining two metrics:
+ * {
+ *   name: "profit",
+ *   entityName: CALCULATED_FIELD_ENTITY_MARKER,
+ *   expression: "(SUM(revenue) - SUM(cost))"
+ * }
+ */
+export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD";
+
 /**
  * Formula metadata for calculated fields (UI-only metadata)
  * This is supplementary data to help the UI display and edit calculated fields.
@@ -355,7 +389,7 @@ export declare type CacheConfig = {
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
  */
-declare interface CalculatedFieldFormula {
+export declare interface CalculatedFieldFormula {
     operation: CalculatedFieldOperation;
     /**
      * Array of full MetricField objects used as inputs to the calculated field.
@@ -387,7 +421,7 @@ declare interface CalculatedFieldFormula {
 /**
  * Operations supported for calculated fields
  */
-declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
+export declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
 
 /**
  * Calendar context for timezone-aware date operations.
@@ -418,9 +452,9 @@ export declare type CalendarContext = {
     };
 };
 
-declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | StringCanonicalFormat;
+export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | StringCanonicalFormat;
 
-declare interface CardConfig {
+export declare interface CardConfig {
     groupByColumns?: GroupByField[];
     metricColumns?: MetricField[];
     pivotByColumns?: PivotByField[];
@@ -487,7 +521,7 @@ declare interface CardInteractionConfig {
     drillHierarchies?: DrillHierarchy[];
 }
 
-declare type CardMode = 'explorer' | 'dev';
+export declare type CardMode = 'explorer' | 'dev';
 
 declare type CardWithContent = BaseCustomCard & {
     content: React.FC<{
@@ -589,7 +623,7 @@ declare interface ColumnSettings {
     minWidth?: number;
     maxWidth?: number;
     textOverflow?: 'ellipsis' | 'wrap' | 'clip';
-    textWrap: 'wrap' | 'nowrap';
+    textWrap: ColumnTextWrap;
     /** Deprecated/inert. Totals are controlled by tablePrefs.tableStyle.totals. */
     totalsBehavior?: TotalsBehavior;
     totalsLabel?: string;
@@ -628,6 +662,8 @@ declare interface ColumnSettings {
 
 declare type ColumnSettingsMap = Record<string, ColumnSettings>;
 
+declare type ColumnTextWrap = 'default' | 'truncate' | 'wrap' | 'nowrap' | 'preserve';
+
 declare type ColumnType = 'string' | 'number' | 'date';
 
 declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
@@ -720,7 +756,9 @@ export declare type ConnectionPolicy = {
     params: Params;
 };
 
-declare type ConnectionType = 'GoogleSheets' | 'FileUpload' | 'MySQL' | 'MSSQL' | 'PostgreSQL' | 'BigQuery' | 'Redshift' | 'Snowflake' | 'S3' | 'clickhouse' | 'S3Tables' | 'API' | 'none';
+export declare type ConnectionType = 'GoogleSheets' | 'FileUpload' | 'MySQL' | 'MSSQL' | 'PostgreSQL' | 'BigQuery' | 'Redshift' | 'Snowflake' | 'S3' | 'clickhouse' | 'S3Tables' | 'API' | 'none';
+
+export declare type ContainerId = 'groupBy' | 'metrics' | 'pivotBy' | 'sortBy' | 'detailColumns' | 'source';
 
 export declare type ContextSource = {
     kind: AlertContextSourceKind;
@@ -1049,7 +1087,7 @@ export declare type DashboardProps = {
     preferences?: DashboardPreferences;
 };
 
-declare interface DatabaseEntityReference {
+export declare interface DatabaseEntityReference {
     connectionId: string;
     connectionType: ConnectionType;
     type: EntityType;
@@ -1060,27 +1098,27 @@ declare interface DatabaseEntityReference {
     name: string;
 }
 
-declare type DatabaseEntityType = 'table' | 'view' | 'materialized view';
+export declare type DatabaseEntityType = 'table' | 'view' | 'materialized view';
 
-declare interface DataModelEntityReference extends DatabaseEntityReference {
+export declare interface DataModelEntityReference extends DatabaseEntityReference {
     type: 'model';
     id: string;
     label: string;
     description: string;
 }
 
-declare interface DatasetEntityReference extends DatabaseEntityReference {
+export declare interface DatasetEntityReference extends DatabaseEntityReference {
     type: 'dataset';
     datasetType: 'physical' | 'virtual';
-    datamodelId: string;
-    sql: string;
+    datamodelId?: string | null;
+    sql?: string | null;
     id: string;
     domainId: string;
     label: string;
-    description: string;
+    description?: string;
 }
 
-declare interface DataSource {
+export declare interface DataSource {
     connectionId: string;
     semanticDomainId?: string;
     connectionType: string;
@@ -1093,7 +1131,9 @@ declare interface DataSource {
     selectedEntities: SelectedEntities;
 }
 
-declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM-DD HH:mm", "YYYY-MM-DD HH:mm:ss", "YYYY-MM-DD HH:mm Z", "YYYY-MM-DD HH:mm:ss Z", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
+export declare type DataType = 'string' | 'number' | 'date' | 'datetime' | 'boolean' | 'json' | 'geo';
+
+export declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM-DD HH:mm", "YYYY-MM-DD HH:mm:ss", "YYYY-MM-DD HH:mm Z", "YYYY-MM-DD HH:mm:ss Z", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
 
 declare type DateCanonicalFormat = {
     type: 'date';
@@ -1106,7 +1146,14 @@ declare type DateCanonicalFormat = {
     suffix?: string;
 };
 
-declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
+export declare type DateComparisonOperation = Extract<Operation, '=' | '!=' | '>' | '>=' | '<' | '<=' | 'between' | 'not between' | 'is null' | 'is not null'>;
+
+export declare type DateFormatOption = {
+    value: DateFormatValue;
+    label: string;
+};
+
+export declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
 
 export declare type DateOptions = {
     locale: string;
@@ -1114,9 +1161,11 @@ export declare type DateOptions = {
     options: Intl.DateTimeFormatOptions;
 };
 
-declare type DateSelectionMode = 'range' | 'months';
+export declare type DateSelectionMode = 'range' | 'months';
+
+export declare type DateUnit = RelativeDateFilter['unit'];
 
-declare type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type DateUnit_2 = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
 /**
  * Default CalendarContext when not provided.
@@ -1141,7 +1190,7 @@ export declare type DeliveryConfig = {
  * Unlike GroupByField, DetailField does not support aggregation or granularity.
  * Columns are selected and displayed as-is from the database.
  */
-declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
+export declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     role: 'detail';
     dateFormat?: DateFormatValue;
     customFormat?: string;
@@ -1155,7 +1204,7 @@ declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     calculatedFormula?: CalculatedFieldFormula;
 }
 
-declare interface DetailTableBackupConfig {
+export declare interface DetailTableBackupConfig {
     groupByColumns?: GroupByField[];
     metricColumns?: MetricField[];
     pivotByColumns?: PivotByField[];
@@ -1173,7 +1222,14 @@ declare interface DetailTableBackupConfig {
     comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
 }
 
-declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
+export declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
+
+export declare type DimensionInputReference = {
+    dataset: string;
+    field: string;
+} | {
+    dimension: string;
+};
 
 export declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
 
@@ -1369,6 +1425,29 @@ export declare type DocumentVariableRef = {
     key: 'generatedAt' | 'pageNumber' | 'pageCount';
 };
 
+export declare interface DomainCalculatedDimension {
+    name: string;
+    label: string;
+    description?: string;
+    expression: string;
+    inputs: Record<string, DimensionInputReference>;
+    dataType?: DataType;
+    tags?: string[];
+}
+
+export declare interface DomainCalculatedMetric {
+    name: string;
+    label: string;
+    description?: string;
+    expression: string;
+    inputs: Record<string, InputReference>;
+    metricType?: 'base' | 'derived' | 'calculated';
+    format?: FormatSpec;
+    tags?: string[];
+    isCertified?: boolean;
+    aggregationStrategy?: AggregationStrategy;
+}
+
 declare interface DrillDownInteraction {
     mode: 'drillDown';
     /**
@@ -1519,7 +1598,17 @@ export declare type EmailSettings = {
 
 export declare const EMPTY_SELECTION: SelectionState;
 
-declare type EntityType = 'table' | 'view' | 'materialized view' | 'model' | 'file' | 'dataset' | 'url' | 'upload';
+export declare type EntityColumnGroup = {
+    entityId: string;
+    entityType: EntityType;
+    entityName: string;
+    qualifiedEntityName: string;
+    label?: string;
+    description?: string;
+    columns: Field[];
+};
+
+export declare type EntityType = 'table' | 'view' | 'materialized view' | 'model' | 'file' | 'dataset' | 'url' | 'upload';
 
 export declare type ErrorProps = {
     message?: string;
@@ -1532,7 +1621,7 @@ export declare type ExportDataPayload = {
     sql: string;
 };
 
-declare interface Field {
+export declare interface Field {
     /**
      * Unique identifier for this field instance (for joins, UI state, etc.).
      * Should be unique within the context of the query or data model.
@@ -1553,6 +1642,7 @@ declare interface Field {
      * If not provided, should be auto-generated from label or name.
      */
     alias?: string;
+    sourceField?: string;
     qualifiedFieldName: string;
     dataType: string;
     description?: string;
@@ -1570,7 +1660,7 @@ declare interface Field {
     fieldScope?: FieldScope;
 }
 
-declare type FieldScope = 'card' | 'dashboard' | 'domain';
+export declare type FieldScope = 'card' | 'sheet' | 'dashboard' | 'domain';
 
 declare type FileAttachment = {
     id: string;
@@ -1583,7 +1673,7 @@ declare type FileAttachment = {
     uploadProgress?: number;
 };
 
-declare interface FileEntityReference extends DatabaseEntityReference {
+export declare interface FileEntityReference extends DatabaseEntityReference {
     id: string;
     type: 'file' | 'url' | 'upload';
     label: string;
@@ -1604,7 +1694,7 @@ declare interface FilterByColumn extends BaseColumn {
     staticValues?: string[];
 }
 
-declare interface FilterCondition {
+export declare interface FilterCondition {
     id: string;
     field: Field;
     operator: Operator;
@@ -1624,7 +1714,7 @@ export declare type FilterDashboardInput = DashboardInputBase & {
  */
 declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
 
-declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
+export declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
     expression?: string;
@@ -1667,7 +1757,7 @@ declare type FilterForString = BaseFilter & {
     values: [string];
 };
 
-declare interface FilterGroup {
+export declare interface FilterGroup {
     id: string;
     logicalOperator: LogicalOperator;
     negate: boolean;
@@ -1705,21 +1795,21 @@ export declare type FilterLayoutSettings = {
     toolbarItemOrder?: string[];
 };
 
-declare type FilterLocation = 'dashboard' | 'frame' | 'sheet' | undefined;
+export declare type FilterLocation = 'dashboard' | 'frame' | 'sheet' | undefined;
 
 declare type FilterOnClick = {
     expression?: string;
     columnIndex: number;
 };
 
-declare type FilterSemanticContext = {
+export declare type FilterSemanticContext = {
     semanticDomainId?: string;
     selectedEntities?: unknown[];
     connectionId?: string;
     connectionType?: string;
 };
 
-declare type FilterValue = string | number | boolean | Date | null | [number, number] | [string, string] | string[] | number[];
+export declare type FilterValue = string | number | boolean | Date | null | [number, number] | [string, string] | string[] | number[];
 
 /**
  * Absolute fixed month/year default used by Month Picker defaults.
@@ -1732,9 +1822,11 @@ declare type FixedMonthDefaultDateFilter = {
     month: number;
 };
 
+export declare type FlatTableTotalsBehavior = 'sum' | 'avg' | 'count' | 'label';
+
 export declare type FormatProfile = 'concise' | 'balanced' | 'detailed';
 
-declare type FormatSpec = {
+export declare type FormatSpec = {
     type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
     locale?: string;
     minimumFractionDigits?: number;
@@ -1772,6 +1864,8 @@ export declare type GetDashboardResponse = {
     organizationAppearance?: AppearanceSpec | null;
 };
 
+export declare function getFieldRuntimeColumnName(field: Pick<Field, 'name' | 'sourceField'> | null | undefined): string;
+
 export declare type GetPluginsResponse = {
     plugins: {
         label: string;
@@ -1788,7 +1882,7 @@ declare interface GroupByColumn extends BaseColumn {
     format?: string;
 }
 
-declare interface GroupByField extends Field {
+export declare interface GroupByField extends Field {
     role: 'groupby';
     granularity?: TimeGranularity;
     /**
@@ -1800,6 +1894,10 @@ declare interface GroupByField extends Field {
     calculatedFormula?: CalculatedFieldFormula;
 }
 
+export declare function hasCalculatedFieldMarker(field: Pick<Field, 'entityName' | 'entityId'> | null | undefined): boolean;
+
+export declare function hasCalculatedFormulaInputs(field: Field | null | undefined): boolean;
+
 export declare type HtmlOptions = {
     html: string;
 };
@@ -1840,6 +1938,16 @@ declare interface InlineDrillInteraction {
     label?: string;
 }
 
+export declare type InputReference = {
+    dataset: string;
+    field: string;
+    aggregate?: AggregateFunction;
+} | {
+    metric: string;
+} | {
+    dimension: string;
+};
+
 /**
  * Unified Interaction type (V2)
  * Combines all interaction types into a single union for the new interactions array.
@@ -1881,29 +1989,63 @@ declare type InteractiveSurfaceAppearance = BaseSurfaceAppearance & {
     toolbarBackground?: string;
 };
 
-declare interface Join {
+/**
+ * Type guard to identify calculated dimensions
+ */
+export declare function isCalculatedDimension(field: GroupByField): field is GroupByField & {
+    expression: string;
+};
+
+/**
+ * Generic type guard for any calculated field
+ */
+export declare function isCalculatedField(field: Field): boolean;
+
+/**
+ * IMPORTANT: Why we store qualifiedFieldNames as strings instead of Field objects
+ *
+ * Field IDs are ephemeral and change on drag-and-drop operations. Storing
+ * qualifiedFieldNames as strings provides:
+ * - No data duplication (metricColumns is the single source of truth)
+ * - Smaller payload size
+ * - Stable references (qualifiedFieldName doesn't change)
+ * - Backend can look up fresh aggregate info from metricColumns
+ * - Enables proper post-aggregation: SUM(t0.sales) / COUNT(t0.order_id)
+ *   instead of incorrect: SUM(t0.sales / t0.order_id)
+ */
+/**
+ * Type guard to identify calculated metrics
+ */
+export declare function isCalculatedMetric(field: Field): field is MetricField & {
+    expression: string;
+};
+
+export declare interface Join {
     id: string;
     source: DatabaseEntityReference;
     target: DatabaseEntityReference;
     joinType: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
     joinKeyGroups: JoinKeyGroup[];
     sequence: number;
+    relationshipId?: string;
+    relationshipName?: string;
+    relationshipCardinality?: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
 }
 
-declare interface JoinKey {
+export declare interface JoinKey {
     id?: string;
     source: Field;
     target: Field;
     operator: string;
 }
 
-declare interface JoinKeyGroup {
+export declare interface JoinKeyGroup {
     id: string;
     operator: string;
     keys: JoinKey[];
 }
 
-declare interface JoinPlan {
+export declare interface JoinPlan {
     baseEntity: DatabaseEntityReference;
     joins: Join[];
 }
@@ -1928,7 +2070,7 @@ export declare type LoadingProps = {
     message?: string;
 };
 
-declare type LogicalOperator = 'AND' | 'OR';
+export declare type LogicalOperator = 'AND' | 'OR';
 
 declare interface MetricColumn extends BaseColumn {
     role: 'metric';
@@ -1936,7 +2078,7 @@ declare interface MetricColumn extends BaseColumn {
     aliasTemplate?: string;
 }
 
-declare interface MetricField extends Field {
+export declare interface MetricField extends Field {
     role: 'metric';
     aggregate?: AggregateFunction;
     /**
@@ -1978,6 +2120,12 @@ declare interface MetricField extends Field {
      * Both are generated together from the same dialog inputs, preventing drift.
      */
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Indicates the metric expression must be evaluated after row-level filtering,
+     * either because it contains an aggregate function directly or depends on a
+     * pre-aggregated metric input.
+     */
+    isPreAggregated?: boolean;
     comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'start_vs_end' | 'target';
     comparisonDisplay?: 'column' | 'inline' | 'hover';
     targetValue?: number;
@@ -2020,9 +2168,9 @@ declare type NumericCanonicalFormat = {
 
 declare type OldFilterValue = string | number | null | (string | number)[] | RangeValue;
 
-declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
+export declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
 
-declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
+export declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
 
 declare type OptionsMap = {
     number: NumberOptions;
@@ -2040,11 +2188,23 @@ declare interface OrderBy {
 /**
  * Pagination configuration for table queries
  */
-declare interface PaginationConfig {
+export declare interface PaginationConfig {
     page: number;
     pageSize: number;
 }
 
+/**
+ * Pagination metadata returned with query results
+ */
+export declare interface PaginationMetadata {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    totalCount: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+
 declare type Params = {
     [key: string]: string | number | string[] | number[];
 };
@@ -2053,10 +2213,49 @@ declare type PersistedInteraction = Interaction & {
     id?: string;
 };
 
-declare interface PivotByField extends Field {
+export declare interface PivotByField extends Field {
     role: 'pivotby';
 }
 
+export declare interface PivotColumnSchema {
+    alias: string;
+    metricId: string;
+    metricName: string;
+    metricLabel?: string;
+    pivotValues: string[];
+    pivotFields?: string[];
+    displayLabel?: string;
+    isPivotColumn?: boolean;
+    isMetricColumn?: boolean;
+    isGroupByColumn?: boolean;
+    aggregate?: AggregateFunction;
+}
+
+/**
+ const config: CardConfig = {
+ groupByColumns: [
+ { id: 'region', name: 'region', label: 'Region', ... },
+ { id: 'country', name: 'country', label: 'Country', ... }
+ ],
+ pivotByColumns: [
+ { id: 'year', name: 'year', label: 'Year', ... },
+ { id: 'quarter', name: 'quarter', label: 'Quarter', ... }
+ ],
+ metricColumns: [ ... ],
+ rowAggregates: ['SUM', 'AVG'],
+ columnAggregates: ['SUM'],
+ subtotals: {
+ groupBy: { functions: ['SUM'], levels: ['region'] }, // subtotal at region level
+ pivotBy: { functions: ['SUM'], levels: ['year'] }    // subtotal at year level
+ }
+ };
+ */
+export declare enum PivotMarkerEnum {
+    SUBTOTAL = "__SUBTOTAL__",
+    TOTAL = "__TOTAL__",
+    ALL = "__ALL__"
+}
+
 export declare type Placeholders = {
     /**
      * Placeholder for the card when there are no records to display.
@@ -2070,6 +2269,20 @@ export declare type Placeholders = {
 
 export declare type PluginType = 'custom' | 'standard';
 
+export declare interface QueryColumnKeyMap {
+    version: 1;
+    source: 'explorer';
+    byFieldId: Record<string, QueryColumnKeyMapEntry>;
+}
+
+export declare interface QueryColumnKeyMapEntry {
+    role: QueryColumnKeyRole;
+    rawKey: string;
+    outputKey?: string;
+}
+
+export declare type QueryColumnKeyRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
+
 declare interface QueryConfig {
     groupByColumns?: GroupByColumn[];
     pivotColumns?: GroupByColumn[];
@@ -2080,6 +2293,26 @@ declare interface QueryConfig {
     orderBy?: OrderBy[];
 }
 
+/**
+ * Response structure for query execution (standard queries and comparison queries)
+ */
+export declare interface QueryExecutionResponse {
+    records: any[];
+    output: string;
+    rowLimitExceeded: boolean;
+    sql?: string;
+    userSql?: string;
+    pivotSchema?: any;
+    pagination?: PaginationMetadata;
+    subtotalColumns?: string[];
+    columnSubtotalMeta?: any;
+    columnMetadata?: Record<string, any>;
+    columnKeyMap?: QueryColumnKeyMap;
+    tableTotalsByColumnId?: Record<string, string | number | null>;
+    documentTableTotalsBaseSql?: string;
+    metadata?: any;
+}
+
 declare type QueryFilter = {
     filterColumnName: string;
     filterValue: OldFilterValue;
@@ -2092,21 +2325,21 @@ declare type RangeValue = {
     gt?: string | number;
 };
 
-declare type RelativeDateFilter = {
+export declare type RelativeDateFilter = {
     mode: 'last';
     n: number;
-    unit: DateUnit;
+    unit: DateUnit_2;
     complete?: boolean;
 } | {
     mode: 'this';
-    unit: DateUnit;
+    unit: DateUnit_2;
     toDate?: boolean;
 } | {
     mode: 'previous';
-    unit: DateUnit;
+    unit: DateUnit_2;
 } | {
     mode: 'between';
-    unit: DateUnit;
+    unit: DateUnit_2;
     from: number;
     to: number;
 };
@@ -2183,7 +2416,9 @@ export declare type ResolvedTokenParams = Omit<TokenParams, 'calendarContext'> &
     calendarContext: CalendarContext;
 };
 
-declare type SelectedEntities = Array<DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference>;
+export declare type SelectedEntities = SelectedEntity[];
+
+export declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
 
 export declare type SelectionState = Record<Level, string | null>;
 
@@ -2217,11 +2452,13 @@ declare type SemanticExecutionPayload = {
 
 export declare type SensitivityPreset = 'low_noise' | 'standard' | 'early_warning';
 
-declare interface SortByField extends Field {
+export declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
 }
 
+export declare type SortDirection = 'asc' | 'desc';
+
 export declare type SqlGen = {
     measures?: {
         name: string;
@@ -2293,6 +2530,14 @@ export declare type StyleProps = {
     };
 };
 
+/**
+ * Subtotal configuration for groupBy and pivotBy axes
+ */
+export declare interface SubtotalConfig {
+    groupBy?: AggregateConfig;
+    pivotBy?: AggregateConfig;
+}
+
 declare type TableAppearance = {
     density?: AppearanceDensity;
     container?: {
@@ -2406,6 +2651,16 @@ declare type TableStylePreferences = {
 
 declare type TableTotalsFontWeight = 'normal' | 'medium' | 'semibold' | 'bold';
 
+export declare type TableTotalsRequest = {
+    source: 'documentFlatTable';
+    columns: Array<{
+        fieldId: string;
+        role: 'detail' | 'groupby' | 'metric';
+        behavior: FlatTableTotalsBehavior;
+        label?: string;
+    }>;
+};
+
 declare type TableTotalsStylePreferences = {
     enabled?: boolean;
     backgroundColor?: string;
@@ -2761,7 +3016,7 @@ export declare type TChartOptions = {
     treemapColorMode?: 'branch' | 'category';
 };
 
-declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
+export declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
 
 export declare type TColumnSetting<T extends DisplayDataType> = {
     columnIdx: number;
@@ -2811,6 +3066,7 @@ export declare type TDashboard = {
     };
     description?: string;
     sheets?: TSheet[];
+    calculatedFields?: Field[];
     style?: TStyle;
     filters?: TFilter[];
     customCards?: CustomCard[];
@@ -2944,7 +3200,7 @@ export declare type TEvent = {
     message: any;
 };
 
-declare type TFilter = {
+export declare type TFilter = {
     kind?: FilterKind;
     type?: 'single' | 'multiple';
     uiType?: 'radio' | 'dropdown' | 'tabs';
@@ -2997,7 +3253,7 @@ declare type TFilter = {
     displayMode?: FilterDisplayMode;
 };
 
-declare type TFilterValue = FilterForString | FilterForEqual | FilterForCompare | FilterForBetween | FilterForIn | FilterForNull | FilterForDate;
+export declare type TFilterValue = FilterForString | FilterForEqual | FilterForCompare | FilterForBetween | FilterForIn | FilterForNull | FilterForDate;
 
 export declare type TFormatOptions = {
     type?: 'auto' | 'number' | 'currency' | 'percent' | 'scientific' | 'date';
@@ -3081,7 +3337,7 @@ declare interface TimeDrillStep {
     rollingWindow?: number;
 }
 
-declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+export declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
 
 /**
  * Inline filter definition stored on a card.
@@ -3563,9 +3819,9 @@ export declare type VisualDisplayPreferences = {
  */
 export declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 
-declare type WindowFunction = 'running_total' | 'moving_average' | 'previous_period_delta' | 'percent_of_total';
+export declare type WindowFunction = 'running_total' | 'moving_average' | 'previous_period_delta' | 'percent_of_total';
 
-declare interface WindowTransform {
+export declare interface WindowTransform {
     function: WindowFunction;
     orderBy?: {
         fieldId: string;