drizzle-cube 0.5.8 → 0.6.1

package/dist/server/server/logical-plan/logical-planner.d.ts

@@ -1,232 +0,0 @@
-import { Cube, QueryContext, PhysicalQueryPlan, SemanticQuery, PrimaryCubeAnalysis, JoinPathAnalysis, QueryWarning } from '../types';
-/**
- * Pre-aggregation plan for handling hasMany relationships
- */
-export declare class LogicalPlanner {
-    private resolverCache;
-    /**
-     * Get or create a JoinPathResolver for the given cubes map
-     */
-    private getResolver;
-    /**
-     * Analyze a semantic query to determine which cubes are involved
-     */
-    analyzeCubeUsage(query: SemanticQuery): Set<string>;
-    /**
-     * Build query-level path hints (Cube-style) from all query members:
-     * measures, dimensions, time dimensions, filters, and order-by.
-     * These hints guide path selection toward the semantic query grain.
-     */
-    private collectPathHintCubes;
-    /**
-     * Recursively extract cube names from filters (handles logical filters)
-     */
-    private extractCubeNamesFromFilter;
-    /**
-     * Extract measures referenced in filters (for CTE inclusion)
-     */
-    private extractMeasuresFromFilters;
-    /**
-     * Recursively extract measures from filters for a specific cube
-     * Only includes filter members that are actually measures (not dimensions)
-     */
-    private extractMeasuresFromFilter;
-    /**
-     * Choose the primary cube based on query analysis
-     * Uses a consistent strategy to avoid measure order dependencies
-     *
-     * Delegates to analyzePrimaryCubeSelection() for the actual logic,
-     * ensuring a single source of truth for primary cube selection.
-     */
-    choosePrimaryCube(cubeNames: string[], query: SemanticQuery, cubes?: Map<string, Cube>): string;
-    /**
-     * Analyze primary cube selection with candidate details.
-     * Exposed for LogicalPlanBuilder so dry-run/analyze can report
-     * exactly which selection rule was used.
-     */
-    analyzePrimaryCube(cubeNames: string[], query: SemanticQuery, cubes: Map<string, Cube>): PrimaryCubeAnalysis;
-    /**
-     * Analyze join path for a specific target cube.
-     * Exposed for LogicalPlanBuilder to provide join decision trace.
-     */
-    analyzeJoinPathForTarget(cubes: Map<string, Cube>, fromCube: string, toCube: string, query?: SemanticQuery): JoinPathAnalysis;
-    /**
-     * Build join plan for a known primary cube.
-     * Exposed for LogicalPlanBuilder so logical planning can compose
-     * planner phases directly.
-     */
-    buildJoinPlanForPrimary(cubes: Map<string, Cube>, primaryCube: Cube, cubeNames: string[], ctx: QueryContext, query: SemanticQuery): PhysicalQueryPlan['joinCubes'];
-    /**
-     * Build pre-aggregation CTE plan from a primary cube and join plan.
-     * Exposed for LogicalPlanBuilder phase composition.
-     */
-    buildPreAggregationCTEs(cubes: Map<string, Cube>, primaryCube: Cube, joinCubes: PhysicalQueryPlan['joinCubes'], query: SemanticQuery, ctx: QueryContext): PhysicalQueryPlan['preAggregationCTEs'];
-    /**
-     * Generate query warnings from pre-aggregation analysis.
-     * Exposed for LogicalPlanBuilder phase composition.
-     */
-    buildWarnings(query: SemanticQuery, preAggregationCTEs?: PhysicalQueryPlan['preAggregationCTEs']): QueryWarning[];
-    /**
-     * Build join plan for multi-cube query
-     * Supports both direct joins and transitive joins through intermediate cubes
-     *
-     * Uses query-aware path selection to prefer joining through cubes that have
-     * measures in the query (e.g., joining Teams through EmployeeTeams when
-     * EmployeeTeams.count is a measure)
-     */
-    private buildJoinPlan;
-    /**
-     * Plan pre-aggregation CTEs for hasMany relationships to prevent fan-out
-     * Note: belongsToMany relationships handle fan-out differently through their junction table structure
-     * and don't require CTEs - the two-hop join with the junction table provides natural grouping
-     *
-     * CRITICAL FAN-OUT PREVENTION LOGIC:
-     * When a query contains ANY hasMany relationship in the join graph, ALL cubes with measures
-     * that could be affected by row multiplication need CTEs. This includes:
-     *
-     * 1. Cubes with direct hasMany FROM primary (existing logic)
-     * 2. Cubes with measures that would be multiplied due to hasMany elsewhere in the query
-     *    - Example: Query has Departments.totalBudget + Productivity.recordCount
-     *    - Employees hasMany → Productivity causes row multiplication
-     *    - Departments.totalBudget would be inflated without CTE pre-aggregation
-     */
-    private planPreAggregationCTEs;
-    /**
-     * Find join information TO a cube (reverse lookup)
-     * Used when the primary cube needs a CTE and we need to find how other cubes join to it
-     */
-    private findJoinInfoToCube;
-    /**
-     * Analyze the join path from primary cube to a target CTE cube.
-     * Detects if there are intermediate hasMany relationships that would cause fan-out.
-     *
-     * Returns information about:
-     * - The full join path
-     * - Whether there are hasMany relationships ON the path (not just at the end)
-     * - Which intermediate tables need to be absorbed into the CTE
-     * - The correct join key to use (from primary cube's connection point)
-     *
-     * @param cubes Map of all registered cubes
-     * @param primaryCube The primary cube (FROM clause)
-     * @param targetCubeName The CTE cube we're analyzing the path to
-     * @param ctx Query context for security filtering
-     */
-    private analyzeJoinPathToPrimary;
-    /**
-     * Compute CTE reasons from the actual join plan entries.
-     *
-     * Instead of scanning all registered cubes (which causes false positives when
-     * unrelated hasMany relationships exist), this walks only the planned joins
-     * using the `relationship` field now stored on each JoinCubePlanEntry.
-     *
-     * Algorithm:
-     * 1. Scan join plan entries for hasMany/belongsToMany relationships
-     * 2. If none found → return empty map (no CTEs needed)
-     * 3. hasMany/belongsToMany targets with measures → 'hasMany'
-     * 4. Other join cubes with measures (not hasMany source) → 'fanOutPrevention'
-     */
-    private computeCTEReasons;
-    /**
-     * Find join information for a cube from any cube in the query
-     * This extends findHasManyJoinDef to work with any relationship type
-     * and to search from any source cube, not just the primary
-     */
-    private findJoinInfoForCube;
-    /**
-     * Find downstream cubes that need join keys included in the CTE.
-     *
-     * When a query has dimensions from a cube (e.g., Teams.name) and measures from
-     * a junction cube (e.g., EmployeeTeams.count), the junction CTE needs to include
-     * the join key to the dimension cube (team_id) so the dimension cube can be
-     * joined through the CTE instead of via an alternative path.
-     *
-     * @param cteCube The cube being converted to a CTE (e.g., EmployeeTeams)
-     * @param query The semantic query with dimensions and measures
-     * @param allCubes Map of all registered cubes
-     * @returns Array of downstream join key info for cubes needing join through this CTE
-     */
-    private findDownstreamJoinKeys;
-    /**
-     * Expand calculated measures to include their dependencies
-     */
-    private expandCalculatedMeasureDependencies;
-    /**
-     * Extract measure references from calculatedSql template
-     */
-    private extractDependenciesFromTemplate;
-    /**
-     * Find hasMany join definition from primary cube to target cube
-     */
-    private findHasManyJoinDef;
-    /**
-     * Find filters that need to propagate from related cubes to a CTE cube.
-     * When cube A has filters and a hasMany relationship to cube B (the CTE cube),
-     * A's filters should propagate into B's CTE via a subquery.
-     *
-     * Example: Employees.createdAt filter should propagate to Productivity CTE
-     * via: employee_id IN (SELECT id FROM employees WHERE created_at >= $date)
-     */
-    private findPropagatingFilters;
-    /**
-     * Extract cube names from filters into a Set (helper for findPropagatingFilters)
-     */
-    private extractFilterCubeNamesToSet;
-    /**
-     * Extract filters for a specific cube from the filter array
-     *
-     * Logic for preserving filter semantics:
-     * - AND: Safe to extract only matching branches (AND of fewer conditions is more permissive)
-     * - OR: Must include ALL branches or skip entirely (partial OR changes semantics)
-     *       If any branch belongs to another cube, skip the entire OR to be safe
-     *       since we can't evaluate the other cube's conditions
-     */
-    private extractFiltersForCube;
-    /**
-     * Check if all simple filters in a filter array belong to the specified cube
-     * Recursively checks nested AND/OR filters
-     */
-    private allFiltersFromCube;
-    /**
-     * Extract time dimension date range filters as regular filters for a specific cube
-     */
-    private extractTimeDimensionFiltersForCube;
-    /**
-     * Analyze why a particular cube was chosen as primary
-     */
-    private analyzePrimaryCubeSelection;
-    /**
-     * Analyze the join path between two cubes with detailed step information
-     *
-     * Uses JoinPathResolver.findPath() for the actual path finding,
-     * then converts the result to human-readable analysis format.
-     */
-    private analyzeJoinPath;
-    private convertInternalPathToJoinPathSteps;
-    private buildJoinPathSelectionAnalysis;
-    private mapPreferredCandidate;
-    /**
-     * Generate warnings for query edge cases that users should be aware of.
-     * Currently detects:
-     * - FAN_OUT_NO_DIMENSIONS: Query has hasMany CTEs but no dimensions to group by
-     *
-     * Note: AVG measures in hasMany CTEs can produce mathematically imprecise results
-     * (average of averages vs weighted average), but this warning was removed as it
-     * fired too aggressively. The issue only occurs when the outer grouping is coarser
-     * than the CTE grouping, which is rare in practice. The limitation is documented
-     * in executor.ts comments.
-     */
-    private generateWarnings;
-    /**
-     * Detect when a query has measures from multiple cubes with hasMany relationships
-     * but no dimensions to provide grouping context.
-     *
-     * This is an edge case where:
-     * - Query has measures from 2+ cubes
-     * - At least one CTE exists (indicating hasMany relationship)
-     * - Query has NO dimensions AND NO time dimensions with granularity
-     *
-     * The SQL is technically correct (CTEs with GROUP BY on join keys), but users
-     * may be confused by the aggregated results without visible grouping.
-     */
-    private checkFanOutNoDimensions;
-}

