drizzle-cube 0.5.7 → 0.6.0

package/dist/server/server/logical-plan/types.d.ts

@@ -0,0 +1,199 @@
+import { AnyColumn, Table } from 'drizzle-orm';
+import { Cube, CubeJoin, JoinKeyInfo, PropagatingFilter, IntermediateJoinInfo, DownstreamJoinKeyInfo } from '../types/cube';
+import { Filter } from '../types/query';
+import { QueryWarning, TimeGranularity } from '../types/core';
+/** Reference to a registered cube */
+export interface CubeRef {
+    /** Cube name (e.g. 'Employees') */
+    name: string;
+    /** Resolved cube object */
+    cube: Cube;
+}
+/** Reference to a measure on a specific cube */
+export interface MeasureRef {
+    /** Fully qualified name: CubeName.measureName */
+    name: string;
+    /** Cube that owns this measure */
+    cube: CubeRef;
+    /** Local measure name (without cube prefix) */
+    localName: string;
+}
+/** Reference to a dimension on a specific cube */
+export interface DimensionRef {
+    /** Fully qualified name: CubeName.dimensionName */
+    name: string;
+    /** Cube that owns this dimension */
+    cube: CubeRef;
+    /** Local dimension name (without cube prefix) */
+    localName: string;
+}
+/** Reference to a time dimension with granularity/dateRange */
+export interface TimeDimensionRef {
+    /** Fully qualified dimension name */
+    name: string;
+    cube: CubeRef;
+    localName: string;
+    granularity?: TimeGranularity;
+    dateRange?: string | string[];
+    fillMissingDates?: boolean;
+    compareDateRange?: (string | [string, string])[];
+}
+/** Reference to a column for join keys */
+export interface ColumnRef {
+    column: AnyColumn;
+    alias?: string;
+}
+/** Order-by specification */
+export interface OrderByRef {
+    /** Fully qualified field name */
+    name: string;
+    direction: 'asc' | 'desc';
+}
+export interface LogicalSchema {
+    measures: MeasureRef[];
+    dimensions: DimensionRef[];
+    timeDimensions: TimeDimensionRef[];
+}
+export interface JoinRef {
+    /** Target cube being joined */
+    target: CubeRef;
+    /** Table alias in the generated SQL */
+    alias: string;
+    /** SQL join type (already resolved from the effective relationship) */
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    /**
+     * Symbolic join definition. The Drizzle join condition is materialized from
+     * this by DrizzlePlanBuilder — the logical plan itself holds no SQL and no
+     * baked security context.
+     */
+    joinDef: CubeJoin;
+    /** Relationship type from the join definition */
+    relationship?: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    /**
+     * Junction table for belongsToMany relationships (symbolic).
+     * The junction join condition and security WHERE are materialized from
+     * `joinDef.through` by DrizzlePlanBuilder at physical-plan time.
+     */
+    junctionTable?: {
+        table: Table;
+        alias: string;
+        joinType: 'inner' | 'left' | 'right' | 'full';
+        sourceCubeName?: string;
+    };
+}
+/** Discriminated union tag for all node types */
+export type LogicalNodeType = 'query' | 'simpleSource' | 'fullKeyAggregate' | 'ctePreAggregate' | 'keysDeduplication' | 'multiFactMerge';
+/** Base interface shared by all logical plan nodes */
+export interface LogicalNodeBase {
+    readonly type: LogicalNodeType;
+    readonly schema: LogicalSchema;
+}
+/**
+ * Root query node — represents the outermost SELECT.
+ * Wraps a source node with dimensions, measures, filters, ordering, etc.
+ */
+export interface QueryNode extends LogicalNodeBase {
+    readonly type: 'query';
+    /** Source of rows (SimpleSource, FullKeyAggregate, etc.) */
+    source: LogicalNode;
+    /** Dimensions to group by */
+    dimensions: DimensionRef[];
+    /** Measures to aggregate */
+    measures: MeasureRef[];
+    /** User-supplied filters */
+    filters: Filter[];
+    /** Time dimensions with granularity / date range */
+    timeDimensions: TimeDimensionRef[];
+    /** ORDER BY clauses */
+    orderBy: OrderByRef[];
+    limit?: number;
+    offset?: number;
+    /** When true, skip GROUP BY (raw rows) */
+    ungrouped?: boolean;
+    /** Planning warnings surfaced to the caller */
+    warnings: QueryWarning[];
+}
+/**
+ * Simple source: one primary cube optionally joined to other cubes.
+ * This is the runtime physical-source shape used by SQL generation today.
+ */
+export interface SimpleSource extends LogicalNodeBase {
+    readonly type: 'simpleSource';
+    /** Primary cube (FROM clause) */
+    primaryCube: CubeRef;
+    /** Cubes joined to the primary */
+    joins: JoinRef[];
+    /** Pre-aggregation CTEs attached to this source */
+    ctes: CTEPreAggregate[];
+}
+/**
+ * Full key aggregate: merges results from multiple subqueries
+ * that share the same dimension key set.
+ */
+export interface FullKeyAggregate extends LogicalNodeBase {
+    readonly type: 'fullKeyAggregate';
+    /** Subqueries whose results will be merged */
+    subqueries: LogicalNode[];
+    /** Shared dimensions used as the merge key */
+    dimensions: DimensionRef[];
+}
+/**
+ * CTE pre-aggregation node.
+ * Represents a WITH clause that pre-aggregates a hasMany cube
+ * to prevent fan-out in the outer query.
+ */
+export interface CTEPreAggregate extends LogicalNodeBase {
+    readonly type: 'ctePreAggregate';
+    /** The cube being pre-aggregated */
+    cube: CubeRef;
+    /** Table alias for the cube in the main query */
+    alias: string;
+    /** CTE alias (WITH clause name) */
+    cteAlias: string;
+    /** Keys connecting CTE back to the main query */
+    joinKeys: JoinKeyInfo[];
+    /** Measure names included in this CTE */
+    measures: string[];
+    /** Cross-cube filter propagation */
+    propagatingFilters?: PropagatingFilter[];
+    /** Downstream join keys for transitive joins through this CTE */
+    downstreamJoinKeys?: DownstreamJoinKeyInfo[];
+    /** Intermediate joins absorbed into this CTE for fan-out prevention */
+    intermediateJoins?: IntermediateJoinInfo[];
+    /** CTE type (currently only 'aggregate') */
+    cteType: 'aggregate';
+    /**
+     * Reason for creating this CTE:
+     * - 'hasMany': Direct hasMany target — outer query uses SUM
+     * - 'fanOutPrevention': Affected by hasMany elsewhere — outer query uses MAX
+     */
+    cteReason: 'hasMany' | 'fanOutPrevention';
+}
+/**
+ * Keys-based deduplication for multiplied measures.
+ */
+export interface KeysDeduplication extends LogicalNodeBase {
+    readonly type: 'keysDeduplication';
+    /** SELECT DISTINCT PKs + dims */
+    keysSource: LogicalNode;
+    /** Aggregated measures source */
+    measureSource: LogicalNode;
+    /** Primary key columns to join on */
+    joinOn: ColumnRef[];
+    /** Measure names NOT from the multiplied cube (pre-aggregated in keys CTE) */
+    regularMeasures?: string[];
+}
+/**
+ * Multi-fact merge: combines independent fact subqueries
+ * that share dimensions.
+ */
+export interface MultiFactMerge extends LogicalNodeBase {
+    readonly type: 'multiFactMerge';
+    /** Independent fact subqueries */
+    groups: LogicalNode[];
+    /** Shared dimensions for the merge */
+    sharedDimensions: DimensionRef[];
+    /** How to combine the groups */
+    mergeStrategy: 'fullJoin' | 'leftJoin' | 'innerJoin';
+}
+export type LogicalNode = QueryNode | SimpleSource | FullKeyAggregate | CTEPreAggregate | KeysDeduplication | MultiFactMerge;

