drizzle-cube 0.3.13 → 0.3.16

package/dist/server/index.d.ts

@@ -25,6 +25,42 @@ export declare interface AIExplainAnalysis {
     recommendations: ExplainRecommendation[];
 }
 
+/**
+ * Validate a query with helpful corrections
+ */
+export declare function aiValidateQuery(query: SemanticQuery, metadata: CubeMetadata[]): AIValidationResult;
+
+/**
+ * Validation error with optional correction
+ */
+export declare interface AIValidationError {
+    type: 'cube_not_found' | 'measure_not_found' | 'dimension_not_found' | 'invalid_filter' | 'invalid_time_dimension' | 'syntax_error';
+    message: string;
+    field?: string;
+    suggestion?: string;
+    correctedValue?: string;
+}
+
+/**
+ * Validation result with corrections
+ */
+export declare interface AIValidationResult {
+    isValid: boolean;
+    errors: AIValidationError[];
+    warnings: AIValidationWarning[];
+    correctedQuery?: SemanticQuery;
+}
+
+/**
+ * Validation warning (query will work but may have issues)
+ */
+export declare interface AIValidationWarning {
+    type: 'ambiguous_field' | 'performance' | 'best_practice';
+    message: string;
+    field?: string;
+    suggestion?: string;
+}
+
 /**
  * Abstract base class for database executors
  */