package/dist/server/server/physical-plan/drizzle-plan-builder.d.ts

@@ -1,50 +0,0 @@
-import { DatabaseAdapter } from '../adapters/base-adapter';
-import { DrizzleSqlBuilder } from './drizzle-sql-builder';
-import { CTEBuilder } from '../builders/cte-builder';
-import { PhysicalQueryPlan, QueryContext, SemanticQuery } from '../types';
-import { QueryNode } from '../logical-plan';
-/**
- * Converts optimised logical plans into runtime physical query plans,
- * then builds executable Drizzle queries.
- */
-export declare class DrizzlePlanBuilder {
-    private readonly queryBuilder;
-    private readonly cteBuilder;
-    private readonly databaseAdapter;
-    constructor(queryBuilder: DrizzleSqlBuilder, cteBuilder: CTEBuilder, databaseAdapter: DatabaseAdapter);
-    /**
-     * Build runtime physical context from an optimised logical plan.
-     * This is the physical-builder input for SQL generation.
-     */
-    derivePhysicalPlanContext(plan: QueryNode): PhysicalQueryPlan;
-    private derivePhysicalPlanContextFromMultiFact;
-    private derivePhysicalPlanContextFromFullKeyAggregate;
-    private toSemanticQuery;
-    private resolvePhysicalSimpleSource;
-    private resolvePhysicalSimpleSourceFromKeysDedup;
-    private resolveKeysDeduplicationMeta;
-    /**
-     * Build unified query that works for both single and multi-cube queries.
-     */
-    build(queryPlan: PhysicalQueryPlan, query: SemanticQuery, context: QueryContext): any;
-    private tryBuildKeysDeduplicationQuery;
-    private tryBuildMultiFactMergeQuery;
-    private buildMultiFactUnionKeysFallbackQuery;
-    private buildSharedKeySelection;
-    private selectRuntimeMergeStrategy;
-    private supportsFullOuterJoin;
-    private coalesceQualifiedColumn;
-    private canExecuteKeysDeduplication;
-    private queryContainsMeasureFilter;
-    private getPrimaryKeyDimensions;
-    /**
-     * Build type-specific outer aggregation for keys deduplication.
-     * Each measure type needs different re-aggregation in the outer query:
-     * - sum/count/number: SUM (re-combine additive values)
-     * - min: MIN (preserve minimum across groups)
-     * - max: MAX (preserve maximum across groups)
-     * - avg: SUM(sums) / NULLIF(SUM(counts), 0) (weighted average from decomposed parts)
-     */
-    private buildKeysOuterAggregation;
-    private applyJoinByType;
-}

package/dist/server/server/physical-plan/index.d.ts

@@ -1,2 +0,0 @@
-export { DrizzlePlanBuilder } from './drizzle-plan-builder';
-export { DrizzleSqlBuilder } from './drizzle-sql-builder';

package/dist/server/server/physical-plan/processors/index.d.ts

@@ -1,6 +0,0 @@
-export { buildCTEState } from './cte-processor';
-export { buildModifiedSelections } from './selection-processor';
-export { applyJoins } from './joins-processor';
-export { applyPredicatesAndFinalize } from './predicates-processor';
-export type { PhysicalBuildDependencies, CTEBuildState, JoinBuildState, SelectionMap, DownstreamJoinState } from './shared';
-export { getCubesFromPlan } from './shared';

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

@@ -1,11 +0,0 @@
-export * from './core';
-export * from './query';
-export * from './funnel';
-export * from './retention';
-export * from './cube';
-export * from './executor';
-export * from './metadata';
-export * from './analysis';
-export * from './utils';
-export * from './cache';
-export { defineCube } from '../cube-utils';