package/dist/server/server/measure-classification.d.ts

@@ -0,0 +1,40 @@
+import { Cube } from './types';
+/**
+ * Measure types that are window functions. Window functions require special
+ * handling: no GROUP BY in the CTE, no re-aggregation in the outer query, and
+ * they return individual rows rather than grouped results.
+ */
+export declare const WINDOW_FUNCTION_TYPES: readonly ["lag", "lead", "rank", "denseRank", "rowNumber", "ntile", "firstValue", "lastValue", "movingAvg", "movingSum"];
+/** Check if a measure type is a window function. */
+export declare function isWindowFunction(measureType: string): boolean;
+/**
+ * Check if a measure is a post-aggregation window function.
+ * Post-aggregation windows reference a base `measure` in their windowConfig,
+ * indicating they operate on aggregated data rather than raw rows.
+ */
+export declare function isPostAggregationWindow(measure: any): boolean;
+/**
+ * Resolve the base-measure reference for a post-aggregation window function to a
+ * fully qualified name (e.g. 'totalRevenue' -> 'Sales.totalRevenue').
+ * Returns null when the measure is not a post-aggregation window.
+ */
+export declare function getWindowBaseMeasure(measure: any, cubeName: string): string | null;
+/**
+ * Default operation for a window function type.
+ * - lag/lead default to 'difference' (compare current vs previous/next)
+ * - all others default to 'raw'
+ */
+export declare function getDefaultWindowOperation(windowType: string): 'raw' | 'difference' | 'ratio' | 'percentChange';
+/**
+ * Categorize measures for post-aggregation window-function handling.
+ * - aggregateMeasures: regular aggregates (count, sum, avg, etc.)
+ * - postAggWindowMeasures: window functions referencing a base measure
+ * - requiredBaseMeasures: base measures those windows depend on (auto-added)
+ */
+export declare function categorizeForPostAggregation(measureNames: string[], cubeMap: Map<string, Cube>): {
+    aggregateMeasures: string[];
+    postAggWindowMeasures: string[];
+    requiredBaseMeasures: Set<string>;
+};
+/** Whether any measure in the list is a post-aggregation window function. */
+export declare function hasPostAggregationWindows(measureNames: string[], cubeMap: Map<string, Cube>): boolean;

