drizzle-cube 0.2.19 → 0.2.22

package/dist/server/index.d.ts

@@ -760,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
  */
@@ -1048,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
@@ -1057,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.
@@ -1281,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;
     };
 }
 
@@ -1543,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 {