drizzle-cube 0.5.8 → 0.6.0

package/dist/server/server/executor.d.ts

@@ -1,4 +1,5 @@
 import { SecurityContext, SemanticQuery, QueryResult, DatabaseExecutor, Cube, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, QueryAnalysis, RLSSetupFn } from './types';
+import { PlanOptimiser } from './logical-plan';
 export declare class QueryExecutor {
     private dbExecutor;
     private queryBuilder;
@@ -8,11 +9,13 @@ export declare class QueryExecutor {
     private funnelQueryBuilder;
     private flowQueryBuilder;
     private retentionQueryBuilder;
-    private cacheConfig?;
     private logicalPlanBuilder;
     private planOptimiser;
+    private modeRouter;
+    private resultCache;
+    private filterCachePreloader;
     private rlsSetup?;
-    constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig, rlsSetup?: RLSSetupFn);
+    constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig, rlsSetup?: RLSSetupFn, planOptimiser?: PlanOptimiser);
     /**
      * Execute a function within a RLS-configured transaction context.
      * If no rlsSetup function is configured, the function is called directly.
@@ -55,34 +58,41 @@ export declare class QueryExecutor {
     private executeComparisonQuery;
     private buildComparisonExecutionPlan;
     /**
-     * Execute a funnel query with caching support
+     * Execute an analysis query (funnel/flow/retention) with caching support.
+     * Wraps the inner execute callback with cache-set logic; the three analysis
+     * modes share identical wrapper behaviour, differing only in which inner
+     * execute method they invoke.
+     *
+     * Cache metadata is intentionally NOT attached here: fresh results across all
+     * query modes (regular, comparison, and analysis) uniformly carry no `cache`
+     * field — only cache *hits* (handled in execute()) carry cache metadata.
      */
-    private executeFunnelQueryWithCache;
+    private executeAnalysisQueryWithCache;
     /**
      * Execute a funnel analysis query
      */
     private executeFunnelQuery;
-    /**
-     * Execute a flow query with caching support
-     */
-    private executeFlowQueryWithCache;
     /**
      * Execute a flow analysis query
      * Produces Sankey diagram data (nodes and links)
      */
     private executeFlowQuery;
-    /**
-     * Execute a retention query with caching support
-     */
-    private executeRetentionQueryWithCache;
     /**
      * Execute a retention analysis query
      * Calculates cohort-based retention rates
      */
     private executeRetentionQuery;
     /**
-     * Standard query execution (non-comparison)
-     * This is the core execution logic extracted for use by comparison queries
+     * Standard (regular/non-comparison) query execution.
+     *
+     * This is the single core execution path used by both the regular query mode
+     * and comparison-mode period sub-queries. It always runs the dev-time
+     * security-context validation and propagates planner warnings; the optional
+     * `cacheKey` controls whether the fresh result is written to the cache.
+     *
+     * @param cacheKey - When provided (and a cache provider is configured), the
+     *   fresh result is written to the cache. Pass `undefined` to skip caching
+     *   (e.g. comparison period sub-queries cache at the comparison level).
      */
     private executeStandardQuery;
     /**
@@ -90,8 +100,9 @@ export declare class QueryExecutor {
      */
     private createQueryContext;
     /**
-     * Normalize engine type for optimiser passes.
-     * SingleStore follows MySQL SQL semantics for planner choices.
+     * Resolve the real database engine type for optimiser passes.
+     * Returns the true engine for all 7 supported engines (no collapsing);
+     * passes decide for themselves whether to treat e.g. SingleStore like MySQL.
      */
     private getOptimiserEngineType;
     /**
@@ -145,6 +156,12 @@ export declare class QueryExecutor {
         sql: string;
         params?: any[];
     }>;
+    /**
+     * Generic dry-run SQL generator for analysis modes (funnel/flow/retention).
+     * The three modes share an identical shape (mode guard → config validation →
+     * build query → toSQL()), differing only in which builder/config they use.
+     */
+    private dryRunAnalysis;
     /**
      * Execute EXPLAIN on a query to get the execution plan
      * Generates the SQL using the same secure path as execute/generateSQL,
@@ -163,21 +180,7 @@ export declare class QueryExecutor {
      * Generate SQL using unified approach (works for both single and multi-cube)
      */
     private generateUnifiedSQL;
-    private resolveQueryMode;
-    private validateQueryForMode;
     private executeQueryByModeWithCache;
-    private executeRegularQueryWithCache;
-    private cacheResult;
     private generateSqlForMode;
     private generateComparisonSQL;
