drizzle-cube 0.2.18 → 0.2.22

package/dist/server/index.d.ts

@@ -647,8 +647,41 @@ declare interface Measure {
     /**
      * Window function configuration
      * Used for lag, lead, rank, movingAvg, and other window function measure types
+     *
+     * Post-aggregation window functions:
+     * When `measure` is specified, the window function operates on AGGREGATED data.
+     * The base measure is first aggregated (grouped by query dimensions), then the
+     * window function is applied to the aggregated results.
+     *
+     * Example: Month-over-month revenue change
+     * ```typescript
+     * revenueChange: {
+     *   type: 'lag',
+     *   windowConfig: {
+     *     measure: 'totalRevenue',  // Reference to aggregate measure
+     *     operation: 'difference',   // current - previous
+     *     orderBy: [{ field: 'date', direction: 'asc' }]
+     *   }
+     * }
+     * ```
      */
     windowConfig?: {
+        /**
+         * Reference to the measure this window function operates on.
+         * The referenced measure will be aggregated first, then the window function applied.
+         * Can be a simple name ('totalRevenue') or fully qualified ('Sales.totalRevenue').
+         */
+        measure?: string;
+        /**
+         * Operation to perform after getting the window result:
+         * - 'raw': Return the window function result directly (default for rank, rowNumber, ntile)
+         * - 'difference': Subtract window result from current value (current - window)
+         * - 'ratio': Divide current value by window result (current / window)
+         * - 'percentChange': Calculate percentage change ((current - window) / window * 100)
+         *
+         * Default: 'difference' for lag/lead, 'raw' for rank/rowNumber/ntile/firstValue/lastValue
+         */
+        operation?: 'raw' | 'difference' | 'ratio' | 'percentChange';
         /** Dimension references to partition by (e.g., ['employeeId']) */
         partitionBy?: string[];
         /** Columns to order by with direction */
@@ -727,6 +760,21 @@ export declare class MySQLExecutor extends BaseDatabaseExecutor {
     getEngineType(): 'mysql' | 'singlestore';
 }
 
+/**
+ * Period comparison metadata for compareDateRange queries
+ * Provides information about the periods being compared
+ */
+export declare interface PeriodComparisonMetadata {
+    /** The date ranges being compared */
+    ranges: [string, string][];
+    /** Human-readable labels for each period */
+    labels: string[];
+    /** The time dimension used for comparison */
+    timeDimension: string;
+    /** Granularity used for the comparison */
+    granularity?: TimeGranularity;
+}
+
 /**
  * Type helpers for specific database types
  */
@@ -755,13 +803,21 @@ export declare interface PreAggregationAnalysis {
     cteAlias: string;
     /** Why this cube needs a CTE */
     reason: string;
-    /** Measures included in CTE */
+    /** Measures included in CTE (aggregate measures + window base measures) */
     measures: string[];
     /** Join keys used */
     joinKeys: Array<{
         sourceColumn: string;
         targetColumn: string;
     }>;
+    /**
+     * Type of CTE:
+     * - 'aggregate': Standard CTE with GROUP BY (count, sum, avg, etc.)
+     *
+     * Note: Window function CTEs are no longer used. Post-aggregation window
+     * functions are applied in the outer query after data is aggregated.
+     */
+    cteType?: 'aggregate';
 }
 
 /**
@@ -777,10 +833,19 @@ export declare interface PreAggregationCTEInfo {
     cteAlias: string;
     /** Join keys to connect CTE back to main query */
     joinKeys: JoinKeyInfo[];
-    /** List of measure names included in this CTE */
+    /** List of measure names included in this CTE (aggregate measures + window base measures) */
     measures: string[];
     /** Propagating filters from related cubes (for cross-cube filter propagation) */
     propagatingFilters?: PropagatingFilter[];
+    /**
+     * Type of CTE:
+     * - 'aggregate': Standard CTE with GROUP BY for count/sum/avg measures
+     *
+     * Note: Window function CTEs are no longer used. Post-aggregation window
+     * functions (lag, lead, rank, etc.) operate on aggregated data and are
+     * applied in the outer query SELECT clause, not in separate CTEs.
+     */
+    cteType?: 'aggregate';
 }
 
 /**
@@ -998,6 +1063,7 @@ export declare class QueryExecutor {
     private queryPlanner;
     private cteBuilder;
     private databaseAdapter;
+    private comparisonQueryBuilder;
     constructor(dbExecutor: DatabaseExecutor);
     /**
      * Unified query execution method that handles both single and multi-cube queries
@@ -1007,6 +1073,16 @@ export declare class QueryExecutor {
      * Legacy interface for single cube queries
      */
     executeQuery(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
+    /**
+     * Execute a comparison query with multiple date periods
+     * Expands compareDateRange into multiple sub-queries and merges results
+     */
+    private executeComparisonQuery;
+    /**
+     * Standard query execution (non-comparison)
+     * This is the core execution logic extracted for use by comparison queries
+     */
+    private executeStandardQuery;
     /**
      * Validate that all cubes in the query plan have proper security filtering.
      * Emits a warning if a cube's sql() function doesn't return a WHERE clause.
@@ -1051,6 +1127,22 @@ export declare class QueryExecutor {
      * rather than appearing as separate parameters in different parts of the query
      */
     private preloadFilterCache;
+    /**
+     * Build post-aggregation window function expression
+     *
+     * Post-aggregation windows operate on already-aggregated data:
+     * 1. The base measure is aggregated (e.g., SUM(revenue))
+     * 2. The window function is applied (e.g., LAG(...) OVER ORDER BY date)
+     * 3. An optional operation is applied (e.g., current - previous)
+     *
+     * @param measure - The window function measure definition
+     * @param baseMeasureExpr - The aggregated base measure expression
+     * @param query - The semantic query (for dimension context)
+     * @param context - Query context
+     * @param cube - The cube containing this measure
+     * @returns SQL expression for the window function
+     */
+    private buildPostAggregationWindowExpression;
 }
 
 /**
@@ -1215,6 +1307,8 @@ export declare interface QueryResult {
         dimensions: Record<string, DimensionAnnotation>;
         segments: Record<string, unknown>;
         timeDimensions: Record<string, TimeDimensionAnnotation>;
+        /** Period comparison metadata (present when compareDateRange is used) */
+        periods?: PeriodComparisonMetadata;
     };
 }
 
@@ -1230,6 +1324,12 @@ export declare interface QuerySummary {
     cteCount: number;
     /** Has hasMany relationships requiring aggregation */
     hasPreAggregation: boolean;
+    /**
+     * Whether query contains post-aggregation window function measures.
+     * These window functions (lag, lead, rank, etc.) operate on aggregated
+     * data and are applied in the outer query after CTEs.
+     */
+    hasWindowFunctions?: boolean;
 }
 
 /**
@@ -1471,6 +1571,22 @@ export declare interface TimeDimension {
      * Default: true (enabled)
      */
     fillMissingDates?: boolean;
+    /**
+     * Array of date ranges for period-over-period comparison.
+     * When specified, queries are executed for each period and results are merged
+     * with period metadata (__periodIndex, __periodDayIndex) for alignment.
+     *
+     * Each range can be:
+     * - A relative string: 'this week', 'last month', 'last 30 days'
+     * - A tuple: ['2024-01-01', '2024-01-31']
+     *
+     * @example
+     * compareDateRange: [
+     *   'last 30 days',                    // Current period
+     *   ['2024-01-01', '2024-01-30']       // Prior period to compare
+     * ]
+     */
+    compareDateRange?: (string | [string, string])[];
 }
 
 export declare interface TimeDimensionAnnotation {