@@ -299,6 +335,12 @@ declare interface Cube {
     name: string;
     title?: string;
     description?: string;
+    /**
+     * Example questions that can be answered using this cube
+     * Used by AI agents to understand cube capabilities
+     * @example ['What was total revenue last month?', 'Show me sales by category']
+     */
+    exampleQuestions?: string[];
     /**
      * Base query setup - returns the foundation that can be extended
      * Should return FROM/JOIN/WHERE setup, NOT a complete SELECT
@@ -338,6 +380,41 @@ export declare type CubeDefinition = Omit<Cube, 'name'> & {
     name?: string;
 };
 
+/**
+ * Discovery result for a cube
+ */
+export declare interface CubeDiscoveryResult {
+    cube: string;
+    title: string;
+    description?: string;
+    relevanceScore: number;
+    matchedOn: ('name' | 'title' | 'description' | 'exampleQuestions' | 'measures' | 'dimensions')[];
+    suggestedMeasures: string[];
+    suggestedDimensions: string[];
+    capabilities: {
+        query: true;
+        funnel: boolean;
+        flow: boolean;
+        retention: boolean;
+    };
+    analysisConfig?: {
+        candidateBindingKeys: Array<{
+            dimension: string;
+            description?: string;
+        }>;
+        candidateTimeDimensions: Array<{
+            dimension: string;
+            description?: string;
+        }>;
+        candidateEventDimensions: Array<{
+            dimension: string;
+            description?: string;
+        }>;
+    };
+    hints?: string[];
+    querySchemas?: typeof QUERY_SCHEMAS;
+}
+
 /**
  * Type-safe cube join definition with lazy loading support
  */
@@ -398,6 +475,11 @@ export declare interface CubeMetadata {
     name: string;
     title: string;
     description?: string;
+    /**
+     * Example questions that can be answered using this cube
+     * Used by AI agents to understand cube capabilities
+     */
+    exampleQuestions?: string[];
     measures: MeasureMetadata[];
     dimensions: DimensionMetadata[];
     segments: any[];
@@ -467,6 +549,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.)
@@ -636,6 +734,12 @@ declare interface Dimension {
     name: string;
     title?: string;
     description?: string;
+    /**
+     * Alternative names for this dimension
+     * Used by AI agents for natural language matching
+     * @example ['date', 'day', 'timestamp'] for a createdAt dimension
+     */
+    synonyms?: string[];
     type: DimensionType;
     /** Direct column reference or SQL expression */
     sql: AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);
@@ -670,6 +774,11 @@ export declare interface DimensionMetadata {
     type: string;
     format?: DimensionFormat;
     description?: string;
+    /**
+     * Alternative names for this dimension
+     * Used by AI agents for natural language matching
+     */
+    synonyms?: string[];
 }
 
 export declare type DimensionType = 'string' | 'number' | 'time' | 'boolean';
@@ -683,6 +792,25 @@ export declare interface DimensionValues {
     [dimensionName: string]: string[];
 }
 
+/**
+ * Discover relevant cubes based on topic or intent
+ */
+export declare function discoverCubes(metadata: CubeMetadata[], options?: DiscoveryOptions): CubeDiscoveryResult[];
+
+/**
+ * Discovery request options
+ */
+export declare interface DiscoveryOptions {
+    /** Topic or intent to search for */
+    topic?: string;
+    /** Natural language intent */
+    intent?: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Minimum relevance score (0-1) */
+    minScore?: number;
+}
+
 /**
  * Information about downstream join keys for CTE building.
  * Used when a cube (e.g., Teams) needs to be joined through a CTE cube (e.g., EmployeeTeams)
@@ -875,6 +1003,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'
@@ -957,6 +1095,16 @@ export declare interface FilterCondition {
  */
 export declare type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'notStartsWith' | 'endsWith' | 'notEndsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'set' | 'notSet' | 'inDateRange' | 'beforeDate' | 'afterDate' | 'between' | 'notBetween' | 'in' | 'notIn' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex' | 'isEmpty' | 'isNotEmpty' | 'arrayContains' | 'arrayOverlaps' | 'arrayContained';
 
+/**
+ * Find the best matching field across all cubes
+ */
+export declare function findBestFieldMatch(metadata: CubeMetadata[], fieldName: string, fieldType?: 'measure' | 'dimension'): {
+    field: string;
+    cube: string;
+    score: number;
+    type: 'measure' | 'dimension';
+} | null;
+
 /**
  * Flow query configuration for server-side execution
  * This is the configuration extracted from SemanticQuery.flow
@@ -1231,6 +1379,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
@@ -1313,6 +1478,12 @@ declare interface Measure {
     name: string;
     title?: string;
     description?: string;
+    /**
+     * Alternative names for this measure
+     * Used by AI agents for natural language matching
+     * @example ['revenue', 'sales', 'income'] for a totalRevenue measure
+     */
+    synonyms?: string[];
     type: MeasureType;
     /**
      * Column to aggregate or SQL expression
@@ -1439,6 +1610,11 @@ export declare interface MeasureMetadata {
     type: MeasureType;
     format?: MeasureFormat;
     description?: string;
+    /**
+     * Alternative names for this measure
+     * Used by AI agents for natural language matching
+     */
+    synonyms?: string[];
 }
 
 /**
@@ -1768,6 +1944,64 @@ export declare interface PropagatingFilter {
     preBuiltFilterSQL?: SQL;
 }
 
+/**
+ * Generic query schemas for AI agents
+ * Teaches AI how to construct analysis queries
+ */
+declare const QUERY_SCHEMAS: {
+    readonly funnel: {
+        readonly description: "Track conversion through sequential steps. Entities (identified by bindingKey) move through ordered steps.";
+        readonly structure: {
+            readonly funnel: {
+                readonly bindingKey: "Cube.dimension - identifies entities moving through funnel";
+                readonly timeDimension: "Cube.dimension - time field for ordering events";
+                readonly steps: readonly [{
+                    readonly name: "string - human readable step name";
+                    readonly filter: {
+                        readonly member: "Cube.dimension";
+                        readonly operator: "equals | notEquals | contains | ...";
+                        readonly values: readonly ["array of filter values"];
+                    };
+                    readonly timeToConvert: "optional - max time window e.g. \"7 days\"";
+                }];
+                readonly dateRange: "[start, end] array OR string like \"last 7 days\", \"last 3 months\", \"this quarter\"";
+            };
+        };
+    };
+    readonly flow: {
+        readonly description: "Analyze paths users take before/after a specific event. Shows event sequences.";
+        readonly structure: {
+            readonly flow: {
+                readonly bindingKey: "Cube.dimension - identifies entities";
+                readonly timeDimension: "Cube.dimension - time field for ordering";
+                readonly eventDimension: "Cube.dimension - the event type field";
+                readonly startingStep: {
+                    readonly filter: {
+                        readonly member: "Cube.dimension";
+                        readonly operator: "equals";
+                        readonly values: readonly ["event value"];
+                    };
+                };
+                readonly stepsBefore: "number - how many steps to show before starting step";
+                readonly stepsAfter: "number - how many steps to show after starting step";
+                readonly dateRange: "[start, end] array OR string like \"last 7 days\", \"last 3 months\", \"this quarter\"";
+            };
+        };
+    };
+    readonly retention: {
+        readonly description: "Measure how many users return over time periods after initial activity.";
+        readonly structure: {
+            readonly retention: {
+                readonly bindingKey: "Cube.dimension - identifies entities";
+                readonly timeDimension: "Cube.dimension - time field for cohort assignment";
+                readonly granularity: "day | week | month - period size";
+                readonly periods: "number - how many periods to analyze";
+                readonly dateRange: "[start, end] array OR string like \"last 7 days\", \"last 3 months\", \"this quarter\"";
+            };
+        };
+    };
+};
+
 /**
  * Any queryable relation that can be used in FROM/JOIN clauses
  * Supports tables, views, subqueries, and raw SQL expressions
@@ -1947,6 +2181,7 @@ export declare class QueryExecutor {
     private comparisonQueryBuilder;
     private funnelQueryBuilder;
     private flowQueryBuilder;
+    private retentionQueryBuilder;
     private cacheConfig?;
     constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig);
     /**
@@ -1985,6 +2220,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 +2280,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,
@@ -2270,6 +2522,20 @@ export declare interface QueryResult {
     };
 }
 
+/**
+ * Suggested query result
+ */
+export declare interface QuerySuggestion {
+    query: Partial<SemanticQuery>;
+    confidence: number;
+    reasoning: string[];
+    warnings?: string[];
+    /** Detected analysis mode */
+    analysisMode: 'query' | 'funnel' | 'flow' | 'retention';
+    /** Next steps when mode != 'query' */
+    nextSteps?: string[];
+}
+
 /**
  * Query structure summary
  */