package/dist/server/server/physical-plan/drizzle-plan-builder.d.ts

@@ -0,0 +1,50 @@
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { DrizzleSqlBuilder } from './drizzle-sql-builder';
+import { CTEBuilder } from '../builders/cte-builder';
+import { PhysicalQueryPlan, QueryContext, SemanticQuery } from '../types';
+import { QueryNode } from '../logical-plan';
+/**
+ * Converts optimised logical plans into runtime physical query plans,
+ * then builds executable Drizzle queries.
+ */
+export declare class DrizzlePlanBuilder {
+    private readonly queryBuilder;
+    private readonly cteBuilder;
+    private readonly databaseAdapter;
+    constructor(queryBuilder: DrizzleSqlBuilder, cteBuilder: CTEBuilder, databaseAdapter: DatabaseAdapter);
+    /**
+     * Build runtime physical context from an optimised logical plan.
+     * This is the physical-builder input for SQL generation.
+     */
+    derivePhysicalPlanContext(plan: QueryNode): PhysicalQueryPlan;
+    /**
+     * Materialize a symbolic JoinRef into a runtime JoinCubePlanEntry, building
+     * the Drizzle join condition(s) from the join definition. This is the seam
+     * where the logical plan's symbolic join refs become executable SQL — the
+     * planner no longer pre-builds any join SQL.
+     *
+     * Junction-table security is NOT materialized here: the stored
+     * `through.securitySql` function is carried forward and applied (in the WHERE
+     * clause) at build time with the request's security context.
+     */
+    private materializeJoin;
+    private derivePhysicalPlanContextFromMultiFact;
+    private derivePhysicalPlanContextFromFullKeyAggregate;
+    /**
+     * Reconstruct a SemanticQuery from a (possibly optimised) QueryNode.
+     *
+     * This is the materialization seam that makes the logical plan a real IR:
+     * the executor derives the query the physical builder consumes from the
+     * optimised plan, so optimiser rewrites of measures/filters/limit/etc. take
+     * effect in the generated SQL. Must faithfully round-trip every field the
+     * physical builder and processors read off a SemanticQuery.
+     */
+    toSemanticQuery(node: QueryNode): SemanticQuery;
+    private resolvePhysicalSimpleSource;
+    private resolvePhysicalSimpleSourceFromKeysDedup;
+    private resolveKeysDeduplicationMeta;
+    /**
+     * Build unified query that works for both single and multi-cube queries.
+     */
+    build(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext): any;
+}

package/dist/server/server/physical-plan/drizzle-sql-builder.d.ts

