drizzle-cube 0.6.0 → 0.6.2

package/dist/server/query-handlers.d.ts

@@ -0,0 +1,79 @@
+import { SemanticLayerCompiler } from './compiler.js';
+import { SemanticQuery, SecurityContext } from './types/index.js';
+import { CubeDiscoveryResult } from './ai/discovery.js';
+/**
+ * Discovery request body
+ */
+export interface DiscoverRequest {
+    /** Topic or keyword to search for */
+    topic?: string;
+    /** Natural language intent */
+    intent?: string;
+    /** Maximum results to return */
+    limit?: number;
+    /** Minimum relevance score (0-1) */
+    minScore?: number;
+}
+/**
+ * Load request body - execute a query
+ */
+export interface LoadRequest {
+    /** Query to execute */
+    query: SemanticQuery;
+}
+/**
+ * Discovery response shape returned by `handleDiscover`.
+ *
+ * In addition to the matched cubes, the response embeds the full query
+ * language reference and the date filtering decision tree. This is the
+ * primary delivery mechanism for query-construction guidance: clients
+ * cannot be relied upon to forward `prompts/*` content to the model, so
+ * we piggyback on `discover` (the mandated first call in our workflow)
+ * to guarantee the model sees the rules before it builds a query.
+ *
+ * The fields are stable strings — consumers may render or strip them as
+ * they see fit, but the MCP `discover` tool relies on them being present.
+ */
+export interface DiscoverResponse {
+    /** Matched cubes (possibly empty) with measures, dimensions, and joins */
+    cubes: CubeDiscoveryResult[];
+    /**
+     * Complete TypeScript DSL reference for query construction. Source of
+     * truth for field naming, filter operators, time dimensions, and
+     * analysis modes (funnel/flow/retention).
+     */
+    queryLanguageReference: string;
+    /**
+     * Decision tree for date filtering vs time grouping. The single most
+     * common source of incorrect queries — read this whenever the user
+     * mentions a time period.
+     */
+    dateFilteringGuide: string;
+}
+/**
+ * Handle /discover endpoint - find relevant cubes based on topic/intent.
+ *
+ * Always returns `queryLanguageReference` and `dateFilteringGuide` alongside
+ * the matched cubes. See `DiscoverResponse` for the rationale.
+ */
+export declare function handleDiscover(semanticLayer: SemanticLayerCompiler, body: DiscoverRequest): Promise<DiscoverResponse>;
+/**
+ * Normalize AI-generated query fields before validation/execution.
+ * Fixes common LLM mistakes:
+ * - Double-prefixed fields: "Teams.Teams.name" -> "Teams.name"
+ * - Order as array: [{key: dir}] -> {key: dir}
+ * - Underscore order keys: "Teams_count" -> "Teams.count"
+ * - Invalid order keys dropped (falls back to first measure desc)
+ *
+ * This runs in the shared handleLoad path so both MCP and Agent benefit.
+ */
+export declare function normalizeQueryFields(query: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Handle /load endpoint - execute a query and return results
+ * This completes the AI workflow: discover → suggest → validate → load
+ */
+export declare function handleLoad(semanticLayer: SemanticLayerCompiler, securityContext: SecurityContext, body: LoadRequest): Promise<{
+    data: Record<string, unknown>[];
+    annotation: any;
+    query: SemanticQuery;
+}>;

package/dist/server/query-modes.d.ts

@@ -0,0 +1,28 @@
+import { SemanticQuery } from './types/index.js';
+export type QueryMode = 'regular' | 'comparison' | 'funnel' | 'flow' | 'retention';
+export interface QueryModeFlags {
+    comparison: boolean;
+    funnel: boolean;
+    flow: boolean;
+    retention: boolean;
+}
+/** A query is a comparison when a time dimension carries a compareDateRange with ≥2 ranges. */
+export declare function hasComparisonMode(query: SemanticQuery): boolean;
+/**
+ * A query is a funnel when it has a funnel config with ≥2 steps.
+ * Null-safe on `steps` — a `funnel: {}` payload must not throw here.
+ */
+export declare function hasFunnelMode(query: SemanticQuery): boolean;
+/** A query is a flow when it has a flow config with a startingStep and eventDimension. */
+export declare function hasFlowMode(query: SemanticQuery): boolean;
+/** A query is a retention when it has a retention config with a timeDimension and bindingKey. */
+export declare function hasRetentionMode(query: SemanticQuery): boolean;
+/** Per-mode booleans for a query. */
+export declare function detectQueryModes(query: SemanticQuery): QueryModeFlags;
+/**
+ * Active non-regular modes for a query, in execution-priority order
+ * (comparison, funnel, flow, retention). A well-formed query matches at most one.
+ */
+export declare function getActiveQueryModes(query: SemanticQuery): Exclude<QueryMode, 'regular'>[];
+/** The single priority mode for a query, or 'regular' when none match. */
+export declare function detectQueryMode(query: SemanticQuery): QueryMode;

package/dist/server/query-validator.d.ts

@@ -0,0 +1,9 @@
+import { SemanticQuery, Cube } from './types/index.js';
+/**
+ * Validate a query against a cubes map
+ * Standalone function that can be used by both compiler and executor
+ */
+export declare function validateQueryAgainstCubes(cubes: Map<string, Cube>, query: SemanticQuery): {
+    isValid: boolean;
+    errors: string[];
+};

package/dist/server/resolvers/calculated-measure-resolver.d.ts

@@ -0,0 +1,98 @@
+import { Cube, Measure } from '../types/cube.js';
+/**
+ * Dependency information for a calculated measure
+ */
+export interface MeasureDependency {
+    /** Full measure name (e.g., "Cube.measure" or "measure") */
+    measureName: string;
+    /** Referenced cube name (null if same cube) */
+    cubeName: string | null;
+    /** Referenced field name */
+    fieldName: string;
+}
+/**
+ * Calculated Measure Resolver
+ * Manages dependency resolution for calculated measures
+ */
+export declare class CalculatedMeasureResolver {
+    private dependencyGraph;
+    private cubes;
+    constructor(cubes: Map<string, Cube> | Cube);
+    /**
+     * Extract {member} references from calculatedSql template
+     * Supports both {measure} and {Cube.measure} syntax
+     *
+     * @param calculatedSql - Template string with {member} references
+     * @returns Array of dependency information
+     */
+    extractDependencies(calculatedSql: string): MeasureDependency[];
+    /**
+     * Build dependency graph for all calculated measures in a cube
+     *
+     * @param cube - The cube containing measures
+     */
+    buildGraph(cube: Cube): void;
+    /**
+     * Build dependency graph for multiple cubes
+     *
+     * @param cubes - Map of cubes to analyze
+     */
+    buildGraphForMultipleCubes(cubes: Map<string, Cube>): void;
+    /**
+     * Calculate in-degree for each node (number of measures depending on it)
+     */
+    private calculateInDegrees;
+    /**
+     * Perform topological sort using Kahn's algorithm
+     * Returns measures in dependency order (dependencies first)
+     *
+     * @param measureNames - List of measure names to sort
+     * @returns Sorted array of measure names
+     * @throws Error if circular dependency detected
+     */
+    topologicalSort(measureNames: string[]): string[];
+    /**
+     * Build a subgraph containing only the requested measures, with in-degrees
+     * recomputed to count only dependencies that are within the subgraph.
+     */
+    private buildSubgraph;
+    /**
+     * Detect circular dependencies using DFS
+     * Returns the cycle path if found, null otherwise
+     *
+     * @returns Array representing the cycle, or null
+     */
+    detectCycle(): string[] | null;
+    /**
+     * DFS helper for cycle detection
+     */
+    private dfs;
+    /**
+     * Get all dependencies for a specific measure (direct and transitive)
+     *
+     * @param measureName - Full measure name (e.g., "Cube.measure")
+     * @returns Set of all dependency measure names
+     */
+    getAllDependencies(measureName: string): Set<string>;
+    /**
+     * Validate that all dependencies exist
+     *
+     * @param cube - The cube to validate
+     * @throws Error if dependencies are missing
+     */
+    validateDependencies(cube: Cube): void;
+    /**
+     * Auto-populate dependencies array for calculated measures
+     * Updates the measure objects with detected dependencies
+     *
+     * @param cube - The cube to update
+     */
+    populateDependencies(cube: Cube): void;
+    /**
+     * Check if a measure is a calculated measure
+     *
+     * @param measure - The measure to check
+     * @returns True if the measure is calculated
+     */
+    static isCalculatedMeasure(measure: Measure): boolean;
+}

package/dist/server/resolvers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolvers Index
+ * Re-exports resolver components for modular imports
+ */
+export { CalculatedMeasureResolver } from './calculated-measure-resolver.js';
+export { JoinPathResolver } from './join-path-resolver.js';

package/dist/server/resolvers/join-path-resolver.d.ts

@@ -0,0 +1,158 @@
+import { Cube, CubeJoin } from '../types/index.js';
+import { SQL } from 'drizzle-orm';
+/**
+ * Internal representation of a join path step
+ * Used during path finding - simpler than the public JoinPathStep analysis type
+ */
+export interface InternalJoinPathStep {
+    /** Source cube name */
+    fromCube: string;
+    /** Target cube name */
+    toCube: string;
+    /** The join definition from the source cube */
+    joinDef: CubeJoin;
+    /** True when this step was discovered via a reversed edge (target cube defines the join back to source) */
+    reversed?: boolean;
+}
+/**
+ * Score breakdown for a candidate preferred path.
+ */
+export interface PreferredPathScoreBreakdown {
+    preferredJoinBonus: number;
+    preferredCubeBonus: number;
+    lengthPenalty: number;
+}
+/**
+ * A scored candidate path considered by preferred-path selection.
+ */
+export interface PreferredPathCandidateScore {
+    path: InternalJoinPathStep[];
+    score: number;
+    usesPreferredJoin: boolean;
+    preferredCubesInPath: number;
+    usesProcessed: boolean;
+    scoreBreakdown: PreferredPathScoreBreakdown;
+}
+/**
+ * Detailed preferred-path selection output for analysis/debug UIs.
+ */
+export interface PreferredPathSelection {
+    strategy: 'preferred' | 'fallbackShortest';
+    preferredCubes: string[];
+    selectedIndex: number;
+    candidates: PreferredPathCandidateScore[];
+    selectedPath: InternalJoinPathStep[] | null;
+}
+/**
+ * Resolves join paths between cubes and manages connectivity caching.
+ * Supports bidirectional path finding: both forward (outgoing) joins and
+ * reverse (incoming) joins are traversable. Reversed steps are marked with
+ * `reversed: true` so downstream code can adjust join type and analysis.
+ */
+export declare class JoinPathResolver {
+    private cubes;
+    private connectivityCache;
+    /** Maps cubeName → joins that TARGET that cube (incoming edges) */
+    private reverseIndex;
+    /**
+     * @param cubes Map of cube name to cube definition
+     */
+    constructor(cubes: Map<string, Cube>);
+    /**
+     * Build reverse adjacency index: for each cube's outgoing join A→B,
+     * store an entry under B pointing back to A.
+     *
+     * Excludes belongsToMany joins because reversing them requires swapping
+     * sourceKey/targetKey in the junction table configuration, which is
+     * error-prone. The 2-hop forward path through the junction table handles
+     * these relationships correctly.
+     */
+    private buildReverseIndex;
+    /**
+     * Find the shortest join path from source cube to target cube
+     * Uses BFS algorithm for optimal path discovery
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param alreadyProcessed Set of cubes to exclude from path finding
+     * @returns Array of join steps or null if no path exists
+     */
+    findPath(fromCube: string, toCube: string, alreadyProcessed?: Set<string>): InternalJoinPathStep[] | null;
+    /**
+     * Enumerate the neighbouring cubes reachable from `currentCube` in one hop,
+     * yielding the resulting join step. Forward edges (outgoing joins) come first,
+     * then reverse edges (incoming joins) unless `forwardOnly` is set.
+     */
+    private neighbourSteps;
+    /**
+     * Find path that prefers going through specified cubes when possible
+     * Used when certain cubes have measures in the query - ensures joins go through
+     * the semantically correct path (e.g., through junction tables when their measures are used)
+     *
+     * IMPORTANT: This method allows paths to go THROUGH already-processed cubes (as intermediate
+     * steps) but won't return them as new cubes to add. This is crucial for preferring paths
+     * through cubes that have measures (like junction tables).
+     *
+     * Path scoring priority (highest to lowest):
+     * 1. Paths using joins with `preferredFor` that includes the target cube (score +10)
+     * 2. Paths going through cubes with measures in the query (score +1 per cube)
+     * 3. Paths reusing already-processed cubes
+     * 4. Shorter paths
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param preferredCubes Set of cube names to prefer in the path (usually cubes with measures)
+     * @param alreadyProcessed Set of cubes already in the join plan (can be used as intermediates)
+     * @returns Array of join steps or null if no path exists
+     */
+    findPathPreferring(fromCube: string, toCube: string, preferredCubes: Set<string>, alreadyProcessed?: Set<string>): InternalJoinPathStep[] | null;
+    /**
+     * Find preferred path with candidate scoring telemetry.
+     * Used by analysis/debug panels to explain planner decisions.
+     */
+    findPathPreferringDetailed(fromCube: string, toCube: string, preferredCubes: Set<string>, alreadyProcessed?: Set<string>): PreferredPathSelection;
+    /**
+     * Find all possible paths between two cubes (up to maxDepth)
+     * Used by findPathPreferring to evaluate multiple paths
+     *
+     * @param fromCube Source cube name
+     * @param toCube Target cube name
+     * @param alreadyProcessed Set of cubes to exclude from path finding
+     * @param maxDepth Maximum path length to search (default 4 to avoid explosion)
+     * @returns Array of all valid paths
+     */
+    private findAllPaths;
+    /**
+     * Check if a cube can reach all other cubes in the list via joins
+     *
+     * @param fromCube Starting cube name
+     * @param allCubes List of all cubes that must be reachable
+     * @returns true if all cubes are reachable
+     */
+    canReachAll(fromCube: string, allCubes: string[]): boolean;
+    /**
+     * Forward-only path finding (no reverse edges).
+     * Used by canReachAll for primary cube selection to preserve join semantics.
+     */
+    private findForwardOnlyPath;
+    /**
+     * Build SQL join condition from join definition
+     *
+     * @param joinDef The cube join definition
+     * @param sourceAlias Optional alias for source table (null uses actual column)
+     * @param targetAlias Optional alias for target table (null uses actual column)
+     * @returns SQL condition for the join
+     */
+    buildJoinCondition(joinDef: CubeJoin, sourceAlias: string | null, targetAlias: string | null): SQL;
+    /**
+     * Get all reachable cubes from a starting cube
+     * Useful for analyzing cube connectivity
+     *
+     * @param fromCube Starting cube name
+     * @returns Set of all reachable cube names
+     */
+    getReachableCubes(fromCube: string): Set<string>;
+    private getCacheKey;
+    private getFromCache;
+    private setInCache;
+}

package/dist/server/sql-format.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SQL pretty-printing for generated queries.
+ *
+ * Lives in the server layer (rather than adapters/) so that the compiler can
+ * format SQL without importing up into the framework-adapter layer — which
+ * would create an import cycle (compiler → adapters/utils → server).
+ */
+/**
+ * Format SQL string using sql-formatter with appropriate dialect
+ */
+export declare function formatSqlString(sqlString: string, engineType: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake'): string;

package/dist/server/template-substitution.d.ts

@@ -0,0 +1,57 @@
+import { SQL } from 'drizzle-orm';
+import { Cube, QueryContext } from './types/cube.js';
+/**
+ * Resolved measure SQL builders
+ * Maps full measure names (e.g., "Cube.measure") to functions that build their SQL
+ * Using functions instead of SQL objects avoids mutation and shared reference issues
+ */
+export type ResolvedMeasures = Map<string, () => SQL>;
+/**
+ * Substitution context
+ */
+export interface SubstitutionContext {
+    /** The cube being processed */
+    cube: Cube;
+    /** All available cubes for cross-cube references */
+    allCubes: Map<string, Cube>;
+    /** Already resolved measure SQL expressions */
+    resolvedMeasures: ResolvedMeasures;
+    /** Query context for SQL generation */
+    queryContext: QueryContext;
+}
+/**
+ * Substitute {member} references in calculatedSql template
+ *
+ * Replaces {member} with the corresponding SQL expression from resolvedMeasures.
+ * Supports both same-cube ({measure}) and cross-cube ({Cube.measure}) references.
+ *
+ * @param calculatedSql - Template string with {member} references
+ * @param context - Substitution context
+ * @returns SQL expression with substituted values
+ * @throws Error if referenced measure is not resolved
+ */
+export declare function substituteTemplate(calculatedSql: string, context: SubstitutionContext): SQL;
+/**
+ * Validate calculatedSql template syntax
+ *
+ * @param calculatedSql - Template string to validate
+ * @returns Validation result
+ */
+export declare function validateTemplateSyntax(calculatedSql: string): {
+    isValid: boolean;
+    errors: string[];
+};
+/**
+ * Check if a template contains any member references
+ *
+ * @param calculatedSql - Template string to check
+ * @returns True if template contains {member} references
+ */
+export declare function hasMemberReferences(calculatedSql: string): boolean;
+/**
+ * Get list of all unique member references in a template
+ *
+ * @param calculatedSql - Template string
+ * @returns Array of unique full member names (e.g., ["Cube.measure", "otherMeasure"])
+ */
+export declare function getMemberReferences(calculatedSql: string, currentCube: string): string[];

package/dist/server/types/analysis.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Query Analysis Types
+ * Provides transparency into query planning decisions for debugging
+ */
+/**
+ * Reason why a cube was selected as primary (FROM table)
+ */
+export type PrimaryCubeSelectionReason = 'most_dimensions' | 'most_connected' | 'alphabetical_fallback' | 'single_cube';
+/**
+ * Candidate cube considered for primary selection
+ */
+export 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;
+}
+/**
+ * Primary cube selection analysis
+ */
+export 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[];
+}
+/**
+ * Single step in a join path
+ */
+export interface JoinPathStep {
+    /** Source cube name */
+    fromCube: string;
+    /** Target cube name */
+    toCube: string;
+    /** Relationship type used (effective, after reversal if applicable) */
+    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[];
+    };
+    /** True when this step was discovered via a reversed edge */
+    reversed?: boolean;
+}
+/**
+ * Complete join path from primary to target cube
+ */
+export 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[];
+    /** Path selection decision and scoring details (when preferred routing is used) */
+    selection?: {
+        strategy: 'shortest' | 'preferred' | 'fallbackShortest';
+        preferredCubes?: string[];
+        selectedRank?: number;
+        selectedScore?: number;
+        candidates?: Array<{
+            rank: number;
+            score: number;
+            usesPreferredJoin: boolean;
+            preferredCubesInPath: number;
+            usesProcessed: boolean;
+            scoreBreakdown: {
+                preferredJoinBonus: number;
+                preferredCubeBonus: number;
+                lengthPenalty: number;
+            };
+            path: JoinPathStep[];
+        }>;
+    };
+}
+/**
+ * Pre-aggregation CTE analysis
+ */
+/**
+ * Reason why a cube requires a CTE
+ */
+export type CTEReason = 'hasMany' | 'fanOutPrevention';
+export interface PreAggregationAnalysis {
+    /** Cube being pre-aggregated */
+    cubeName: string;
+    /** CTE alias in the query */
+    cteAlias: string;
+    /** Why this cube needs a CTE (human-readable explanation) */
+    reason: string;
+    /** Typed reason for programmatic use */
+    reasonType?: CTEReason;
+    /** 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';
+}
+/**
+ * Query structure summary
+ */
+export interface QuerySummary {
+    /** Query type: 'single_cube', 'multi_cube_join', or 'multi_cube_cte' */
+    queryType: 'single_cube' | 'multi_cube_join' | 'multi_cube_cte';
+    /** Strategy selected for multiplied-measure handling / multi-fact merge */
+    measureStrategy?: 'simple' | 'keysDeduplication' | 'ctePreAggregateFallback' | 'multiFactMerge';
+    /** Total number of joins */
+    joinCount: number;
+    /** Total number of CTEs */
+    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;
+}
+/**
+ * Structured planner trace for explain/dry-run UIs.
+ * Captures key decisions made during logical planning.
+ */
+export interface PlanningTraceStep {
+    /** Pipeline phase name */
+    phase: 'cube_usage' | 'primary_cube_selection' | 'join_planning' | 'cte_planning' | 'measure_strategy' | 'warnings';
+    /** Short summary of what was decided */
+    decision: string;
+    /** Optional machine-readable details */
+    details?: Record<string, unknown>;
+}
+export interface PlanningTrace {
+    /** Ordered decision trace */
+    steps: PlanningTraceStep[];
+}
+/**
+ * Complete query analysis result
+ */
+export 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[];
+    /** Structured decision trace for debugging and dry-run UIs */
+    planningTrace?: PlanningTrace;
+}