drizzle-cube 0.5.7 → 0.6.0

package/dist/server/server/compiler-metadata.d.ts

@@ -0,0 +1,11 @@
+import { Cube, MeasureMetadata, DimensionMetadata, CubeRelationshipMetadata, HierarchyMetadata, TimeGranularity } from './types';
+/** Default time granularities used when a time dimension omits `granularities`. */
+export declare const DEFAULT_TIME_GRANULARITIES: TimeGranularity[];
+/** Build measure metadata, normalizing drillMembers to fully-qualified names. */
+export declare function buildMeasureMetadata(cube: Cube): MeasureMetadata[];
+/** Build dimension metadata, including granularities for time dimensions. */
+export declare function buildDimensionMetadata(cube: Cube): DimensionMetadata[];
+/** Build relationship metadata from a cube's joins, resolving target cubes. */
+export declare function buildRelationshipMetadata(cube: Cube, cubes: Map<string, Cube>, getColumnName: (column: any) => string): CubeRelationshipMetadata[];
+/** Build hierarchy metadata, qualifying level names to full member names. */
+export declare function buildHierarchyMetadata(cube: Cube): HierarchyMetadata[];

package/dist/server/server/compiler.d.ts

@@ -0,0 +1,212 @@
+import { SemanticQuery, QueryResult, SecurityContext, DatabaseExecutor, CubeMetadata, Cube, QueryAnalysis, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, RLSSetupFn } from './types';
+import { PlanOptimiser } from './logical-plan';
+export { validateQueryAgainstCubes } from './query-validator';
+export declare class SemanticLayerCompiler {
+    private cubes;
+    private metadataCache?;
+    private cacheConfig?;
+    private rlsSetup?;
+    private planOptimiser?;
+    private db?;
+    private schema?;
+    private engineType?;
+    constructor(options?: {
+        drizzle?: DatabaseExecutor['db'];
+        schema?: any;
+        databaseExecutor?: DatabaseExecutor;
+        engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+        /** Cache configuration for query result caching */
+        cache?: CacheConfig;
+        /**
+         * Row-Level Security setup function.
+         * When provided, every query execution opens a transaction, calls this function
+         * to configure RLS (e.g., set JWT claims and switch roles), then runs the query.
+         * Dry-run/SQL generation is NOT wrapped in a transaction.
+         */
+        rlsSetup?: RLSSetupFn;
+        /**
+         * Optional logical-plan optimiser injected into every QueryExecutor.
+         * Defaults to a no-op IdentityOptimiser when omitted.
+         */
+        planOptimiser?: PlanOptimiser;
+    });
+    /**
+     * Set or update the database connection
+     */
+    setDatabaseExecutor(executor: DatabaseExecutor): void;
+    /**
+     * Get the database engine type for SQL formatting
+     */
+    getEngineType(): 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake' | undefined;
+    /**
+     * Set Drizzle instance and schema directly
+     */
+    setDrizzle(db: DatabaseExecutor['db'], schema?: any, engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake'): void;
+    /**
+     * Check if database executor is configured
+     */
+    hasExecutor(): boolean;
+    /**
+     * Create a fresh DatabaseExecutor from stored ingredients, or throw.
+     */
+    private createDbExecutor;
+    /**
+     * Create a query executor with optional cache integration.
+     * Each call creates a fresh DatabaseExecutor so concurrent requests
+     * never share mutable state.
+     */
+    private createQueryExecutor;
+    /**
+     * Format SQL result using current engine dialect.
+     */
+    private formatSqlResult;
+    /**
+     * Register a simplified cube with dynamic query building
+     * Validates calculated measures during registration
+     */
+    registerCube(cube: Cube): void;
+    /**
+     * Validate that all string-based cube references in joins resolve to registered cubes.
+     * Call after all cubes are registered for strict startup validation.
+     * Throws an error listing all unresolved references.
+     */
+    validateCubeReferences(): void;
+    /**
+     * Validate calculated measures in a cube
+     * Checks template syntax, dependency existence, and circular dependencies
+     */
+    private validateCalculatedMeasures;
+    /**
+     * Get a cube by name
+     */
+    getCube(name: string): Cube | undefined;
+    /**
+     * Get all registered cubes
+     */
+    getAllCubes(): Cube[];
+    /**
+     * Get all cubes as a Map for multi-cube queries
+     */
+    getAllCubesMap(): Map<string, Cube>;
+    /**
+     * Unified query execution method that handles both single and multi-cube queries
+     * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
+     */
+    execute(query: SemanticQuery, securityContext: SecurityContext, options?: ExecutionOptions): Promise<QueryResult>;
+    /**
+     * Execute a multi-cube query
+     * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
+     */
+    executeMultiCubeQuery(query: SemanticQuery, securityContext: SecurityContext, options?: ExecutionOptions): Promise<QueryResult>;
+    /**
+     * Execute a single cube query
+     */
+    executeQuery(cubeName: string, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
+    /**
+     * Get metadata for all cubes (for API responses)
+     * Uses caching to improve performance for repeated requests
+     * Cache is invalidated when cubes are modified (registerCube, removeCube, clearCubes)
+     */
+    getMetadata(): CubeMetadata[];
+    /**
+     * Extract column name from Drizzle column reference
+     * Handles different column types and extracts the actual column name
+     */
+    private getColumnName;
+    /**
+     * Generate cube metadata for API responses from cubes
+     * Includes drill-down support: drillMembers on measures, granularities on time dimensions, hierarchies
+     */
+    private generateCubeMetadata;
+    /**
+     * Get SQL for a query without executing it (debugging)
+     */
+    generateSQL(cubeName: string, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Get SQL for a multi-cube query without executing it (debugging)
+     */
+    generateMultiCubeSQL(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Canonical dry-run SQL generation entrypoint for all query modes.
+     */
+    dryRun(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Get SQL for a funnel query without executing it (debugging)
+     * Returns the actual CTE-based SQL that would be executed for funnel queries
+     */
+    dryRunFunnel(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Get SQL for a flow query without executing it (debugging)
+     * Returns the actual CTE-based SQL that would be executed for flow queries
+     */
+    dryRunFlow(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a retention query without execution (dry-run)
+     * Returns the CTE-based SQL that would be executed for retention analysis
+     */
+    dryRunRetention(query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Execute EXPLAIN on a query to get the execution plan
+     * Uses the same secure path as execute/dryRun to generate SQL,
+     * then runs database EXPLAIN on it.
+     */
+    explainQuery(query: SemanticQuery, securityContext: SecurityContext, options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Check if a cube exists
+     */
+    hasCube(name: string): boolean;
+    /**
+     * Unregister a cube by name.
+     * Returns true if the cube existed and was removed, false if not found.
+     */
+    unregisterCube(name: string): boolean;
+    /**
+     * Remove a cube
+     */
+    removeCube(name: string): boolean;
+    /**
+     * Clear all cubes
+     */
+    clearCubes(): void;
+    /**
+     * Invalidate the metadata cache
+     * Called whenever cubes are modified
+     */
+    private invalidateMetadataCache;
+    /**
+     * Get cube names
+     */
+    getCubeNames(): string[];
+    /**
+     * Validate a query against registered cubes
+     * Ensures all referenced cubes and fields exist
+     */
+    validateQuery(query: SemanticQuery): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Analyze query planning decisions for debugging and transparency
+     * Returns detailed metadata about how the query would be planned
+     * Used by the playground UI to help users understand query structure
+     */
+    analyzeQuery(query: SemanticQuery, securityContext: SecurityContext): QueryAnalysis;
+}

package/dist/server/server/cube-utils.d.ts

@@ -0,0 +1,158 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { Cube, CubeJoin, Dimension, QueryContext, MultiCubeQueryContext, SqlExpression } from './types';
+/**
+ * Resolve cube reference (handles direct, lazy, and string name references)
+ *
+ * String references are resolved from the optional `cubes` registry map.
+ * Returns `null` when a string ref cannot be resolved (logs a warning).
+ */
+export declare function resolveCubeReference(ref: Cube | (() => Cube) | string, cubes?: Map<string, Cube>): Cube | null;
+/**
+ * Reverse a semantic relationship type for bidirectional join path resolution.
+ * When traversing a join edge in reverse (target→source instead of source→target),
+ * the relationship semantics flip: belongsTo↔hasMany, hasOne stays hasOne,
+ * belongsToMany stays belongsToMany (symmetric).
+ */
+export declare function reverseRelationship(relationship: string): string;
+/**
+ * Derive SQL join type from semantic relationship
+ */
+export declare function getJoinType(relationship: string, override?: string): string;
+/**
+ * DRIZZLE ORM LIMITATION: SQL Object Mutation Protection
+ *
+ * Create an isolated copy of a SQL expression to prevent mutation issues
+ * when the expression will be reused across multiple query contexts.
+ *
+ * ## Background
+ *
+ * Drizzle SQL objects are mutable - their internal `queryChunks` array can be
+ * modified during query construction. When column objects (like employees.id)
+ * are reused across multiple parts of a query (SELECT, WHERE, GROUP BY), this
+ * mutation can cause:
+ * - Duplicate SQL fragments in generated queries
+ * - Incorrect parameter binding order
+ * - Query execution failures
+ *
+ * ## Evidence from Drizzle Source Code
+ *
+ * Investigation of Drizzle ORM source code (/tmp/drizzle-orm/drizzle-orm/src/sql/sql.ts)
+ * revealed:
+ *
+ * 1. SQL objects have a mutable `queryChunks` array (line 133)
+ * 2. The `append()` method directly mutates this array
+ * 3. No public `clone()` method exists (only internal SQL.Aliased.clone())
+ * 4. The `sql` template function creates NEW arrays but chunks are pushed by reference
+ *
+ * ## The Double Wrapping Pattern
+ *
+ * `sql`${sql`${expr}`}`` creates two layers of SQL isolation:
+ *
+ * **Single wrap** (`sql`${expr}``):
+ * - Creates a new SQL object
+ * - But queryChunks contains REFERENCES to original objects
+ * - Original objects can still be mutated
+ *
+ * **Double wrap** (`sql`${sql`${expr}`}``):
+ * - Inner wrap: Creates fresh SQL from original expression
+ * - Outer wrap: Creates complete isolation from shared state
+ * - When Drizzle processes nested SQL, it recursively builds from inner chunks
+ * - This prevents corruption when SQL expressions are reused
+ *
+ * ## When to Use
+ *
+ * - **resolveSqlExpression()**: ALWAYS (expressions may be reused)
+ * - **buildMeasureExpression()**: ALWAYS (after resolveSqlExpression)
+ * - **New aggregations**: Single wrap OK (creating fresh SQL for first time)
+ *
+ * ## Alternatives Investigated
+ *
+ * - ❌ Use Drizzle's clone() - Doesn't exist publicly
+ * - ❌ Store SQL factory functions - Still returns same column objects
+ * - ❌ Create fresh column references - Impossible, columns are singletons
+ * - ❌ Avoid SQL reuse - Unavoidable (same dimension in SELECT, WHERE, GROUP BY)
+ *
+ * ## Performance Impact
+ *
+ * - Memory: ~200 bytes per wrap (negligible)
+ * - CPU: Two function calls during query building (microseconds)
+ * - No runtime query performance impact
+ *
+ * @param expr - SQL expression that may be reused across query contexts
+ * @returns Isolated SQL expression safe for reuse
+ */
+export declare function isolateSqlExpression(expr: AnyColumn | SQL): SQL;
+/**
+ * Sanitize a property key to prevent prototype pollution.
+ * Keys in this codebase come from validated cube field names (e.g., "Cube.measure")
+ * but CodeQL cannot trace that validation across module boundaries.
+ */
+export declare function safeKey(key: string): string;
+/**
+ * Helper to resolve SQL expressions with mutation protection
+ *
+ * Evaluates function-based SQL expressions and applies isolation to prevent
+ * Drizzle's internal mutation from corrupting reused SQL objects.
+ *
+ * @param expr - Column, SQL object, or function that returns one
+ * @param ctx - Query context for function evaluation
+ * @returns Isolated SQL expression safe for reuse
+ */
+export declare function resolveSqlExpression(expr: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL), ctx: QueryContext): AnyColumn | SQL;
+/**
+ * Resolve a dimension's SQL expression for use in a filter condition.
+ *
+ * For non-time dimensions, use the raw column so Drizzle preserves column type
+ * metadata for proper parameter binding (e.g. UUID columns need type info) — this
+ * deliberately bypasses isolateSqlExpression. For time dimensions, keep isolated
+ * SQL because normalizeDate() returns strings.
+ *
+ * Centralises the filter-field resolution that was previously copy-pasted across
+ * the filter builder, executor, and funnel/flow/retention builders.
+ */
+export declare function resolveFilterFieldExpr(dimension: Dimension, ctx: QueryContext): AnyColumn | SQL;
+/**
+ * Helper to create multi-cube query context
+ */
+export declare function createMultiCubeContext(baseContext: QueryContext, cubes: Map<string, Cube>, currentCube: Cube): MultiCubeQueryContext;
+/**
+ * Type guard to check if value is a function-based SQL expression
+ */
+export declare function isFunctionSqlExpression(expr: SqlExpression): expr is (ctx: QueryContext) => AnyColumn | SQL;
+/**
+ * Helper function to create cubes
+ */
+export declare function defineCube(name: string, definition: Omit<Cube, 'name'>): Cube;
+/**
+ * Build the Drizzle join condition for a regular (belongsTo/hasOne/hasMany)
+ * join from its symbolic CubeJoin definition. Columns are isolated to prevent
+ * Drizzle's mutable queryChunks from corrupting reused expressions. The
+ * condition is symmetric, so it is correct for reversed joins as-is.
+ *
+ * This is the materialization counterpart used by DrizzlePlanBuilder; it
+ * mirrors JoinPathResolver.buildJoinCondition(joinDef, null, null).
+ */
+export declare function buildRegularJoinCondition(joinDef: CubeJoin): SQL;
+/**
+ * Expanded join information for belongsToMany relationships
+ */
+export interface ExpandedBelongsToManyJoin {
+    /** Junction table joins */
+    junctionJoins: Array<{
+        joinType: 'inner' | 'left' | 'right' | 'full';
+        table: any;
+        condition: SQL;
+    }>;
+}
+/**
+ * Expand a belongsToMany join into junction table joins
+ * This converts a many-to-many relationship into two separate joins:
+ * 1. Source cube -> Junction table
+ * 2. Junction table -> Target cube
+ *
+ * Junction-table security is intentionally NOT materialized here: it must be
+ * applied (in the WHERE clause) at physical-build time from the stored
+ * `through.securitySql` function with the request's security context, so the
+ * join conditions here are a pure function of the join definition.
+ */
+export declare function expandBelongsToManyJoin(joinDef: CubeJoin): ExpandedBelongsToManyJoin;

package/dist/server/server/database-utils.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseAdapter } from './adapters/base-adapter';
+/**
+ * Create a database adapter for the specified engine type
+ * @param engineType - The database engine type
+ * @returns Database adapter instance
+ */
+export declare function createDatabaseAdapter(engineType: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake'): DatabaseAdapter;
+/**
+ * Get available database adapters
+ * @returns Array of supported engine types
+ */
+export declare function getSupportedEngines(): ('postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake')[];
+/**
+ * Check if an engine type is supported
+ * @param engineType - Engine type to check
+ * @returns True if supported, false otherwise
+ */
+export declare function isEngineSupported(engineType: string): engineType is 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';

package/dist/server/server/execution/annotation-builder.d.ts

@@ -0,0 +1,12 @@
+import { PhysicalQueryPlan, SemanticQuery, MeasureAnnotation, DimensionAnnotation, TimeDimensionAnnotation } from '../types';
+/**
+ * Generate annotations for UI metadata - unified approach.
+ * Collects measure/dimension/timeDimension titles from every cube in the plan
+ * (primary + joins + multi-fact merge groups).
+ */
+export declare function buildAnnotations(queryPlan: PhysicalQueryPlan, query: SemanticQuery): {
+    measures: Record<string, MeasureAnnotation>;
+    dimensions: Record<string, DimensionAnnotation>;
+    segments: Record<string, never>;
+    timeDimensions: Record<string, TimeDimensionAnnotation>;
+};

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

@@ -0,0 +1,19 @@
+import { Cube, SemanticQuery, QueryContext } from '../types';
+import { FilterCacheManager } from '../filter-cache';
+import { DrizzleSqlBuilder } from '../physical-plan/drizzle-sql-builder';
+export declare class FilterCachePreloader {
+    private readonly queryBuilder;
+    constructor(queryBuilder: DrizzleSqlBuilder);
+    /**
+     * 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
+     */
+    preload(query: SemanticQuery, filterCache: FilterCacheManager, cubes: Map<string, Cube>, context: QueryContext): void;
+    /** Resolve the dimension a filter/time-dimension member refers to, or null. */
+    private resolveMemberDimension;
+    /** Pre-build and cache the SQL for a single simple (non-logical) filter. */
+    private preloadRegularFilter;
+    /** Pre-build and cache the date-range SQL for a single time dimension. */
+    private preloadTimeDimensionFilter;
+}

package/dist/server/server/execution/mode-router.d.ts

@@ -0,0 +1,25 @@
+import { Cube, SemanticQuery } from '../types';
+import { ComparisonQueryBuilder } from '../builders/comparison-query-builder';
+import { FunnelQueryBuilder } from '../builders/funnel-query-builder';
+import { FlowQueryBuilder } from '../builders/flow-query-builder';
+import { RetentionQueryBuilder } from '../builders/retention-query-builder';
+export type QueryExecutionMode = 'regular' | 'comparison' | 'funnel' | 'flow' | 'retention';
+export interface ModeRouterBuilders {
+    comparison: ComparisonQueryBuilder;
+    funnel: FunnelQueryBuilder;
+    flow: FlowQueryBuilder;
+    retention: RetentionQueryBuilder;
+}
+export declare class ModeRouter {
+    private readonly builders;
+    constructor(builders: ModeRouterBuilders);
+    /**
+     * Resolve the single active execution mode for a query.
+     * Throws if more than one analysis mode is present.
+     */
+    resolveMode(query: SemanticQuery): QueryExecutionMode;
+    /**
+     * Validate a query for its resolved mode. Throws a translated error on failure.
+     */
+    validateForMode(mode: QueryExecutionMode, cubes: Map<string, Cube>, query: SemanticQuery): void;
+}

package/dist/server/server/execution/query-result-cache.d.ts

@@ -0,0 +1,21 @@
+import { SecurityContext, SemanticQuery, QueryResult, CacheConfig } from '../types';
+export declare class QueryResultCache {
+    private readonly cacheConfig?;
+    constructor(cacheConfig?: CacheConfig | undefined);
+    /**
+     * Returns the cache key when caching is enabled and a provider is configured,
+     * otherwise undefined (which disables lookup and store).
+     */
+    generateKey(query: SemanticQuery, securityContext: SecurityContext): string | undefined;
+    /**
+     * Look up a cached result. Returns the cached value (with cache metadata
+     * attached) on a hit, or undefined on miss / bypass / no-cache. Emits
+     * hit/miss events; lookup errors are non-fatal.
+     */
+    lookup(cacheKey: string | undefined, skipCache: boolean): Promise<QueryResult | undefined>;
+    /**
+     * Store a fresh result under the given key. No-ops when caching is disabled
+     * or the key is undefined. Store errors are non-fatal.
+     */
+    store(cacheKey: string | undefined, result: QueryResult): Promise<void>;
+}

package/dist/server/server/execution/result-post-processor.d.ts

@@ -0,0 +1,10 @@
+import { SemanticQuery } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+/**
+ * Normalise time-dimension values in result rows and apply gap filling.
+ *
+ * @param data Raw rows from the database executor
+ * @param query The semantic query (for timeDimensions + measures)
+ * @param databaseAdapter Adapter used to convert engine-specific date results
+ */
+export declare function postProcessResultRows(data: unknown, query: SemanticQuery, databaseAdapter: DatabaseAdapter): Record<string, unknown>[];