@@ -0,0 +1,118 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { SemanticQuery, FilterOperator, Filter, Cube, QueryContext, PhysicalQueryPlan } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { ResolvedMeasures } from '../template-substitution';
+export declare class DrizzleSqlBuilder {
+    private dateTimeBuilder;
+    private filterBuilder;
+    private groupByBuilder;
+    private measureBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Build resolvedMeasures map for a set of measures
+     * Delegates to MeasureBuilder
+     */
+    buildResolvedMeasures(measureNames: string[], cubeMap: Map<string, Cube>, context: QueryContext, customMeasureBuilder?: (measureName: string, measure: any, cube: Cube) => SQL): ResolvedMeasures;
+    /**
+     * Build dynamic selections for measures, dimensions, and time dimensions
+     * Works for both single and multi-cube queries
+     * Handles calculated measures with dependency resolution
+     */
+    buildSelections(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext): Record<string, SQL | AnyColumn>;
+    /**
+     * Build calculated measure expression by substituting {member} references
+     * Delegates to MeasureBuilder
+     */
+    buildCalculatedMeasure(measure: any, cube: Cube, allCubes: Map<string, Cube>, resolvedMeasures: ResolvedMeasures, context: QueryContext): SQL;
+    /**
+     * Build resolved measures map for a calculated measure from CTE columns
+     * Delegates to MeasureBuilder
+     */
+    buildCTECalculatedMeasure(measure: any, cube: Cube, cteInfo: {
+        cteAlias: string;
+        measures: string[];
+        cube: Cube;
+    }, allCubes: Map<string, Cube>, context: QueryContext): SQL;
+    /**
+     * Build measure expression for HAVING clause, handling CTE references correctly
+     * Delegates to MeasureBuilder
+     */
+    private buildHavingMeasureExpression;
+    /**
+     * Build measure expression with aggregation and filters
+     * Delegates to MeasureBuilder
+     */
+    buildMeasureExpression(measure: any, context: QueryContext, cube?: Cube): SQL;
+    /**
+     * Build time dimension expression with granularity using database adapter
+     * Delegates to DateTimeBuilder
+     */
+    buildTimeDimensionExpression(dimensionSql: any, granularity: string | undefined, context: QueryContext): SQL;
+    /**
+     * Build WHERE conditions from semantic query filters (dimensions only)
+     * Works for both single and multi-cube queries
+     * @param preBuiltFilters - Optional map of cube name to pre-built filter SQL for parameter deduplication
+     */
+    buildWhereConditions(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: PhysicalQueryPlan, preBuiltFilters?: Map<string, SQL[]>): SQL[];
+    /**
+     * Append a single regular filter's WHERE condition, preferring pre-built
+     * filter SQL (for parameter deduplication) and skipping CTE-handled cubes.
+     */
+    private appendWhereFilter;
+    /** Append a time dimension's date-range WHERE condition (cached when possible). */
+    private appendTimeDimensionWhere;
+    /** Whether a cube is materialized in a pre-aggregation CTE of the plan. */
+    private cubeIsInCTE;
+    /**
+     * Build HAVING conditions from semantic query filters (measures only)
+     * Works for both single and multi-cube queries
+     */
+    buildHavingConditions(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: PhysicalQueryPlan): SQL[];
+    /**
+     * Process a single filter (basic or logical)
+     * @param filterType - 'where' for dimension filters, 'having' for measure filters
+     */
+    private processFilter;
+    /** Build a WHERE condition for a dimension filter, honouring CTE skips and the filter cache. */
+    private processWhereDimensionFilter;
+    /**
+     * Build filter condition using Drizzle operators
+     * Delegates to FilterBuilder
+     */
+    private buildFilterCondition;
+    /**
+     * Build date range condition for time dimensions
+     * Delegates to DateTimeBuilder
+     */
+    buildDateRangeCondition(fieldExpr: AnyColumn | SQL, dateRange: string | string[]): SQL | null;
+    /**
+     * Build GROUP BY fields from dimensions and time dimensions
+     * Delegates to GroupByBuilder
+     */
+    buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: any): (SQL | AnyColumn)[];
+    /**
+     * Build ORDER BY clause with automatic time dimension sorting
+     */
+    buildOrderBy(query: SemanticQuery, selectedFields?: string[]): SQL[];
+    /**
+     * Collect numeric field names (measures + numeric dimensions) for type conversion
+     * Works for both single and multi-cube queries
+     */
+    collectNumericFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery): string[];
+    /**
+     * Apply LIMIT and OFFSET to a query with validation
+     * If offset is provided without limit, add a reasonable default limit
+     */
+    applyLimitAndOffset<T>(query: T, semanticQuery: SemanticQuery): T;
+    /**
+     * Public wrapper for buildFilterCondition - used by executor for cache preloading
+     * This allows pre-building filter SQL before query construction
+     */
+    buildFilterConditionPublic(fieldExpr: AnyColumn | SQL, operator: FilterOperator, values: any[], field?: any, dateRange?: string | string[]): SQL | null;
+    /**
+     * Build a logical filter (AND/OR) - used by executor for cache preloading
+     * This handles nested filter structures and builds combined SQL
+     * Delegates to FilterBuilder
+     */
+    buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
+}

package/dist/server/server/physical-plan/index.d.ts

@@ -0,0 +1,2 @@
+export { DrizzlePlanBuilder } from './drizzle-plan-builder';
+export { DrizzleSqlBuilder } from './drizzle-sql-builder';

package/dist/server/server/physical-plan/processors/cte-processor.d.ts

