drizzle-cube 0.2.14 → 0.2.16

package/dist/server/index.d.ts

@@ -282,6 +282,62 @@ declare interface DatabaseAdapter {
      * @returns Preprocessed template string
      */
     preprocessCalculatedTemplate(calculatedSql: string): string;
+    /**
+     * Get database capabilities for feature detection
+     * Used for graceful degradation when functions aren't supported
+     */
+    getCapabilities(): DatabaseCapabilities;
+    /**
+     * Build STDDEV aggregation expression
+     * @param fieldExpr - The field expression to calculate stddev for
+     * @param useSample - Use sample stddev (STDDEV_SAMP) vs population (STDDEV_POP). Default: false
+     * @returns SQL expression or null if unsupported
+     */
+    buildStddev(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL | null;
+    /**
+     * Build VARIANCE aggregation expression
+     * @param fieldExpr - The field expression to calculate variance for
+     * @param useSample - Use sample variance (VAR_SAMP) vs population (VAR_POP). Default: false
+     * @returns SQL expression or null if unsupported
+     */
+    buildVariance(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL | null;
+    /**
+     * Build PERCENTILE aggregation expression
+     * @param fieldExpr - The field expression to calculate percentile for
+     * @param percentile - Percentile value (0-100)
+     * @returns SQL expression or null if unsupported
+     */
+    buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL | null;
+    /**
+     * Build a window function expression
+     * @param type - Window function type (lag, lead, rank, etc.)
+     * @param fieldExpr - The field expression (null for rank functions that don't need a field)
+     * @param partitionBy - PARTITION BY columns
+     * @param orderBy - ORDER BY columns with direction
+     * @param config - Additional configuration (offset, default, frame, etc.)
+     * @returns SQL expression or null if unsupported
+     */
+    buildWindowFunction(type: WindowFunctionType, fieldExpr: AnyColumn | SQL | null, partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
+        field: AnyColumn | SQL;
+        direction: 'asc' | 'desc';
+    }>, config?: WindowFunctionConfig): SQL | null;
+}
+
+/**
+ * Database capabilities for feature detection
+ * Used for graceful degradation when functions aren't supported
+ */
+declare interface DatabaseCapabilities {
+    /** Whether the database supports STDDEV_POP/STDDEV_SAMP */
+    supportsStddev: boolean;
+    /** Whether the database supports VAR_POP/VAR_SAMP */
+    supportsVariance: boolean;
+    /** Whether the database supports PERCENTILE_CONT or similar */
+    supportsPercentile: boolean;
+    /** Whether the database supports window functions (LAG, LEAD, RANK, etc.) */
+    supportsWindowFunctions: boolean;
+    /** Whether the database supports frame clauses (ROWS BETWEEN, RANGE BETWEEN) */
+    supportsFrameClause: boolean;
 }
 
 /**
@@ -388,6 +444,65 @@ export declare type ExtractSchemaFromCubeRef = any;
  */
 export declare type Filter = FilterCondition | LogicalFilter;
 
+/**
+ * Manages filter SQL caching for a single query execution
+ *
+ * Design principles:
+ * - Immutable SQL: Once cached, SQL objects are never modified
+ * - Cache lifetime: Created at query start, discarded after query execution
+ * - Key by content: Filters with same member/operator/values share SQL
+ * - Thread-safe: No shared mutable state between queries
+ */
+declare class FilterCacheManager {
+    private cache;
+    private stats;
+    /**
+     * Get cached SQL or build and cache it
+     *
+     * @param key - The cache key (use getFilterKey or getTimeDimensionFilterKey)
+     * @param builder - Function to build the SQL if not cached
+     * @returns The cached or freshly built SQL, or null if builder returns null
+     */
+    getOrBuild(key: string, builder: () => SQL | null): SQL | null;
+    /**
+     * Check if a key exists in the cache without affecting stats
+     */
+    has(key: string): boolean;
+    /**
+     * Get cached SQL without building (returns undefined if not cached)
+     */
+    get(key: string): SQL | undefined;
+    /**
+     * Pre-populate cache with multiple filters
+     * Useful for batch initialization at query start
+     */
+    preload(entries: Array<{
+        key: string;
+        sql: SQL;
+    }>): void;
+    /**
+     * Store a single entry in the cache
+     */
+    set(key: string, sql: SQL): void;
+    /**
+     * Get cache statistics for debugging
+     */
+    getStats(): FilterCacheStats;
+    /**
+     * Clear the cache (normally not needed as cache is per-query)
+     */
+    clear(): void;
+}
+
+/**
+ * Cache statistics for debugging and monitoring
+ */
+declare interface FilterCacheStats {
+    hits: number;
+    misses: number;
+    cacheSize: number;
+}
+
 export declare interface FilterCondition {
     member: string;
     operator: FilterOperator;
@@ -509,6 +624,41 @@ declare interface Measure {
     dependencies?: string[];
     /** Additional metadata */
     meta?: Record<string, any>;
+    /**
+     * Statistical function configuration
+     * Used for percentile, stddev, variance measure types
+     */
+    statisticalConfig?: {
+        /** Percentile value (0-100) for percentile measures. Default: 50 for median */
+        percentile?: number;
+        /** Use sample vs population calculation for stddev/variance. Default: false (population) */
+        useSample?: boolean;
+    };
+    /**
+     * Window function configuration
+     * Used for lag, lead, rank, movingAvg, and other window function measure types
+     */
+    windowConfig?: {
+        /** Dimension references to partition by (e.g., ['employeeId']) */
+        partitionBy?: string[];
+        /** Columns to order by with direction */
+        orderBy?: Array<{
+            field: string;
+            direction: 'asc' | 'desc';
+        }>;
+        /** Number of rows to offset for lag/lead. Default: 1 */
+        offset?: number;
+        /** Default value when offset is out of bounds for lag/lead */
+        defaultValue?: any;
+        /** Number of buckets for ntile. Default: 4 */
+        nTile?: number;
+        /** Window frame specification for moving aggregates */
+        frame?: {
+            type: 'rows' | 'range';
+            start: number | 'unbounded';
+            end: number | 'current' | 'unbounded';
+        };
+    };
 }
 export { Measure }
 export { Measure as SemanticMeasure }
@@ -540,7 +690,7 @@ export declare interface MeasureMetadata {
 /**
  * Type enums and constants
  */
-export declare type MeasureType = 'count' | 'countDistinct' | 'countDistinctApprox' | 'sum' | 'avg' | 'min' | 'max' | 'runningTotal' | 'number' | 'calculated';
+export declare type MeasureType = 'count' | 'countDistinct' | 'countDistinctApprox' | 'sum' | 'avg' | 'min' | 'max' | 'runningTotal' | 'number' | 'calculated' | 'stddev' | 'stddevSamp' | 'variance' | 'varianceSamp' | 'percentile' | 'median' | 'p95' | 'p99' | 'lag' | 'lead' | 'rank' | 'denseRank' | 'rowNumber' | 'ntile' | 'firstValue' | 'lastValue' | 'movingAvg' | 'movingSum';
 
 /**
  * Multi-cube query context for cross-cube operations
@@ -619,6 +769,8 @@ export declare interface PreAggregationCTEInfo {
     joinKeys: JoinKeyInfo[];
     /** List of measure names included in this CTE */
     measures: string[];
+    /** Propagating filters from related cubes (for cross-cube filter propagation) */
+    propagatingFilters?: PropagatingFilter[];
 }
 
 /**
@@ -658,6 +810,27 @@ export declare interface PrimaryCubeCandidate {
  */
 export declare type PrimaryCubeSelectionReason = 'most_dimensions' | 'most_connected' | 'alphabetical_fallback' | 'single_cube';
 
+/**
+ * Propagating filter information for cross-cube filter propagation
+ * When cube A has filters and cube B (with hasMany from A) needs a CTE,
+ * A's filters should propagate into B's CTE via a subquery
+ */
+export declare interface PropagatingFilter {
+    /** The source cube whose filters need to propagate */
+    sourceCube: Cube;
+    /** Filters from the source cube to apply */
+    filters: Filter[];
+    /** Join condition linking source cube PK to target cube FK */
+    joinCondition: {
+        /** Primary key column on source cube */
+        source: AnyColumn;
+        /** Foreign key column on target cube (CTE cube) */
+        target: AnyColumn;
+    };
+    /** Pre-built filter SQL for parameter deduplication (optional, built during query planning) */
+    preBuiltFilterSQL?: SQL;
+}
+
 /**
  * Any queryable relation that can be used in FROM/JOIN clauses
  * Supports tables, views, subqueries, and raw SQL expressions
@@ -738,8 +911,12 @@ export declare class QueryBuilder {
     /**
      * Build measure expression with aggregation and filters
      * Note: This should NOT be called for calculated measures
+     *
+     * @param measure - The measure definition
+     * @param context - Query context with security context and database info
+     * @param cube - Optional cube reference for resolving dimension references (window functions)
      */
-    buildMeasureExpression(measure: any, context: QueryContext): SQL;
+    buildMeasureExpression(measure: any, context: QueryContext, cube?: Cube): SQL;
     /**
      * Build time dimension expression with granularity using database adapter
      */
@@ -747,8 +924,9 @@ export declare class QueryBuilder {
     /**
      * 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?: QueryPlan): SQL[];
+    buildWhereConditions(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: QueryPlan, preBuiltFilters?: Map<string, SQL[]>): SQL[];
     /**
      * Build HAVING conditions from semantic query filters (measures only)
      * Works for both single and multi-cube queries
@@ -778,9 +956,20 @@ export declare class QueryBuilder {
      * Ensures dates are in the correct format for each database engine
      */
     private normalizeDate;
+    /**
+     * Check if a measure type is a window function
+     */
+    private isWindowFunctionType;
+    /**
+     * Check if a measure type is an aggregate function (requires GROUP BY)
+     */
+    private isAggregateFunctionType;
     /**
      * Build GROUP BY fields from dimensions and time dimensions
      * Works for both single and multi-cube queries
+     *
+     * NOTE: GROUP BY is only added when there are AGGREGATE measures.
+     * Window functions do not require GROUP BY and operate on individual rows.
      */
     buildGroupByFields(cubes: Map<string, Cube> | Cube, query: SemanticQuery, context: QueryContext, queryPlan?: any): (SQL | AnyColumn)[];
     /**
@@ -797,6 +986,21 @@ export declare class QueryBuilder {
      * 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
+     */
+    buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
+    /**
+     * Build SQL for a single filter condition (simple or logical)
+     * Used for cache preloading to build filters independently of query context
+     */
+    private buildSingleFilter;
 }
 
 /**
@@ -814,6 +1018,11 @@ declare interface QueryContext {
     query?: SemanticQuery;
     /** The compiled cube being queried */
     cube?: Cube;
+    /**
+     * Filter cache for parameter deduplication across CTEs
+     * Created at query start and used throughout query building
+     */
+    filterCache?: FilterCacheManager;
 }
 export { QueryContext }
 export { QueryContext as SemanticQueryContext }
@@ -840,6 +1049,14 @@ export declare class QueryExecutor {
      * Build join condition for CTE
      */
     private buildCTEJoinCondition;
+    /**
+     * Build a subquery filter for propagating filters from related cubes.
+     * This generates: cteCube.FK IN (SELECT sourceCube.PK FROM sourceCube WHERE filters...)
+     *
+     * Example: For Productivity CTE with Employees.createdAt filter:
+     * employee_id IN (SELECT id FROM employees WHERE organisation_id = $1 AND created_at >= $date)
+     */
+    private buildPropagatingFilterSubquery;
     /**
      * Build unified query that works for both single and multi-cube queries
      */
@@ -870,6 +1087,12 @@ export declare class QueryExecutor {
      * 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;
 }
 
 /**
@@ -925,6 +1148,7 @@ export declare class QueryPlanner {
     private extractMeasuresFromFilters;
     /**
      * Recursively extract measures from filters for a specific cube
+     * Only includes filter members that are actually measures (not dimensions)
      */
     private extractMeasuresFromFilter;
     /**
@@ -972,6 +1196,27 @@ export declare class QueryPlanner {
      * Find hasMany join definition from primary cube to target cube
      */
     private findHasManyJoinDef;
+    /**
+     * 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)
+     */
+    private findPropagatingFilters;
+    /**
+     * Extract cube names from filters into a Set (helper for findPropagatingFilters)
+     */
+    private extractFilterCubeNamesToSet;
+    /**
+     * Extract filters for a specific cube from the filter array
+     */
+    private extractFiltersForCube;
+    /**
+     * Extract time dimension date range filters as regular filters for a specific cube
+     */
+    private extractTimeDimensionFiltersForCube;
     /**
      * Analyze query planning decisions without building the full query
      * Returns detailed metadata about how the query plan would be constructed
@@ -988,6 +1233,7 @@ export declare class QueryPlanner {
     private analyzeJoinPath;
     /**
      * Analyze pre-aggregation requirements for hasMany relationships
+     * This mirrors the logic in planPreAggregationCTEs to ensure analysis matches execution
      */
     private analyzePreAggregations;
 }
@@ -1270,4 +1516,27 @@ export declare interface TimeDimensionAnnotation {
 
 export declare type TimeGranularity = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 
+/**
+ * Window function configuration
+ */
+declare interface WindowFunctionConfig {
+    /** Number of rows to offset for lag/lead */
+    offset?: number;
+    /** Default value when offset is out of bounds */
+    defaultValue?: any;
+    /** Number of buckets for ntile */
+    nTile?: number;
+    /** Frame specification for moving aggregates */
+    frame?: {
+        type: 'rows' | 'range';
+        start: number | 'unbounded';
+        end: number | 'current' | 'unbounded';
+    };
+}
+
+/**
+ * Window function types supported by the adapter
+ */
+declare type WindowFunctionType = 'lag' | 'lead' | 'rank' | 'denseRank' | 'rowNumber' | 'ntile' | 'firstValue' | 'lastValue' | 'movingAvg' | 'movingSum';
+
 export { }