drizzle-cube 0.3.13 → 0.3.15

package/dist/server/index.d.ts

@@ -467,6 +467,22 @@ declare interface DatabaseAdapter {
      * @returns SQL for conditional aggregation
      */
     buildConditionalAggregation(aggFn: 'count' | 'avg' | 'min' | 'max' | 'sum', expr: SQL | null, condition: SQL): SQL;
+    /**
+     * Build date difference expression in specified periods
+     * Used for retention analysis to calculate period numbers
+     * @param startDate - Start date expression
+     * @param endDate - End date expression
+     * @param unit - Unit for difference ('day' | 'week' | 'month')
+     * @returns SQL expression for date difference in periods
+     */
+    buildDateDiffPeriods(startDate: SQL, endDate: SQL, unit: 'day' | 'week' | 'month'): SQL;
+    /**
+     * Build a subquery that generates a series of period numbers (0 to maxPeriod)
+     * Used for retention analysis to cross-join with user data
+     * @param maxPeriod - Maximum period number to generate
+     * @returns SQL expression for period series subquery with alias 'p' containing 'period_number' column
+     */
+    buildPeriodSeriesSubquery(maxPeriod: number): SQL;
     /**
      * Build time dimension expression with granularity truncation
      * @param granularity - Time granularity (day, month, year, etc.)
@@ -875,6 +891,16 @@ export declare interface ExplainSummary {
     usedIndexes: string[];
 }
 
+/**
+ * Extract cube name from a time dimension specification
+ */
+export declare function extractCubeFromTimeDimension(timeDimension: string | RetentionTimeDimensionMapping): string;
+
+/**
+ * Extract dimension name from a time dimension specification
+ */
+export declare function extractDimensionFromTimeDimension(timeDimension: string | RetentionTimeDimensionMapping): string;
+
 /**
  * Type-level utility to extract the schema type from a cube reference
  * Since we removed generics, this now returns 'any'
@@ -1231,6 +1257,23 @@ export declare function isMultiCubeStep(step: FunnelStep): step is FunnelStepMul
  */
 export declare function isMultiCubeTimeDimension(timeDimension: string | FunnelTimeDimensionMapping[]): timeDimension is FunnelTimeDimensionMapping[];
 
+/**
+ * Type guard for multi-cube binding key
+ */
+export declare function isRetentionMultiCubeBindingKey(bindingKey: string | RetentionBindingKeyMapping[]): bindingKey is RetentionBindingKeyMapping[];
+
+/**
+ * Type guard for multi-cube time dimension (object form)
+ */
+export declare function isRetentionMultiCubeTimeDimension(timeDimension: string | RetentionTimeDimensionMapping): timeDimension is RetentionTimeDimensionMapping;
+
+/**
+ * Type guard for retention query
+ */
+export declare function isRetentionQuery(query: unknown): query is {
+    retention: RetentionQueryConfig;
+};
+
 /**
  * Join key information for CTE joins
  * Describes how a CTE should be joined to the main query
@@ -1947,6 +1990,7 @@ export declare class QueryExecutor {
     private comparisonQueryBuilder;
     private funnelQueryBuilder;
     private flowQueryBuilder;
+    private retentionQueryBuilder;
     private cacheConfig?;
     constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig);
     /**
@@ -1985,6 +2029,15 @@ export declare class QueryExecutor {
      * 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
@@ -2036,6 +2089,14 @@ export declare class QueryExecutor {
         sql: string;
         params?: any[];
     }>;
+    /**
+     * Generate SQL for a retention query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
+     */
+    dryRunRetention(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
     /**
      * Execute EXPLAIN on a query to get the execution plan
      * Generates the SQL using the same secure path as execute/generateSQL,
@@ -2314,6 +2375,130 @@ declare type ResolvedMeasures = Map<string, () => SQL>;
  */
 export declare function resolveSqlExpression(expr: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL), ctx: QueryContext): AnyColumn | SQL;
 
+/**
+ * Binding key mapping for multi-cube retention
+ * Maps the user/entity identifier across cohort and activity cubes
+ */
+export declare interface RetentionBindingKeyMapping {
+    cube: string;
+    dimension: string;
+}
+
+/**
+ * Retention capabilities per database engine
+ */
+export declare interface RetentionCapabilities {
+    /** Whether database supports DATE_TRUNC natively */
+    supportsDateTrunc: boolean;
+    /** Whether database supports DATE_DIFF with unit specification */
+    supportsDateDiff: boolean;
+    /** Whether database supports generate_series for period generation */
+    supportsGenerateSeries: boolean;
+}
+
+/**
+ * Date range for cohort analysis
+ */
+export declare interface RetentionDateRange {
+    /** Start date (inclusive), ISO 8601 format (YYYY-MM-DD) */
+    start: string;
+    /** End date (inclusive), ISO 8601 format (YYYY-MM-DD) */
+    end: string;
+}
+
+/**
+ * Retention query configuration (Simplified Mixpanel-style format)
+ *
+ * Key simplifications from previous version:
+ * - Single timeDimension for both cohort entry and activity
+ * - Single granularity for viewing periods (no separate cohort/period granularity)
+ * - Single cohort (date range defines the cohort) with optional breakdown
+ */
+export declare interface RetentionQueryConfig {
+    /**
+     * Single timestamp dimension for the analysis.
+     * String for single-cube (e.g., 'Events.timestamp'),
+     * Object for multi-cube with explicit cube reference.
+     */
+    timeDimension: string | RetentionTimeDimensionMapping;
+    /**
+     * Binding key - dimension that links users across events.
+     * This is typically a user ID or other entity identifier.
+     * String for single-cube (e.g., 'Events.userId'),
+     * Array for multi-cube with different column names per cube.
+     */
+    bindingKey: string | RetentionBindingKeyMapping[];
+    /**
+     * Date range for cohort analysis (REQUIRED).
+     * Users who first performed the cohort action within this range are included.
+     */
+    dateRange: RetentionDateRange;
+    /**
+     * Granularity for viewing retention periods.
+     * Determines how period_number is calculated (day/week/month).
+     */
+    granularity: 'day' | 'week' | 'month';
+    /**
+     * Number of periods to calculate (e.g., 12 for 12 weeks).
+     * Period 0 is always the cohort entry period.
+     */
+    periods: number;
+    /**
+     * Retention type:
+     * - 'classic': User returned exactly in period N (bounded)
+     * - 'rolling': User returned in period N or any later period (unbounded)
+     */
+    retentionType: 'classic' | 'rolling';
+    /**
+     * Optional filters on cohort entry events.
+     * Applied when identifying which users enter the cohort.
+     */
+    cohortFilters?: Filter | Filter[];
+    /**
+     * Optional filters on return activity events.
+     * Applied when checking for user activity in each period.
+     */
+    activityFilters?: Filter | Filter[];
+    /**
+     * Optional breakdown dimensions for segmenting the cohort.
+     * When provided, retention is calculated per unique combination of breakdown values.
+     * e.g., ["Events.country", "Events.plan"] to see retention by country and plan.
+     */
+    breakdownDimensions?: string[];
+}
+
+/**
+ * Single retention data point in the flat result format.
+ * Results are returned as a flat array; client transforms to matrix if needed.
+ *
+ * Simplified format: no cohortPeriod since we use a single cohort model.
+ * When breakdownDimensions are specified, results include breakdownValues.
+ */
+export declare interface RetentionResultRow {
+    /** Period number (0 = cohort entry, 1 = first retention period, etc.) */
+    period: number;
+    /** Number of users in the cohort (or segment when breakdown is used) */
+    cohortSize: number;
+    /** Number of users retained in this period */
+    retainedUsers: number;
+    /** Retention rate as decimal (0-1), e.g., 0.45 for 45% */
+    retentionRate: number;
+    /**
+     * Breakdown values when breakdownDimensions are specified.
+     * Keyed by dimension name (e.g., { "Events.country": "US", "Events.plan": "pro" })
+     */
+    breakdownValues?: Record<string, string | null>;
+}
+
+/**
+ * Time dimension mapping for multi-cube retention
+ * Maps the timestamp field across different cubes
+ */
+export declare interface RetentionTimeDimensionMapping {
+    cube: string;
+    dimension: string;
+}
+
 /**
  * Security context passed to cube SQL functions
  * Contains user/tenant-specific data for filtering
@@ -2433,6 +2618,14 @@ export declare class SemanticLayerCompiler {
         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,
@@ -2557,6 +2750,30 @@ export declare interface SemanticQuery {
      * ```
      */
     flow?: FlowQueryConfig;
+    /**
+     * Retention analysis configuration for cohort-based retention tracking.
+     * When specified, the query executes as a retention analysis instead of
+     * standard measures/dimensions aggregation.
+     *
+     * Retention analysis tracks what percentage of users from each cohort
+     * return in subsequent time periods.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   retention: {
+     *     timeDimension: 'Events.timestamp',
+     *     bindingKey: 'Events.userId',
+     *     dateRange: { start: '2024-01-01', end: '2024-12-31' },
+     *     granularity: 'week',
+     *     periods: 12,
+     *     retentionType: 'classic',
+     *     breakdownDimensions: ['Events.country', 'Events.plan']
+     *   }
+     * }
+     * ```
+     */
+    retention?: RetentionQueryConfig;
 }
 
 export { SQL }