@@ -0,0 +1,6 @@
+import { PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { PhysicalBuildDependencies, CTEBuildState } from './shared';
+/**
+ * Builds pre-aggregation CTE state used by selection/join/predicate processors.
+ */
+export declare function buildCTEState(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, deps: PhysicalBuildDependencies): CTEBuildState;

package/dist/server/server/physical-plan/processors/index.d.ts

@@ -0,0 +1,8 @@
+export { buildCTEState } from './cte-processor';
+export { buildModifiedSelections } from './selection-processor';
+export { applyJoins } from './joins-processor';
+export { applyPredicatesAndFinalize } from './predicates-processor';
+export { buildKeysDeduplicationQuery } from './keys-dedup-processor';
+export { buildMultiFactMergeQuery } from './multi-fact-processor';
+export type { PhysicalBuildDependencies, CTEBuildState, JoinBuildState, SelectionMap, DownstreamJoinState } from './shared';
+export { getCubesFromPlan } from './shared';

package/dist/server/server/physical-plan/processors/joins-processor.d.ts

@@ -0,0 +1,6 @@
+import { Cube, PhysicalQueryPlan, QueryContext } from '../../types';
+import { CTEBuildState, JoinBuildState, PhysicalBuildDependencies, SelectionMap } from './shared';
+/**
+ * Applies CTEs and JOIN graph construction to the query builder.
+ */
+export declare function applyJoins(queryPlan: PhysicalQueryPlan, context: QueryContext, primaryCubeBase: ReturnType<Cube['sql']>, modifiedSelections: SelectionMap, cteState: CTEBuildState, deps: Pick<PhysicalBuildDependencies, 'cteBuilder'>): JoinBuildState;

package/dist/server/server/physical-plan/processors/keys-dedup-processor.d.ts

@@ -0,0 +1,13 @@
+import { PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { PhysicalBuildDependencies } from './shared';
+/**
+ * Build the dual-CTE keys-deduplication query, or return null when the plan
+ * does not qualify (caller falls back to the standard build).
+ *
+ * The query splits into:
+ *  - a "keys" CTE that groups by the query grain + multiplied cube primary key
+ *    (pre-aggregating regular measures), and
+ *  - a "pk_agg" CTE that pre-aggregates the multiplied cube's measures per PK,
+ * then re-aggregates both in an outer query joined on the primary key.
+ */
+export declare function buildKeysDeduplicationQuery(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, deps: PhysicalBuildDependencies): any | null;

package/dist/server/server/physical-plan/processors/multi-fact-processor.d.ts

@@ -0,0 +1,13 @@
+import { PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { PhysicalBuildDependencies } from './shared';
+/**
+ * Build a function for `build()` so each group CTE can be materialized through
+ * the standard physical-plan builder without a class dependency.
+ */
+export type GroupQueryBuilder = (queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext) => any;
+/**
+ * Build a multi-fact-merge query (joining independent measure groups on shared
+ * grain keys), or return null when the plan does not qualify. Falls back to a
+ * UNION-of-keys strategy when a FULL OUTER JOIN is requested but unsupported.
+ */
+export declare function buildMultiFactMergeQuery(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, deps: PhysicalBuildDependencies, buildGroup: GroupQueryBuilder): any | null;

package/dist/server/server/physical-plan/processors/predicates-processor.d.ts

@@ -0,0 +1,6 @@
+import { Cube, PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { CTEBuildState, JoinBuildState, PhysicalBuildDependencies } from './shared';
+/**
+ * Applies WHERE/GROUP/HAVING/ORDER/LIMIT phases.
+ */
+export declare function applyPredicatesAndFinalize(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, allCubes: Map<string, Cube>, primaryCubeBase: ReturnType<Cube['sql']>, cteState: CTEBuildState, joinState: JoinBuildState, deps: Pick<PhysicalBuildDependencies, 'queryBuilder'>): any;

package/dist/server/server/physical-plan/processors/selection-processor.d.ts

@@ -0,0 +1,6 @@
+import { Cube, PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { PhysicalBuildDependencies, SelectionMap } from './shared';
+/**
+ * Builds and rewrites selections (including CTE and window handling).
+ */
+export declare function buildModifiedSelections(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, allCubes: Map<string, Cube>, deps: Pick<PhysicalBuildDependencies, 'queryBuilder' | 'databaseAdapter'>): SelectionMap;

package/dist/server/server/physical-plan/processors/shared.d.ts

@@ -0,0 +1,38 @@
+import { SQL } from 'drizzle-orm';
+import { DatabaseAdapter } from '../../adapters/base-adapter';
+import { DrizzleSqlBuilder } from '../drizzle-sql-builder';
+import { CTEBuilder } from '../../builders/cte-builder';
+import { Cube, PhysicalQueryPlan } from '../../types';
+export interface PhysicalBuildDependencies {
+    queryBuilder: DrizzleSqlBuilder;
+    cteBuilder: CTEBuilder;
+    databaseAdapter: DatabaseAdapter;
+}
+export interface DownstreamJoinState {
+    cteAlias: string;
+    joinKeys: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+        sourceColumnObj?: any;
+        targetColumnObj?: any;
+    }>;
+}
+export interface CTEBuildState {
+    preBuiltFilterMap: Map<string, SQL[]>;
+    ctes: any[];
+    cteAliasMap: Map<string, string>;
+    downstreamCubeMap: Map<string, DownstreamJoinState>;
+}
+export interface JoinBuildState {
+    drizzleQuery: any;
+    allWhereConditions: SQL[];
+    cubesWithSecurityInJoin: Set<string>;
+    absorbedIntermediateCubes: Set<string>;
+}
+export type SelectionMap = Record<string, any>;
+/**
+ * Apply a join of the given type to a Drizzle query builder.
+ * Shared by the physical-plan builders that assemble CTE/merge queries.
+ */
+export declare function applyJoinByType(drizzleQuery: any, joinType: 'inner' | 'left' | 'right' | 'full', joinTarget: any, joinCondition: SQL): any;
+export declare function getCubesFromPlan(queryPlan: PhysicalQueryPlan): Map<string, Cube>;

package/dist/server/server/physical-plan/processors/window-processor.d.ts

@@ -0,0 +1,6 @@
+import { Cube, PhysicalQueryPlan, QueryContext, SemanticQuery } from '../../types';
+import { PhysicalBuildDependencies, SelectionMap } from './shared';
+/**
+ * Applies post-aggregation window measures to the selection map.
+ */
+export declare function applyPostAggregationWindows(modifiedSelections: SelectionMap, queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext, allCubes: Map<string, Cube>, deps: Pick<PhysicalBuildDependencies, 'queryBuilder' | 'databaseAdapter'>): void;

package/dist/server/server/prompts/explain-analysis-prompt.d.ts

@@ -0,0 +1,47 @@
+import { CubeMetadata } from '../types/metadata.js';
+/**
+ * System prompt template for EXPLAIN plan analysis.
+ *
+ * Placeholders:
+ * - {DATABASE_TYPE} - postgres, mysql, or sqlite
+ * - {CUBE_SCHEMA} - JSON-formatted cube schema with relationships
+ * - {SEMANTIC_QUERY} - The original semantic query object
+ * - {SQL_QUERY} - The generated SQL query
+ * - {NORMALIZED_PLAN} - JSON of normalized ExplainOperation[]
+ * - {RAW_EXPLAIN} - Raw EXPLAIN output from database
+ */
+export declare const EXPLAIN_ANALYSIS_PROMPT = "You are a database performance expert analyzing query execution plans for a semantic layer (Cube.js/drizzle-cube).\n\nCRITICAL CONTEXT - READ CAREFULLY:\nThe user is working with a semantic layer that auto-generates SQL queries. They do NOT write or modify SQL directly.\n\nTherefore, your recommendations MUST focus ONLY on:\n1. INDEX CREATION - Specific CREATE INDEX statements they can run\n2. TABLE STRUCTURE - Schema changes (column types, constraints)\n3. CUBE CONFIGURATION - How cube definitions (joins, filters) might be improved\n4. GENERAL INSIGHTS - Understanding what makes the query slow\n\nDO NOT recommend:\n- Rewriting the SQL query (users can't do this)\n- Changing JOIN order (the semantic layer handles this)\n- Using different query patterns (CTEs, subqueries, etc.)\n- Any SQL modification beyond index/schema changes\n\nDATABASE TYPE: {DATABASE_TYPE}\n\nCUBE DEFINITION SYNTAX (drizzle-cube):\nUsers define cubes in TypeScript like this. There are TWO valid syntax patterns for security context:\n\nPATTERN 1 - Simple WHERE filter (older syntax):\n```typescript\nconst employeesCube = defineCube({\n  name: 'Employees',\n  // Security filter - returns just the WHERE condition\n  sql: (securityContext) => eq(employees.organisationId, securityContext.organisationId),\n  // ...\n})\n```\n\nPATTERN 2 - Full QueryContext with BaseQueryDefinition (recommended):\n```typescript\nconst employeesCube = defineCube({\n  name: 'Employees',\n  // Security filter - returns object with 'from' and 'where'\n  sql: (ctx: QueryContext<Schema>): BaseQueryDefinition => ({\n    from: employees,\n    where: eq(employees.organisationId, ctx.securityContext.organisationId)\n  }),\n  // ...\n})\n```\n\nBOTH patterns correctly implement security context filtering. The key is:\n- Pattern 1: The function receives securityContext directly and returns a WHERE condition\n- Pattern 2: The function receives ctx (QueryContext) and accesses ctx.securityContext\n\nFULL CUBE EXAMPLE:\n```typescript\nconst employeesCube = defineCube({\n  name: 'Employees',\n  // Security filter using Pattern 2 (recommended)\n  sql: (ctx: QueryContext<Schema>): BaseQueryDefinition => ({\n    from: employees,\n    where: eq(employees.organisationId, ctx.securityContext.organisationId)\n  }),\n\n  // Joins to other cubes\n  joins: {\n    Departments: {\n      targetCube: () => departmentsCube,\n      relationship: 'belongsTo',  // or 'hasOne', 'hasMany', 'belongsToMany'\n      on: [{ source: employees.departmentId, target: departments.id }]\n    }\n  },\n\n  measures: {\n    count: { type: 'count', sql: () => employees.id },\n    avgSalary: { type: 'avg', sql: () => employees.salary }\n  },\n\n  dimensions: {\n    name: { type: 'string', sql: () => employees.name },\n    createdAt: { type: 'time', sql: () => employees.createdAt }\n  }\n})\n```\n\nSECURITY CONTEXT VALIDATION:\nWhen checking if a cube has proper security context, look for EITHER:\n- `sql: (securityContext) => eq(table.organisationId, securityContext.organisationId)`\n- `sql: (ctx) => ({ from: table, where: eq(table.organisationId, ctx.securityContext.organisationId) })`\n- Any variation that filters by organisationId using the security context parameter\n\nA cube is MISSING security context ONLY if:\n- The sql function doesn't use the securityContext/ctx parameter at all\n- There's no filter on organisationId (or equivalent tenant identifier)\n- The sql property is missing entirely\n\nCUBE RECOMMENDATION TYPES:\nWhen suggesting cube changes, ONLY recommend features that drizzle-cube supports:\n\nSUPPORTED FEATURES:\n- dimensions (with sql expressions)\n- measures (count, sum, avg, min, max, countDistinct, countDistinctApprox)\n- joins (belongsTo, hasOne, hasMany, belongsToMany)\n- security context filtering via sql function\n\nNOT SUPPORTED (do NOT recommend these):\n- preAggregations (not implemented)\n- segments (not implemented)\n- refreshKey (not implemented)\n- scheduledRefresh (not implemented)\n\n1. ADDING JOINS - If queries frequently combine cubes without explicit joins:\n   ```typescript\n   joins: {\n     TargetCube: {\n       targetCube: () => targetCube,\n       relationship: 'belongsTo',  // or 'hasOne', 'hasMany', 'belongsToMany'\n       on: [{ source: table.foreignKey, target: targetTable.id }]\n     }\n   }\n   ```\n\n2. OPTIMIZING BASE QUERY FILTERS (ONLY if SQL lacks tenant filtering):\n   NOTE: If the SQL already filters by organisation_id, tenant_id, or similar, the cube is correctly configured.\n   Only suggest this if security/tenant filtering is genuinely missing from the generated SQL.\n   ```typescript\n   sql: (ctx: QueryContext<Schema>): BaseQueryDefinition => ({\n     from: table,\n     where: and(\n       eq(table.organisationId, ctx.securityContext.organisationId),\n       eq(table.isActive, true)  // Add commonly-used filters to base query\n     )\n   })\n   ```\n\n3. ADDING CALCULATED MEASURES - For commonly-needed aggregations:\n   ```typescript\n   measures: {\n     averageOrderValue: {\n       type: 'avg',\n       sql: () => orders.total\n     },\n     activeUserCount: {\n       type: 'count',\n       sql: () => users.id,\n       filters: [{ sql: () => eq(users.isActive, true) }]\n     }\n   }\n   ```\n\nCUBE SCHEMA (the semantic layer structure):\n{CUBE_SCHEMA}\n\nSEMANTIC QUERY (what the user requested):\n{SEMANTIC_QUERY}\n\nGENERATED SQL:\n{SQL_QUERY}\n\nEXECUTION PLAN (normalized format):\n{NORMALIZED_PLAN}\n\nRAW EXPLAIN OUTPUT:\n{RAW_EXPLAIN}\n\nEXISTING INDEXES ON RELEVANT TABLES:\n{EXISTING_INDEXES}\n\nIMPORTANT: Before recommending an index, check if it already exists above. If an index already exists:\n- Do NOT recommend creating it again\n- Instead, note that the index exists and analyze whether it's being used effectively\n- If the index exists but isn't being used, recommend investigating why (wrong column order, statistics outdated, etc.)\n\nIMPORTANT: Before recommending security context optimizations, CHECK THE SQL QUERY above for existing filters:\n- Look for tenant/security filters like: organisation_id, organizationId, tenant_id, tenantId, org_id, orgId, company_id, companyId, or similar\n- If the SQL already contains parameterized filters on any of these columns (e.g., \"organisation_id = $1\", \"tenant_id = ?\"), security context IS ALREADY IMPLEMENTED\n- Do NOT suggest \"add security context\" or \"optimize base query filters\" if the SQL already filters by a tenant identifier\n- drizzle-cube AUTOMATICALLY applies security context to all queries - if you see tenant filters in the SQL, the cube is correctly configured\n- Only suggest security filter optimizations if the SQL genuinely lacks tenant filtering (which would be a serious bug)\n\nANALYSIS TASKS:\n\n1. UNDERSTAND THE QUERY\n   - What business question is this answering?\n   - What cubes and relationships are involved?\n   - What aggregations and filters are applied?\n\n2. IDENTIFY PERFORMANCE ISSUES\n   - Sequential scans on large tables (look for \"Seq Scan\" / \"ALL\" access)\n   - Missing indexes (filters/joins on unindexed columns)\n   - High row estimates with filters that could benefit from indexes\n   - Sort operations that could use indexes\n\n3. GENERATE ACTIONABLE RECOMMENDATIONS\n   For each issue, provide:\n   - Specific CREATE INDEX statement (if applicable)\n   - Exact table and column names\n   - Expected impact estimate\n   - {DATABASE_TYPE}-specific syntax\n\nINDEX SYNTAX BY DATABASE:\n- PostgreSQL: CREATE INDEX idx_name ON table_name (column1, column2);\n- MySQL: CREATE INDEX idx_name ON table_name (column1, column2);\n- SQLite: CREATE INDEX idx_name ON table_name (column1, column2);\n\nCOMPOSITE INDEX GUIDANCE:\n- For filters: Index columns used in WHERE clauses\n- For joins: Index foreign key columns (e.g., department_id, organisation_id)\n- For sorting: Include ORDER BY columns in index\n- Multi-tenant: Always consider including organisation_id in composite indexes\n\nRESPONSE FORMAT (JSON):\n{\n  \"summary\": \"Brief description of what this query does\",\n  \"assessment\": \"good|warning|critical\",\n  \"assessmentReason\": \"Why this assessment\",\n  \"queryUnderstanding\": \"Detailed explanation of the query's purpose and structure\",\n  \"issues\": [\n    {\n      \"type\": \"sequential_scan|missing_index|high_cost|sort_operation\",\n      \"description\": \"What the issue is\",\n      \"severity\": \"high|medium|low\"\n    }\n  ],\n  \"recommendations\": [\n    {\n      \"type\": \"index\",\n      \"severity\": \"critical|warning|suggestion\",\n      \"title\": \"Short actionable title\",\n      \"description\": \"Detailed explanation of why this helps\",\n      \"sql\": \"CREATE INDEX idx_name ON table (columns);\",\n      \"table\": \"table_name\",\n      \"columns\": [\"col1\", \"col2\"],\n      \"estimatedImpact\": \"Expected improvement\"\n    },\n    {\n      \"type\": \"cube\",\n      \"severity\": \"critical|warning|suggestion\",\n      \"title\": \"Short actionable title\",\n      \"description\": \"Why this cube change helps\",\n      \"cubeCode\": \"TypeScript snippet to add to the cube definition\",\n      \"cubeName\": \"CubeName\",\n      \"estimatedImpact\": \"Expected improvement\"\n    }\n  ]\n}\n\nCRITICAL: Return ONLY valid JSON. No markdown, no explanations outside JSON.";
+/**
+ * Build the complete EXPLAIN analysis prompt with all context
+ *
+ * @param databaseType - The database engine type
+ * @param cubeSchema - JSON-formatted cube schema
+ * @param semanticQuery - JSON of the original semantic query
+ * @param sqlQuery - The generated SQL query
+ * @param normalizedPlan - JSON of the normalized ExplainOperation[]
+ * @param rawExplain - Raw EXPLAIN output from the database
+ * @param existingIndexes - Optional: JSON of existing indexes on relevant tables
+ * @returns Complete prompt ready to send to AI
+ */
+export declare function buildExplainAnalysisPrompt(databaseType: 'postgres' | 'mysql' | 'sqlite', cubeSchema: string, semanticQuery: string, sqlQuery: string, normalizedPlan: string, rawExplain: string, existingIndexes?: string): string;
+/**
+ * Format cube metadata for AI consumption
+ * Includes relationships and joins for full context
+ *
+ * @param metadata - Array of CubeMetadata from the semantic layer
+ * @returns JSON string formatted for the AI prompt
+ */
+export declare function formatCubeSchemaForExplain(metadata: CubeMetadata[]): string;
+/**
+ * Format existing indexes for AI consumption
+ *
+ * @param indexes - Array of index information from database query
+ * @returns Formatted string for the AI prompt
+ */
+export declare function formatExistingIndexes(indexes: Array<{
+    table_name: string;
+    index_name: string;
+    columns: string[];
+    is_unique?: boolean;
+    is_primary?: boolean;
+}>): string;

package/dist/server/server/prompts/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AI Prompt Templates for Drizzle Cube Query Generation
+ *
+ * This module provides the system prompts used for AI-assisted query building.
+ * The prompts power a multi-stage generation flow:
+ *
+ * 0. **Step 0 - Validation**: Validate input for security and relevance
+ *    - Uses STEP0_VALIDATION_PROMPT (fast/cheap model recommended)
+ *
+ * 1. **Single-Step Flow**: Used when no dimension values need to be fetched
+ *    - Uses SYSTEM_PROMPT_TEMPLATE directly
+ *
+ * 2. **Multi-Stage Flow**: Used when dimension values are needed for filters
+ *    - Step 1: Analyze query shape (STEP1_SYSTEM_PROMPT)
+ *    - Step 2: Fetch dimension values from database (with security context)
+ *    - Step 3: Generate final query (STEP2_SYSTEM_PROMPT)
+ *
+ * @see https://github.com/cliftonc/drizzle-cube/tree/main/src/server/prompts
+ * @module
+ */
+export type { PromptContext, DimensionValues, Step1Result } from './types.js';
+export type { Step0Result } from './step0-validation-prompt.js';
+export { STEP0_VALIDATION_PROMPT, buildStep0Prompt } from './step0-validation-prompt.js';
+export { SYSTEM_PROMPT_TEMPLATE, buildSystemPrompt } from './single-step-prompt.js';
+export { STEP1_SYSTEM_PROMPT, buildStep1Prompt } from './step1-shape-prompt.js';
+export { STEP2_SYSTEM_PROMPT, buildStep2Prompt } from './step2-complete-prompt.js';
+export { EXPLAIN_ANALYSIS_PROMPT, buildExplainAnalysisPrompt, formatCubeSchemaForExplain, formatExistingIndexes } from './explain-analysis-prompt.js';