-    /**
-     * Generate annotations for UI metadata - unified approach
-     */
-    private generateAnnotations;
-    /**
-     * Pre-build filter SQL and store in cache for reuse across CTEs and main query
-     * This enables parameter deduplication - the same filter values are shared
-     * rather than appearing as separate parameters in different parts of the query
-     */
-    private preloadFilterCache;
 }

package/dist/server/server/executors/explain-utils.d.ts

@@ -0,0 +1,28 @@
+import { SQL } from 'drizzle-orm';
+/**
+ * Rebuild a parameterized SQL string into a Drizzle SQL object with `params`
+ * bound as real driver parameters.
+ *
+ * @param sqlString - SQL produced by Drizzle's `.toSQL()`, containing either `?`
+ *   placeholders (mysql/sqlite/singlestore/snowflake) or `$n` placeholders
+ *   (postgres/duckdb/databend)
+ * @param params - Bound parameter values, in order
+ * @param style - Placeholder style used by `sqlString`
+ */
+export declare function buildBoundSql(sqlString: string, params: unknown[], style: 'question' | 'dollar'): SQL;
+/**
+ * Normalize raw MySQL EXPLAIN result rows into the column shape the MySQL parser
+ * expects. Extracted from MySQLExecutor.explainQuery to keep that method simple.
+ */
+export declare function normalizeMySQLExplainRows(result: unknown): any[];
+/**
+ * Normalize raw SQLite EXPLAIN QUERY PLAN result rows into the column shape the
+ * SQLite parser expects. Extracted from SQLiteExecutor.explainQuery.
+ */
+export declare function normalizeSQLiteExplainRows(result: unknown): any[];
+/**
+ * Extract the textual plan lines from PostgreSQL EXPLAIN result rows. Handles the
+ * differing column-name casing across drivers. Extracted from
+ * PostgresExecutor.explainQuery.
+ */
+export declare function extractPostgresExplainLines(rows: any[]): string[];

package/dist/server/server/explain/explain-tree.d.ts

@@ -0,0 +1,20 @@
+import { ExplainOperation } from '../types/executor';
+/** Stack entry tracking an operation and its indentation depth. */
+export interface ExplainStackEntry {
+    indent: number;
+    op: ExplainOperation;
+}
+/**
+ * Insert an operation into the hierarchical tree using the indentation stack.
+ *
+ * Pops the stack until the top entry has strictly less indentation than the
+ * incoming operation, then attaches the operation either as a root (pushed to
+ * `operations`) or as a child of the current stack top. Finally pushes the
+ * operation onto the stack so subsequent deeper lines can nest under it.
+ */
+export declare function pushOperationToTree(stack: ExplainStackEntry[], operations: ExplainOperation[], operation: ExplainOperation, indent: number): void;
+/**
+ * Count indentation level based on tree drawing characters and spaces.
+ * Used by DuckDB and Databend parsers.
+ */
+export declare function countTreeIndent(line: string): number;

package/dist/server/server/filter-cache.d.ts

@@ -1,5 +1,5 @@
 import { SQL } from 'drizzle-orm';
-import { Filter, FilterCondition } from './types';
+import { Filter, FilterCondition, FilterCache } from './types';
 /**
  * Generates a deterministic cache key for a filter
  * Keys are based on filter content (member, operator, values) not object identity
@@ -26,7 +26,7 @@ export interface FilterCacheStats {
  * - Key by content: Filters with same member/operator/values share SQL
  * - Thread-safe: No shared mutable state between queries
  */