@@ -2314,6 +2580,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 +2823,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 +2955,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 }
@@ -2664,6 +3086,11 @@ export declare interface Step1Result {
  */
 export declare const STEP2_SYSTEM_PROMPT = "Complete the data query using actual dimension values from the database.\n\nORIGINAL USER REQUEST: {USER_PROMPT}\n\nCUBE SCHEMA:\n{CUBE_SCHEMA}\n\nAVAILABLE DIMENSION VALUES (from the actual database):\n{DIMENSION_VALUES}\n\nComplete the query using ONLY the values listed above for any dimension filters.\nDo NOT invent or guess filter values - use exactly what's available.\nMatch user intent to the closest available values (e.g., if user says \"opened\" but only \"created\" exists, use \"created\").\n\nRESPONSE FORMAT (same as single-step):\n{\n  \"query\": { /* Cube.js query OR funnel query with actual filter values */ },\n  \"chartType\": \"line\"|\"bar\"|\"area\"|\"pie\"|\"scatter\"|\"bubble\"|\"table\"|\"funnel\",\n  \"chartConfig\": {\n    \"xAxis\": string[],\n    \"yAxis\": string[],\n    \"series\": string[],\n    \"sizeField\": string,\n    \"colorField\": string\n  }\n}\n\nFUNNEL QUERY STRUCTURE (if queryType was \"funnel\"):\n{\n  \"funnel\": {\n    \"bindingKey\": \"PREvents.prNumber\",\n    \"timeDimension\": \"PREvents.timestamp\",\n    \"steps\": [\n      {\n        \"name\": \"Created\",\n        \"filter\": [\n          { \"member\": \"PREvents.eventType\", \"operator\": \"equals\", \"values\": [\"created\"] },\n          { \"member\": \"PREvents.timestamp\", \"operator\": \"inDateRange\", \"values\": [\"last 6 months\"] }\n        ]\n      },\n      {\n        \"name\": \"Merged\",\n        \"filter\": { \"member\": \"PREvents.eventType\", \"operator\": \"equals\", \"values\": [\"merged\"] }\n      }\n    ],\n    \"includeTimeMetrics\": true\n  }\n}\n\nCRITICAL FILTER FORMAT RULES:\n- filter MUST be a flat array of filter objects: [{ member, operator, values }, ...]\n- filter MUST NOT be nested arrays: NOT [[{ member, operator, values }]]\n- For a single filter, use object format: { \"member\": \"...\", \"operator\": \"...\", \"values\": [...] }\n- For multiple filters on step 0, use flat array: [{ filter1 }, { filter2 }] (NOT [[filter1, filter2]])\n- The time filter (inDateRange) goes ONLY on step 0's filter, not on other steps.\n\nReturn ONLY valid JSON - no explanations or markdown:";
 
+/**
+ * Suggest a query based on natural language input
+ */
+export declare function suggestQuery(metadata: CubeMetadata[], naturalLanguage: string, targetCube?: string): QuerySuggestion;
+
 /**
  * Complete system prompt template for single-step query generation.
  *