react-semaphor 0.1.504 → 0.1.505

package/dist/types/lib/types/explorer-types.d.ts

@@ -0,0 +1,736 @@
+import { ClickFilterInteraction, DrillHierarchy, TimeDrillStep } from './interaction-types.js';
+import { SemaphorDerivedFieldDefinition, MatrixConfig, SemaphorSourceRef, SemaphorResultColumn, SemaphorPivotValue, SemaphorTimeGrain, SemanticGroupedTemporalInput, TemporalBucketMetadata, TemporalBucketFormat, MetricComparisonConfig, MetricComparisonPolarity } from '../../shared/analytics-protocol/index.js';
+import { CanonicalPivotResultContract, CanonicalPivotResultState, FlatTableExportTotalsBehavior, FlatTableExportTotalsRequest, QueryColumnKeyMap as SharedQueryColumnKeyMap } from '../../shared/format-utils/index.js';
+import { TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
+/**
+ * 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";
+export declare const LEGACY_CALCULATED_FIELD_ENTITY_MARKER: "calculated_fields";
+export type CardMode = 'explorer' | 'dev';
+export type FieldScope = 'card' | 'sheet' | 'dashboard' | 'domain';
+export type SemanticTemporalPresentation = {
+    granularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+};
+export type ConnectionType = 'GoogleSheets' | 'FileUpload' | 'MySQL' | 'MSSQL' | 'PostgreSQL' | 'BigQuery' | 'Redshift' | 'Snowflake' | 'S3' | 'clickhouse' | 'S3Tables' | 'API' | 'none';
+export type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
+export interface Field {
+    /**
+     * Stable authored/semantic field identifier (for joins, UI state, etc.).
+     * It is normally unique within a role, but one saved query may reuse it in
+     * different roles; result bindings must therefore include the role.
+     * Example: 'orders.customer_id', 'expr_12345', etc.
+     */
+    id: string;
+    /**
+     * The physical/source column name in the database or data source.
+     * Used for mapping to the underlying data model and SQL generation (unless overridden by expression).
+     */
+    name: string;
+    /**
+     * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
+     */
+    label: string;
+    /**
+     * Set only when `label` was synthesized from `name` because the source
+     * provided no authored label (raw database objects). Field pickers follow
+     * the naming rule in `@/lib/fields/field-display`: an authored semantic
+     * label is shown as is, otherwise the physical column name. A field whose
+     * `label` still equals `derivedLabel` has no authored label; any later
+     * edit to `label` makes it authored without touching this marker.
+     */
+    derivedLabel?: string;
+    /**
+     * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
+     * If not provided, should be auto-generated from label or name.
+     */
+    alias?: string;
+    sourceField?: string;
+    /** Catalog identity for source-bound field selections; metadata, not authorization. */
+    source?: Exclude<SemaphorSourceRef, {
+        kind: 'sql';
+    }>;
+    qualifiedFieldName: string;
+    dataType: string;
+    /** Exact database type when dataType is normalized for analytics/UI use. */
+    nativeDataType?: string;
+    description?: string;
+    qualifiedEntityName?: string;
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+    granularity?: TimeGranularity;
+    entityId: string;
+    entityName: string;
+    entityType: EntityType;
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
+    format?: FormatSpec;
+    /**
+     * Source-level temporal presentation keeps the semantic grain that authored
+     * the format. The card's mutable `granularity` remains the active query
+     * grain, so changing it cannot accidentally retarget a semantic default.
+     */
+    semanticTemporalPresentation?: SemanticTemporalPresentation;
+    aggregate?: AggregateFunction;
+    /** Whether this placement aggregate was supplied by the editor or authored. Omitted means unknown. */
+    aggregateOrigin?: 'default' | 'explicit';
+    /** Runtime representation, independent of definition ownership and shelf role. */
+    calculationRepresentation?: 'inline-expression' | 'manual' | 'typed-derived';
+    /** Definition identity survives timestamped shelf IDs and changes of placement role. */
+    calculatedFieldOrigin?: {
+        id: string;
+        role?: Field['role'];
+    };
+    /** Provenance for display metadata on governed fields. Unmarked legacy values are semantic snapshots. */
+    labelOrigin?: 'semantic' | 'override';
+    /** Provenance for display formatting on governed fields. Unmarked legacy values are semantic snapshots. */
+    formatOrigin?: 'semantic' | 'override';
+    fieldScope?: FieldScope;
+}
+export declare function getFieldRuntimeColumnName(field: Pick<Field, 'name' | 'sourceField'> | null | undefined): string;
+export type SortDirection = 'asc' | 'desc';
+export type TimeGranularity = SemaphorTimeGrain;
+export type DataType = 'string' | 'number' | 'date' | 'datetime' | 'boolean' | 'json' | 'geo';
+export type LogicalOperator = 'AND' | 'OR';
+export type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
+export type ContainerId = 'groupBy' | 'metrics' | 'pivotBy' | 'sortBy' | 'detailColumns' | 'source';
+export type AggregateFunction = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+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"];
+export type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
+export type DateFormatOption = {
+    value: DateFormatValue;
+    label: string;
+};
+export interface GroupByField extends Field {
+    role: 'groupby';
+    granularity?: TimeGranularity;
+    /**
+     * Optional SQL expression for grouping (e.g., DATE_TRUNC('month', order_date)).
+     * If present, used in SELECT and GROUP BY instead of just the column name.
+     */
+    expression?: string;
+    timeDrillPath?: TimeDrillStep[];
+    calculatedFormula?: CalculatedFieldFormula;
+}
+export type WindowFunction = 'running_total' | 'moving_average' | 'previous_period_delta' | 'percent_of_total';
+export interface WindowTransform {
+    function: WindowFunction;
+    orderBy?: {
+        fieldId: string;
+        direction?: 'asc' | 'desc';
+    };
+    partitionByFieldIds?: string[];
+    frame?: 'unbounded_preceding';
+    movingAverage?: {
+        windowSize?: number;
+        minPeriods?: number;
+    };
+    previousPeriodDelta?: {
+        mode?: 'absolute' | 'percent';
+    };
+    percentOfTotal?: {
+        scope?: 'grand_total' | 'partition_total';
+        output?: 'fraction' | 'percent';
+    };
+}
+export interface MetricField extends Field {
+    role: 'metric';
+    aggregate?: AggregateFunction;
+    /**
+     * Optional SQL expression for the metric (e.g., ship_date - order_date).
+     * If present, used as aggregate(expression) instead of aggregate(name).
+     */
+    expression?: string;
+    /**
+     * Optional parameters for future extensibility (e.g., window functions).
+     * * Example:
+     * {
+        aggregate: "SUM",
+        name: "sales",
+        parameters: {
+          window: "PARTITION BY region ORDER BY date ROWS BETWEEN 1 PRECEDING AND CURRENT ROW"
+        }
+      }
+  
+      {
+        aggregate: "COUNT",
+        name: "order_id",
+        parameters: {
+          filter: "status = 'Active'"
+        }
+      }
+     */
+    parameters?: {
+        filters?: FilterGroup;
+        windowTransform?: WindowTransform;
+    };
+    aliasTemplate?: string;
+    valueAliases?: Record<string, string>;
+    /**
+     * Formula metadata for calculated fields (UI-only metadata)
+     * This is supplementary data to help the UI display and edit calculated fields.
+     * The `expression` field remains the source of truth for the backend.
+     *
+     * IMPORTANT: This metadata is ALWAYS updated atomically with the expression 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;
+    comparison?: MetricComparisonConfig;
+    comparisonPolarity?: MetricComparisonPolarity;
+    /** Governed runtime annotation. When present, authoring polarity is read-only. */
+    semanticComparisonPolarity?: MetricComparisonPolarity;
+}
+/**
+ * Operations supported for calculated fields
+ */
+export type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
+/**
+ * Formula metadata for calculated fields (UI-only metadata)
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
+ *
+ * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
+ * Both are generated together from the same dialog inputs, preventing drift.
+ */
+export interface CalculatedFieldFormula {
+    operation: CalculatedFieldOperation;
+    /** Evaluation stage of the definition, independent of its selected shelf. */
+    computeStage?: 'row' | 'aggregate';
+    /**
+     * Array of full MetricField objects used as inputs to the calculated field.
+     *
+     * Storing complete Field objects eliminates the need for runtime lookups and ensures:
+     * - Table alias resolution works with schema-qualified tables (Issue 1)
+     * - All field metadata is available even if the input field isn't selected on the card (Issue 2)
+     * - Aggregate functions, filters, and entity info are preserved
+     *
+     * Each input field contains complete metadata:
+     * - name, entityId, entityName, qualifiedEntityName (for table qualification)
+     * - aggregate (for proper post-aggregation: SUM(sales) / COUNT(orders))
+     * - parameters.filters (for filtered metrics)
+     * - dataType and other properties
+     *
+     * Example: [
+     *   {name: 'sales', aggregate: 'SUM', entityName: 'sales_data', ...},
+     *   {name: 'order_id', aggregate: 'COUNT', entityName: 'sales_data', ...}
+     * ]
+     */
+    inputFields: Array<MetricField | GroupByField>;
+    /**
+     * Constant value used in scale operations (e.g., multiply by 0.15)
+     * Only applicable for 'scale' operation type
+     */
+    constant?: number;
+}
+export interface DomainCalculatedMetric {
+    name: string;
+    label: string;
+    description?: string;
+    expression: string;
+    inputs: Record<string, InputReference>;
+    metricType?: 'base' | 'derived' | 'calculated';
+    format?: ScalarFormatSpec;
+    tags?: string[];
+    isCertified?: boolean;
+    aggregationStrategy?: AggregationStrategy;
+}
+type DomainCalculatedDimensionBase = {
+    name: string;
+    label: string;
+    description?: string;
+    expression: string;
+    inputs: Record<string, DimensionInputReference>;
+    dataType?: DataType;
+    tags?: string[];
+};
+export type DomainCalculatedDimension = SemanticGroupedTemporalInput<DomainCalculatedDimensionBase>;
+export type InputReference = {
+    dataset: string;
+    field: string;
+    aggregate?: AggregateFunction;
+} | {
+    metric: string;
+} | {
+    dimension: string;
+};
+export type DimensionInputReference = {
+    dataset: string;
+    field: string;
+} | {
+    dimension: string;
+};
+export type FormatSpec = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+} | TemporalBucketFormat;
+export type ScalarFormatSpec = Exclude<FormatSpec, TemporalBucketFormat>;
+export type AggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+/**
+ * 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;
+};
+/**
+ * Type guard to identify calculated dimensions
+ */
+export declare function isCalculatedDimension(field: GroupByField): field is GroupByField & {
+    expression: string;
+};
+/**
+ * True for every representation of a derived (calculated) field:
+ * an expression, formula inputs, the shared-contract `derivedField`
+ * (the only shape Matrix-authored calculations may carry), or a synthetic
+ * calculated-field owner. Use this wherever the
+ * question is "is this computed rather than stored".
+ */
+export declare function isDerivedField(field: CalculatedFieldInspectable | null | undefined): boolean;
+export type CalculatedFieldInspection = {
+    representation: 'physical' | 'inline-expression' | 'manual' | 'typed-derived';
+    ownership: 'local' | 'domain';
+    completeness: 'not-calculated' | 'complete' | 'incomplete';
+    computeStage?: 'row' | 'aggregate';
+    runtimeExecutable: boolean;
+    /** Compatibility mode for local runtime fields created before stage metadata. */
+    legacyManual: boolean;
+};
+/** Metadata surface needed to classify a field without requiring shelf UI fields. */
+export type CalculatedFieldInspectable = {
+    calculationRepresentation?: Field['calculationRepresentation'];
+    name?: string;
+    sourceField?: string;
+    role?: Field['role'];
+    entityName?: string;
+    entityId?: string;
+    qualifiedEntityName?: string;
+    fieldScope?: FieldScope;
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    calculatedFieldOrigin?: Field['calculatedFieldOrigin'];
+    derivedField?: SemaphorDerivedFieldDefinition;
+};
+/**
+ * Inspect a runtime field without conflating public typed-derived metadata with
+ * the dashboard-local expression/formula representation. Consumers use this
+ * result for classification and stage; each compiler still owns execution.
+ */
+export declare function inspectCalculatedField(field: CalculatedFieldInspectable | null | undefined): CalculatedFieldInspection;
+/** Normalize unannotated saved shapes once, before attaching placement/scope
+ * metadata. Never replaces an explicit tag, even if invalid: validation owns it. */
+export declare function normalizeCalculatedFieldRepresentation<T extends CalculatedFieldInspectable>(field: T): T;
+export declare function getCalculatedFieldComputeStage(field: CalculatedFieldInspectable | null | undefined): 'row' | 'aggregate' | undefined;
+/** Only a proven inherited default may be removed for an aggregate-stage definition. */
+export declare function shouldDropInheritedCalculationAggregate(computeStage: 'row' | 'aggregate' | undefined, aggregateOrigin: MetricField['aggregateOrigin']): boolean;
+export declare function hasCalculatedFormulaInputs(field: Field | null | undefined): boolean;
+export declare function hasCalculatedFieldMarker(field: Pick<Field, 'entityName' | 'entityId'> | null | undefined): boolean;
+/**
+ * Identifies the synthetic owner used by calculated fields. New fields use
+ * CALCULATED_FIELD_ENTITY_MARKER, while persisted dashboards may still carry
+ * the historical `calculated_fields` namespace.
+ */
+export declare function hasSyntheticCalculatedFieldOwner(field: Partial<Pick<Field, 'entityName' | 'entityId' | 'qualifiedEntityName'>> | null | undefined): boolean;
+export interface SortByField extends Field {
+    role: 'sortby';
+    direction: 'asc' | 'desc';
+}
+/**
+ * Persisted authoring intent for the order of generated pivot-member columns.
+ *
+ * `auto` is a distinct persisted value rather than a synonym for `asc` so a
+ * future governed semantic member order can become the default for `auto`
+ * without changing cards that explicitly chose `asc` or `desc`.
+ */
+export type PivotMemberOrder = 'auto' | 'asc' | 'desc';
+export interface PivotByField extends Field {
+    role: 'pivotby';
+    /**
+     * Ordering rule for this field's discovered members. Omitted means `auto`,
+     * so existing cards need no migration.
+     */
+    memberOrder?: PivotMemberOrder;
+}
+/**
+ * Field configuration for detail table columns.
+ * Unlike GroupByField, DetailField does not support aggregation or granularity.
+ * Columns are selected and displayed as-is from the database.
+ */
+export interface DetailField extends Omit<Field, 'role' | 'granularity'> {
+    role: 'detail';
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+    /**
+     * Optional SQL expression for calculated detail fields.
+     */
+    expression?: string;
+    /**
+     * Formula metadata for calculated fields (used for token qualification).
+     */
+    calculatedFormula?: CalculatedFieldFormula;
+}
+export type FilterValue = string | number | boolean | Date | null | [number, number] | [string, string] | string[] | number[];
+export interface FilterCondition {
+    id: string;
+    field: Field;
+    operator: Operator;
+    value: FilterValue;
+    /** Display-only label for canonical grouped-temporal values. */
+    label?: string;
+    /** Governed meaning for a canonical grouped-temporal scalar. */
+    temporalBucket?: TemporalBucketMetadata;
+}
+export interface FilterGroup {
+    id: string;
+    logicalOperator: LogicalOperator;
+    negate: boolean;
+    conditions: FilterCondition[];
+    groups: FilterGroup[];
+}
+export interface JoinKey {
+    id?: string;
+    source: Field;
+    target: Field;
+    operator: string;
+}
+export interface JoinKeyGroup {
+    id: string;
+    operator: string;
+    keys: JoinKey[];
+}
+export interface JoinPlan {
+    baseEntity: DatabaseEntityReference;
+    joins: Join[];
+}
+export 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';
+    relationshipTraversalDirection?: 'forward' | 'reverse';
+}
+export type EntityType = 'table' | 'view' | 'materialized view' | 'model' | 'file' | 'dataset' | 'url' | 'upload';
+export type DatabaseEntityType = 'table' | 'view' | 'materialized view';
+export interface DatabaseEntityReference {
+    connectionId: string;
+    connectionType: ConnectionType;
+    type: EntityType;
+    dbObjectType?: string;
+    dialect?: Dialect;
+    database?: string;
+    schema?: string;
+    name: string;
+}
+export interface DataModelEntityReference extends DatabaseEntityReference {
+    type: 'model';
+    id: string;
+    label: string;
+    description: string;
+}
+export interface DatasetEntityReference extends DatabaseEntityReference {
+    type: 'dataset';
+    datasetType: 'physical' | 'virtual';
+    table?: string | null;
+    datamodelId?: string | null;
+    sql?: string | null;
+    /** UI entity key from dataset discovery; may be the canonical dataset name. */
+    id: string;
+    domainId: string;
+    label: string;
+    description?: string;
+}
+export interface FileEntityReference extends DatabaseEntityReference {
+    id: string;
+    type: 'file' | 'url' | 'upload';
+    label: string;
+    description: string;
+    originalName: string;
+    file?: File;
+    url?: string;
+}
+export type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
+export type SelectedEntities = SelectedEntity[];
+export interface DataSource {
+    connectionId: string;
+    semanticDomainId?: string;
+    connectionType: string;
+    mode: 'database' | 'upload' | 'url' | 'semanticDomain';
+    dbSelection?: {
+        database: string;
+        schema: string;
+        entityType: DatabaseEntityType;
+    };
+    selectedEntities: SelectedEntities;
+}
+export type EntityColumnGroup = {
+    entityId: string;
+    entityType: EntityType;
+    entityName: string;
+    qualifiedEntityName: string;
+    label?: string;
+    description?: string;
+    columns: Field[];
+};
+/**
+ * Configuration for which aggregate functions to use and at which levels (by Field.id)
+ */
+export interface AggregateConfig {
+    functions: AggregateFunction[];
+    levels?: string[];
+}
+/**
+ * Subtotal configuration for groupBy and pivotBy axes
+ */
+export interface SubtotalConfig {
+    groupBy?: AggregateConfig;
+    pivotBy?: AggregateConfig;
+}
+/**
+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 interface CardConfig {
+    /** Sole persisted Matrix definition; runtime windows are not card configuration. */
+    matrix?: MatrixConfig;
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    detailColumns?: DetailField[];
+    /**
+     * Typed source that anchors the query before auto-join materializes an
+     * executable joinPlan.baseEntity. This is distinct from
+     * DataSource.selectedEntities, which lists available datasets but does not
+     * define join-root semantics.
+     */
+    queryBaseSource?: SemaphorSourceRef;
+    /** Preserves non-detail config when switching to detail tables. */
+    detailTableBackup?: DetailTableBackupConfig;
+    filters?: FilterGroup;
+    joinPlan?: JoinPlan;
+    rowLimit?: number;
+    /**
+     * One or more hierarchies that define drillable paths through dimensions.
+     */
+    drillHierarchies?: DrillHierarchy[];
+    /**
+     * Optional list of dimensions allowed for dynamic drill-down across this card.
+     * Used only when drill steps contain `mode: 'dynamicDrill'` or `type: 'dynamic'`.
+     */
+    allowedDrillTargets?: Field[];
+    /**
+     * NOT UOptional preload settings for inline drill previews
+     */
+    inlineDrillPreview?: {
+        enabled: boolean;
+        limit: number;
+        mode: 'lazy' | 'preloaded';
+    };
+    /**
+     * Configuration for on-click dashboard filters triggered by this card.
+     */
+    clickFilterInteractions?: ClickFilterInteraction[];
+    summary?: {
+        enabled?: boolean;
+        showOnCard?: boolean;
+        includeInDashboardSummary?: boolean;
+        breakdownDimensions?: GroupByField[];
+    };
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+}
+export interface DetailTableBackupConfig {
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+}
+export interface PivotColumnSchema {
+    alias: string;
+    metricAlias?: string;
+    metricId: string;
+    metricName: string;
+    metricLabel?: string;
+    pivotValues: SemaphorPivotValue[];
+    pivotFieldIds?: string[];
+    pivotFields?: string[];
+    displayLabel?: string;
+    isPivotColumn?: boolean;
+    isMetricColumn?: boolean;
+    isGroupByColumn?: boolean;
+    aggregate?: AggregateFunction;
+}
+/**
+ * Pagination configuration for table queries
+ */
+export interface PaginationConfig {
+    page: number;
+    pageSize: number;
+}
+/**
+ * Pagination metadata returned with query results
+ */
+export interface PaginationMetadata {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    totalCount: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}
+export { resolveQueryColumnKeyMapEntry, resolveUniqueQueryColumnKeyMapEntry, type QueryColumnKeyMapByRole, type QueryColumnKeyMapEntry, type QueryColumnKeyRole, } from '../../shared/format-utils/pivot-result-identity.js';
+export type QueryColumnKeyMap = SharedQueryColumnKeyMap;
+export type FlatTableTotalsBehavior = FlatTableExportTotalsBehavior;
+export type TableTotalsRequest = FlatTableExportTotalsRequest;
+/**
+ * Response structure for query execution (standard queries and comparison queries)
+ */
+export interface QueryExecutionResponse {
+    records: any[];
+    /** Execution owner captured with these exact result rows. */
+    resultOwner?: TemporalResultOwner;
+    pivotResultState?: CanonicalPivotResultState;
+    pivotResultContract?: CanonicalPivotResultContract;
+    columns?: SemaphorResultColumn[];
+    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;
+}