-export declare class FilterCacheManager {
+export declare class FilterCacheManager implements FilterCache {
     private cache;
     private stats;
     /**

package/dist/server/server/gap-filler.d.ts

@@ -1,5 +1,11 @@
 import { SemanticQuery } from './types/query';
 import { TimeGranularity } from './types/core';
+/**
+ * Maximum number of time buckets gap filling will generate. Beyond this, gap
+ * filling is skipped entirely (data is returned unmodified) to avoid both
+ * runaway memory use and silent truncation of real rows.
+ */
+export declare const MAX_GAP_FILL_BUCKETS = 10000;
 export interface GapFillerConfig {
     /** The time dimension key (e.g., 'Sales.date') */
     timeDimensionKey: string;

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

@@ -6,6 +6,8 @@ import { SemanticLayerCompiler } from './compiler';
  */
 export { SemanticLayerCompiler } from './compiler';
 export { QueryExecutor } from './executor';
+export { detectQueryMode, detectQueryModes, getActiveQueryModes, hasComparisonMode, hasFunnelMode, hasFlowMode, hasRetentionMode } from './query-modes';
+export type { QueryMode, QueryModeFlags } from './query-modes';
 export { LogicalPlanner } from './logical-plan';
 export { DrizzleSqlBuilder } from './physical-plan';
 export { CTEBuilder, ComparisonQueryBuilder, FunnelQueryBuilder, FlowQueryBuilder, RetentionQueryBuilder } from './builders';
@@ -16,7 +18,7 @@ export { DrizzlePlanBuilder } from './physical-plan';
 export { createDatabaseExecutor, createPostgresExecutor, createSQLiteExecutor, createMySQLExecutor, createDuckDBExecutor, createDatabendExecutor, createSnowflakeExecutor, BaseDatabaseExecutor, PostgresExecutor, SQLiteExecutor, MySQLExecutor, DuckDBExecutor, DatabendExecutor, SnowflakeExecutor } from './executors';
 export { resolveSqlExpression, createMultiCubeContext, resolveCubeReference, getJoinType } from './cube-utils';
 export { defineCube } from './cube-utils';
-export { generateCacheKey, normalizeQuery, fnv1aHash, getCubeInvalidationPattern } from './cache-utils';
+export { generateCacheKey, normalizeQuery, fnv1aHash, strongHash, getCubeInvalidationPattern } from './cache-utils';
 export { MemoryCacheProvider } from './cache-providers';
 export { STEP0_VALIDATION_PROMPT, SYSTEM_PROMPT_TEMPLATE, STEP1_SYSTEM_PROMPT, STEP2_SYSTEM_PROMPT, buildStep0Prompt, buildSystemPrompt, buildStep1Prompt, buildStep2Prompt, EXPLAIN_ANALYSIS_PROMPT, buildExplainAnalysisPrompt, formatCubeSchemaForExplain, formatExistingIndexes } from './prompts';
 export type { Step0Result, PromptContext, DimensionValues, Step1Result } from './prompts';

package/dist/server/server/logical-plan/cte-planner-helpers.d.ts

@@ -0,0 +1,37 @@
+import { Cube, CubeJoin, SemanticQuery } from '../types';
+/** A resolved CTE join key (column names plus the underlying column objects). */
+export interface CTEJoinKey {
+    sourceColumn: string;
+    targetColumn: string;
+    sourceColumnObj: any;
+    targetColumnObj: any;
+}
+/** A join definition located relative to a primary/target cube pair. */
+export interface FoundJoinInfo {
+    sourceCube: Cube;
+    joinDef: CubeJoin;
+    reversed?: boolean;
+}
+/**
+ * Derive the CTE join keys for a located join definition, handling
+ * belongsToMany junctions and reversed (belongsTo-back-to-primary) joins.
+ */
+export declare function deriveCTEJoinKeys(joinInfo: FoundJoinInfo, primaryCube: Cube): CTEJoinKey[];
+/**
+ * Derive the join keys connecting a downstream dimension cube through the CTE
+ * cube, handling belongsToMany (via junction sourceKey) and regular joins.
+ */
+export declare function deriveDownstreamJoinKeys(joinDef: CubeJoin): CTEJoinKey[];
+/**
+ * Find join information for a target cube, searching (in priority order):
+ * 1. The primary cube's direct join to the target.
+ * 2. The target cube's join back to the primary (reverse lookup → reversed).
+ * 3. Any other registered cube's join to the target.
+ */
+export declare function findJoinInfoForCube(cubes: Map<string, Cube>, primaryCube: Cube, targetCubeName: string): FoundJoinInfo | null;
+/**
+ * Collect the names of cubes (other than the CTE cube) that contribute
+ * dimensions, time dimensions, or filter members to the query. These are the
+ * candidate downstream cubes that may need to join through the CTE.
+ */
+export declare function collectDimensionCubeNames(query: SemanticQuery, cteCubeName: string): Set<string>;

package/dist/server/server/logical-plan/cte-planner.d.ts

@@ -0,0 +1,104 @@
+import { Cube, QueryContext, PhysicalQueryPlan, SemanticQuery } from '../types';
+import { ResolverCache } from './planner-utils';
+import { FilterPropagation } from './filter-propagation';
+import { JoinRef } from './types';
+export declare class CTEPlanner {
+    private readonly resolverCache;
+    private readonly filterPropagation;
+    constructor(resolverCache: ResolverCache, filterPropagation: FilterPropagation);
+    /**
+     * Plan pre-aggregation CTEs for hasMany relationships to prevent fan-out
+     * Note: belongsToMany relationships handle fan-out differently through their junction table structure
+     * and don't require CTEs - the two-hop join with the junction table provides natural grouping
+     *
+     * CRITICAL FAN-OUT PREVENTION LOGIC:
+     * When a query contains ANY hasMany relationship in the join graph, ALL cubes with measures
+     * that could be affected by row multiplication need CTEs. This includes:
+     *
+     * 1. Cubes with direct hasMany FROM primary (existing logic)
+     * 2. Cubes with measures that would be multiplied due to hasMany elsewhere in the query
+     *    - Example: Query has Departments.totalBudget + Productivity.recordCount
+     *    - Employees hasMany → Productivity causes row multiplication
+     *    - Departments.totalBudget would be inflated without CTE pre-aggregation
+     */
+    planPreAggregationCTEs(cubes: Map<string, Cube>, primaryCube: Cube, joinCubes: JoinRef[], query: SemanticQuery, _ctx: QueryContext): PhysicalQueryPlan['preAggregationCTEs'];
+    /**
+     * Build a single pre-aggregation CTE for one join-cube entry, or return null
+     * when the cube contributes no aggregate measures / has no resolvable join.
+     */
+    private buildCTEForJoinCube;
+    /**
+     * Resolve the join keys (and any intermediate joins to absorb) for a CTE cube.
+     *
+     * Analyses the path from primary to the CTE cube: if an intermediate hasMany
+     * exists, returns the corrected keys plus intermediate joins; otherwise locates
+     * the join definition and derives keys from it.
+     */
+    private resolveCTEJoinKeys;
+    /**
+     * Locate the join definition for a CTE cube, preferring the final step of the
+     * analysed path and falling back to a primary/reverse/any-cube search.
+     */
+    private locateJoinInfo;
+    /**
+     * Analyze the join path from primary cube to a target CTE cube.
+     * Detects if there are intermediate hasMany relationships that would cause fan-out.
+     *
+     * Returns information about:
+     * - The full join path
+     * - Whether there are hasMany relationships ON the path (not just at the end)
+     * - Which intermediate tables need to be absorbed into the CTE
+     * - The correct join key to use (from primary cube's connection point)
+     *
+     * @param cubes Map of all registered cubes
+     * @param primaryCube The primary cube (FROM clause)
+     * @param targetCubeName The CTE cube we're analyzing the path to
+     * @param query The semantic query (drives query-aware path selection)
+     */
+    private analyzeJoinPathToPrimary;
+    /**
+     * Compute CTE reasons from the actual join plan entries.
+     *
+     * Instead of scanning all registered cubes (which causes false positives when
+     * unrelated hasMany relationships exist), this walks only the planned joins
+     * using the `relationship` field now stored on each JoinCubePlanEntry.
+     *
+     * Algorithm:
+     * 1. Scan join plan entries for hasMany/belongsToMany relationships
+     * 2. If none found → return empty map (no CTEs needed)
+     * 3. hasMany/belongsToMany targets with measures → 'hasMany'
+     * 4. Other join cubes with measures (not hasMany source) → 'fanOutPrevention'
+     */
+    private computeCTEReasons;
+    /**
+     * Find downstream cubes that need join keys included in the CTE.
+     *
+     * When a query has dimensions from a cube (e.g., Teams.name) and measures from
+     * a junction cube (e.g., EmployeeTeams.count), the junction CTE needs to include
+     * the join key to the dimension cube (team_id) so the dimension cube can be
+     * joined through the CTE instead of via an alternative path.
+     *
+     * @param cteCube The cube being converted to a CTE (e.g., EmployeeTeams)
+     * @param query The semantic query with dimensions and measures
+     * @param allCubes Map of all registered cubes
+     * @returns Array of downstream join key info for cubes needing join through this CTE
+     */
+    private findDownstreamJoinKeys;
+    /**
+     * Expand calculated measures to include their dependencies
+     */
+    private expandCalculatedMeasureDependencies;
+    /**
+     * Extract measure references from calculatedSql template
+     */
+    private extractDependenciesFromTemplate;
+    /**
+     * Extract measures referenced in filters (for CTE inclusion)
+     */
+    private extractMeasuresFromFilters;
+    /**
+     * Recursively extract measures from filters for a specific cube
+     * Only includes filter members that are actually measures (not dimensions)
+     */
+    private extractMeasuresFromFilter;
+}

package/dist/server/server/logical-plan/filter-propagation.d.ts

@@ -0,0 +1,44 @@
+import { Cube, SemanticQuery, PropagatingFilter, Filter } from '../types';
+export declare class FilterPropagation {
+    /**
+     * Find filters that need to propagate from related cubes to a CTE cube.
+     * When cube A has filters and a hasMany relationship to cube B (the CTE cube),
+     * A's filters should propagate into B's CTE via a subquery.
+     *
+     * Example: Employees.createdAt filter should propagate to Productivity CTE
+     * via: employee_id IN (SELECT id FROM employees WHERE created_at >= $date)
+     */
+    findPropagatingFilters(query: SemanticQuery, cteCube: Cube, allCubes: Map<string, Cube>): PropagatingFilter[];
+    /**
+     * Collect cube names referenced by filters and by time-dimension date ranges.
+     */
+    private collectFilterCubeNames;
+    /**
+     * Build a single PropagatingFilter for a filterCube → cteCube hasMany edge,
+     * or null when the cube contributes no filters / the join has no keys.
+     */
+    private buildPropagatingFilter;
+    /**
+     * Extract cube names from filters into a Set (helper for findPropagatingFilters)
+     */
+    extractFilterCubeNamesToSet(filters: Filter[], cubesSet: Set<string>): void;
+    /**
+     * Extract filters for a specific cube from the filter array
+     *
+     * Logic for preserving filter semantics:
+     * - AND: Safe to extract only matching branches (AND of fewer conditions is more permissive)
+     * - OR: Must include ALL branches or skip entirely (partial OR changes semantics)
+     *       If any branch belongs to another cube, skip the entire OR to be safe
+     *       since we can't evaluate the other cube's conditions
+     */
+    extractFiltersForCube(filters: Filter[], targetCubeName: string): Filter[];
+    /**
+     * Check if all simple filters in a filter array belong to the specified cube
+     * Recursively checks nested AND/OR filters
+     */
+    allFiltersFromCube(filters: Filter[], targetCubeName: string): boolean;
+    /**
+     * Extract time dimension date range filters as regular filters for a specific cube
+     */
+    extractTimeDimensionFiltersForCube(query: SemanticQuery, targetCubeName: string): Filter[];
+}

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

@@ -10,5 +10,10 @@ export type { LogicalNode, LogicalNodeType, LogicalNodeBase, QueryNode, SimpleSo
 export { LogicalPlanner } from './logical-planner';
 export { LogicalPlanBuilder } from './logical-plan-builder';
 export type { LogicalPlanWithAnalysis } from './logical-plan-builder';
-export type { PlanOptimiser, OptimiserContext } from './optimiser';
+export { JoinPlanner } from './join-planner';
+export { CTEPlanner } from './cte-planner';
+export { FilterPropagation } from './filter-propagation';
+export { PlanAnalysisReporter } from './plan-analysis-reporter';
+export { ResolverCache, analyzeCubeUsage, extractCubeNamesFromFilter } from './planner-utils';
+export type { PlanOptimiser, OptimiserContext, OptimiserEngineType } from './optimiser';
 export { IdentityOptimiser, OptimiserPipeline } from './optimiser';

package/dist/server/server/logical-plan/join-planner.d.ts

@@ -0,0 +1,27 @@
+import { Cube, CubeJoin, SemanticQuery } from '../types';
+import { ResolverCache } from './planner-utils';
+import { JoinRef } from './types';
+export declare class JoinPlanner {
+    private readonly resolverCache;
+    constructor(resolverCache: ResolverCache);
+    /**
+     * Build join plan for multi-cube query
+     * Supports both direct joins and transitive joins through intermediate cubes
+     *
+     * Uses query-aware path selection to prefer joining through cubes that have
+     * measures in the query (e.g., joining Teams through EmployeeTeams when
+     * EmployeeTeams.count is a measure)
+     */
+    buildJoinPlan(cubes: Map<string, Cube>, primaryCube: Cube, cubeNames: string[], _ctx: unknown, query: SemanticQuery): JoinRef[];
+    /**
+     * Build a single symbolic JoinRef for a join-path step. Handles belongsToMany
+     * (junction-table) joins and regular (belongsTo/hasOne/hasMany) joins. The join
+     * conditions and security WHERE are materialized later by DrizzlePlanBuilder;
+     * only the join type is resolved here (it depends on the effective relationship).
+     */
+    private buildJoinRef;
+    /**
+     * Find hasMany join definition from primary cube to target cube
+     */
+    findHasManyJoinDef(primaryCube: Cube, targetCubeName: string, cubes?: Map<string, Cube>): CubeJoin | null;
+}