drizzle-cube 0.1.66 → 0.1.68

package/dist/server/index.d.ts

@@ -436,6 +436,49 @@ export declare interface JoinKeyInfo {
     targetColumnObj?: AnyColumn;
 }
 
+/**
+ * Complete join path from primary to target cube
+ */
+export declare interface JoinPathAnalysis {
+    /** Target cube name */
+    targetCube: string;
+    /** Whether a path was found */
+    pathFound: boolean;
+    /** The join steps (if found) */
+    path?: JoinPathStep[];
+    /** Total path length */
+    pathLength?: number;
+    /** Error message if path not found */
+    error?: string;
+    /** Cubes that were visited during BFS search */
+    visitedCubes?: string[];
+}
+
+/**
+ * Single step in a join path
+ */
+export declare interface JoinPathStep {
+    /** Source cube name */
+    fromCube: string;
+    /** Target cube name */
+    toCube: string;
+    /** Relationship type used */
+    relationship: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    /** SQL join type that will be used */
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    /** Join condition columns */
+    joinColumns: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+    /** Junction table info for belongsToMany */
+    junctionTable?: {
+        tableName: string;
+        sourceColumns: string[];
+        targetColumns: string[];
+    };
+}
+
 export declare type JoinType = 'left' | 'right' | 'inner' | 'full';
 
 export declare interface LogicalFilter {
@@ -558,6 +601,25 @@ export declare class PostgresExecutor extends BaseDatabaseExecutor {
     getEngineType(): 'postgres';
 }
 
+/**
+ * Pre-aggregation CTE analysis
+ */
+export declare interface PreAggregationAnalysis {
+    /** Cube being pre-aggregated */
+    cubeName: string;
+    /** CTE alias in the query */
+    cteAlias: string;
+    /** Why this cube needs a CTE */
+    reason: string;
+    /** Measures included in CTE */
+    measures: string[];
+    /** Join keys used */
+    joinKeys: Array<{
+        sourceColumn: string;
+        targetColumn: string;
+    }>;
+}
+
 /**
  * Pre-aggregation CTE information
  * Describes a Common Table Expression used for pre-aggregating hasMany relationships
@@ -575,12 +637,71 @@ export declare interface PreAggregationCTEInfo {
     measures: string[];
 }
 
+/**
+ * Primary cube selection analysis
+ */
+export declare interface PrimaryCubeAnalysis {
+    /** Name of the selected primary cube */
+    selectedCube: string;
+    /** Reason for selection */
+    reason: PrimaryCubeSelectionReason;
+    /** Human-readable explanation */
+    explanation: string;
+    /** Other candidates that were considered */
+    candidates?: PrimaryCubeCandidate[];
+}
+
+/**
+ * Candidate cube considered for primary selection
+ */
+export declare interface PrimaryCubeCandidate {
+    /** Cube name */
+    cubeName: string;
+    /** Number of dimensions from this cube in the query */
+    dimensionCount: number;
+    /** Number of join definitions on this cube */
+    joinCount: number;
+    /** Whether this cube can reach all other required cubes */
+    canReachAll: boolean;
+}
+
+/**
+ * Query Analysis Types
+ * Provides transparency into query planning decisions for debugging
+ */
+/**
+ * Reason why a cube was selected as primary (FROM table)
+ */
+export declare type PrimaryCubeSelectionReason = 'most_dimensions' | 'most_connected' | 'alphabetical_fallback' | 'single_cube';
+
 /**
  * Any queryable relation that can be used in FROM/JOIN clauses
  * Supports tables, views, subqueries, and raw SQL expressions
  */
 export declare type QueryableRelation = Table | View | Subquery | SQL;
 
+/**
+ * Complete query analysis result
+ */
+export declare interface QueryAnalysis {
+    /** Timestamp of analysis */
+    timestamp: string;
+    /** Number of cubes involved */
+    cubeCount: number;
+    /** List of all cubes used */
+    cubesInvolved: string[];
+    /** Primary cube selection details */
+    primaryCube: PrimaryCubeAnalysis;
+    /** Join path analysis for each joined cube */
+    joinPaths: JoinPathAnalysis[];
+    /** Pre-aggregation CTE details */
+    preAggregations: PreAggregationAnalysis[];
+    /** Overall query structure summary */
+    querySummary: QuerySummary;
+    /** Warnings or potential issues */
+    warnings?: string[];
+}
+
 export declare class QueryBuilder {
     private databaseAdapter;
     constructor(databaseAdapter: DatabaseAdapter);
@@ -867,6 +988,24 @@ export declare class QueryPlanner {
      * Find hasMany join definition from primary cube to target cube
      */
     private findHasManyJoinDef;
+    /**
+     * Analyze query planning decisions without building the full query
+     * Returns detailed metadata about how the query plan would be constructed
+     * Used for debugging and transparency in the playground UI
+     */
+    analyzeQueryPlan(cubes: Map<string, Cube>, query: SemanticQuery, _ctx: QueryContext): QueryAnalysis;
+    /**
+     * Analyze why a particular cube was chosen as primary
+     */
+    private analyzePrimaryCubeSelection;
+    /**
+     * Analyze the join path between two cubes with detailed step information
+     */
+    private analyzeJoinPath;
+    /**
+     * Analyze pre-aggregation requirements for hasMany relationships
+     */
+    private analyzePreAggregations;
 }
 
 /**
@@ -882,6 +1021,20 @@ export declare interface QueryResult {
     };
 }
 
+/**
+ * Query structure summary
+ */
+export declare interface QuerySummary {
+    /** Query type: 'single_cube', 'multi_cube_join', or 'multi_cube_cte' */
+    queryType: 'single_cube' | 'multi_cube_join' | 'multi_cube_cte';
+    /** Total number of joins */
+    joinCount: number;
+    /** Total number of CTEs */
+    cteCount: number;
+    /** Has hasMany relationships requiring aggregation */
+    hasPreAggregation: boolean;
+}
+
 /**
  * Resolve cube reference (handles both direct and lazy references)
  */
@@ -1036,6 +1189,12 @@ export declare class SemanticLayerCompiler {
         isValid: boolean;
         errors: string[];
     };
+    /**
+     * Analyze query planning decisions for debugging and transparency
+     * Returns detailed metadata about how the query would be planned
+     * Used by the playground UI to help users understand query structure
+     */
+    analyzeQuery(query: SemanticQuery, securityContext: SecurityContext): QueryAnalysis;
 }
 
 /**