drizzle-cube 0.6.0 → 0.6.2

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

@@ -0,0 +1,34 @@
+import { LogicalNode } from './types.js';
+/** Database engine the optimiser is targeting (all 7 supported engines). */
+export type OptimiserEngineType = 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+/** Context available to optimiser passes */
+export interface OptimiserContext {
+    /** Database engine type for engine-specific rewrites */
+    engineType: OptimiserEngineType;
+}
+/** A single optimiser pass that rewrites a logical plan */
+export interface PlanOptimiser {
+    /** Human-readable name for debugging / explain output */
+    readonly name: string;
+    /** Rewrite the plan tree. Must return a valid plan (may return the same reference). */
+    optimise(plan: LogicalNode, context: OptimiserContext): LogicalNode;
+}
+/**
+ * No-op optimiser — returns the plan unchanged.
+ * Used as the default in Phase 1 and as a baseline for testing.
+ */
+export declare class IdentityOptimiser implements PlanOptimiser {
+    readonly name = "identity";
+    optimise(plan: LogicalNode): LogicalNode;
+}
+/**
+ * Runs a sequence of optimiser passes in order.
+ * Short-circuits if a pass returns a different reference (for future use).
+ */
+export declare class OptimiserPipeline implements PlanOptimiser {
+    readonly name = "pipeline";
+    private passes;
+    constructor(passes?: PlanOptimiser[]);
+    optimise(plan: LogicalNode, context: OptimiserContext): LogicalNode;
+    addPass(pass: PlanOptimiser): void;
+}

package/dist/server/logical-plan/plan-analysis-reporter.d.ts

@@ -0,0 +1,59 @@
+import { Cube, PhysicalQueryPlan, SemanticQuery, PrimaryCubeAnalysis, JoinPathAnalysis, QueryWarning } from '../types/index.js';
+import { ResolverCache } from './planner-utils.js';
+export declare class PlanAnalysisReporter {
+    private readonly resolverCache;
+    constructor(resolverCache: ResolverCache);
+    /**
+     * Analyze why a particular cube was chosen as primary
+     */
+    analyzePrimaryCubeSelection(cubeNames: string[], query: SemanticQuery, cubes: Map<string, Cube>): PrimaryCubeAnalysis;
+    /**
+     * Build the scored candidate list (dimension count, join count, reachability).
+     */
+    private buildPrimaryCubeCandidates;
+    /**
+     * Tier 1: select the cube with the most query dimensions that can reach all
+     * others. Returns null when no dimension-based winner applies.
+     */
+    private selectByDimensions;
+    /**
+     * Tier 2: among cubes that can reach all others, select the most connected.
+     * Returns null when no candidate can reach all others.
+     */
+    private selectByConnectivity;
+    /**
+     * 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.
+     */
+    analyzeJoinPath(cubes: Map<string, Cube>, fromCube: string, toCube: string, query?: SemanticQuery): JoinPathAnalysis;
+    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.
+     */
+    generateWarnings(query: SemanticQuery, preAggregationCTEs?: PhysicalQueryPlan['preAggregationCTEs']): QueryWarning[];
+    /**
+     * 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/logical-plan/planner-utils.d.ts

@@ -0,0 +1,20 @@
+import { Cube, SemanticQuery } from '../types/index.js';
+import { JoinPathResolver } from '../resolvers/join-path-resolver.js';
+/**
+ * Caches a JoinPathResolver per cubes map to avoid repeated instantiation.
+ * Shared by all sub-planners so a single query reuses one resolver per cubes map.
+ */
+export declare class ResolverCache {
+    private cache;
+    get(cubes: Map<string, Cube>): JoinPathResolver;
+}
+/**
+ * Analyze a semantic query to determine which cubes are involved.
+ * Scans measures, dimensions, time dimensions, filters and ORDER BY members.
+ */
+export declare function analyzeCubeUsage(query: SemanticQuery): Set<string>;
+/**
+ * Recursively extract cube names from a filter (handles logical AND/OR filters)
+ * into the provided set.
+ */
+export declare function extractCubeNamesFromFilter(filter: any, cubesUsed: Set<string>): void;

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

@@ -0,0 +1,199 @@
+import { AnyColumn, Table } from 'drizzle-orm';
+import { Cube, CubeJoin, JoinKeyInfo, PropagatingFilter, IntermediateJoinInfo, DownstreamJoinKeyInfo } from '../types/cube.js';
+import { Filter } from '../types/query.js';
+import { QueryWarning, TimeGranularity } from '../types/core.js';
+/** Reference to a registered cube */
+export interface CubeRef {
+    /** Cube name (e.g. 'Employees') */
+    name: string;
+    /** Resolved cube object */
+    cube: Cube;
+}
+/** Reference to a measure on a specific cube */
+export interface MeasureRef {
+    /** Fully qualified name: CubeName.measureName */
+    name: string;
+    /** Cube that owns this measure */
+    cube: CubeRef;
+    /** Local measure name (without cube prefix) */
+    localName: string;
+}
+/** Reference to a dimension on a specific cube */
+export interface DimensionRef {
+    /** Fully qualified name: CubeName.dimensionName */
+    name: string;
+    /** Cube that owns this dimension */
+    cube: CubeRef;
+    /** Local dimension name (without cube prefix) */
+    localName: string;
+}
+/** Reference to a time dimension with granularity/dateRange */
+export interface TimeDimensionRef {
+    /** Fully qualified dimension name */
+    name: string;
+    cube: CubeRef;
+    localName: string;
+    granularity?: TimeGranularity;
+    dateRange?: string | string[];
+    fillMissingDates?: boolean;
+    compareDateRange?: (string | [string, string])[];
+}
+/** Reference to a column for join keys */
+export interface ColumnRef {
+    column: AnyColumn;
+    alias?: string;
+}
+/** Order-by specification */
+export interface OrderByRef {
+    /** Fully qualified field name */
+    name: string;
+    direction: 'asc' | 'desc';
+}
+export interface LogicalSchema {
+    measures: MeasureRef[];
+    dimensions: DimensionRef[];
+    timeDimensions: TimeDimensionRef[];
+}
+export interface JoinRef {
+    /** Target cube being joined */
+    target: CubeRef;
+    /** Table alias in the generated SQL */
+    alias: string;
+    /** SQL join type (already resolved from the effective relationship) */
+    joinType: 'inner' | 'left' | 'right' | 'full';
+    /**
+     * Symbolic join definition. The Drizzle join condition is materialized from
+     * this by DrizzlePlanBuilder — the logical plan itself holds no SQL and no
+     * baked security context.
+     */
+    joinDef: CubeJoin;
+    /** Relationship type from the join definition */
+    relationship?: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    /**
+     * Junction table for belongsToMany relationships (symbolic).
+     * The junction join condition and security WHERE are materialized from
+     * `joinDef.through` by DrizzlePlanBuilder at physical-plan time.
+     */
+    junctionTable?: {
+        table: Table;
+        alias: string;
+        joinType: 'inner' | 'left' | 'right' | 'full';
+        sourceCubeName?: string;
+    };
+}
+/** Discriminated union tag for all node types */
+export type LogicalNodeType = 'query' | 'simpleSource' | 'fullKeyAggregate' | 'ctePreAggregate' | 'keysDeduplication' | 'multiFactMerge';
+/** Base interface shared by all logical plan nodes */
+export interface LogicalNodeBase {
+    readonly type: LogicalNodeType;
+    readonly schema: LogicalSchema;
+}
+/**
+ * Root query node — represents the outermost SELECT.
+ * Wraps a source node with dimensions, measures, filters, ordering, etc.
+ */
+export interface QueryNode extends LogicalNodeBase {
+    readonly type: 'query';
+    /** Source of rows (SimpleSource, FullKeyAggregate, etc.) */
+    source: LogicalNode;
+    /** Dimensions to group by */
+    dimensions: DimensionRef[];
+    /** Measures to aggregate */
+    measures: MeasureRef[];
+    /** User-supplied filters */
+    filters: Filter[];
+    /** Time dimensions with granularity / date range */
+    timeDimensions: TimeDimensionRef[];
+    /** ORDER BY clauses */
+    orderBy: OrderByRef[];
+    limit?: number;
+    offset?: number;
+    /** When true, skip GROUP BY (raw rows) */
+    ungrouped?: boolean;
+    /** Planning warnings surfaced to the caller */
+    warnings: QueryWarning[];
+}
+/**
+ * Simple source: one primary cube optionally joined to other cubes.
+ * This is the runtime physical-source shape used by SQL generation today.
+ */
+export interface SimpleSource extends LogicalNodeBase {
+    readonly type: 'simpleSource';
+    /** Primary cube (FROM clause) */
+    primaryCube: CubeRef;
+    /** Cubes joined to the primary */
+    joins: JoinRef[];
+    /** Pre-aggregation CTEs attached to this source */
+    ctes: CTEPreAggregate[];
+}
+/**
+ * Full key aggregate: merges results from multiple subqueries
+ * that share the same dimension key set.
+ */
+export interface FullKeyAggregate extends LogicalNodeBase {
+    readonly type: 'fullKeyAggregate';
+    /** Subqueries whose results will be merged */
+    subqueries: LogicalNode[];
+    /** Shared dimensions used as the merge key */
+    dimensions: DimensionRef[];
+}
+/**
+ * CTE pre-aggregation node.
+ * Represents a WITH clause that pre-aggregates a hasMany cube
+ * to prevent fan-out in the outer query.
+ */
+export interface CTEPreAggregate extends LogicalNodeBase {
+    readonly type: 'ctePreAggregate';
+    /** The cube being pre-aggregated */
+    cube: CubeRef;
+    /** Table alias for the cube in the main query */
+    alias: string;
+    /** CTE alias (WITH clause name) */
+    cteAlias: string;
+    /** Keys connecting CTE back to the main query */
+    joinKeys: JoinKeyInfo[];
+    /** Measure names included in this CTE */
+    measures: string[];
+    /** Cross-cube filter propagation */
+    propagatingFilters?: PropagatingFilter[];
+    /** Downstream join keys for transitive joins through this CTE */
+    downstreamJoinKeys?: DownstreamJoinKeyInfo[];
+    /** Intermediate joins absorbed into this CTE for fan-out prevention */
+    intermediateJoins?: IntermediateJoinInfo[];
+    /** CTE type (currently only 'aggregate') */
+    cteType: 'aggregate';
+    /**
+     * Reason for creating this CTE:
+     * - 'hasMany': Direct hasMany target — outer query uses SUM
+     * - 'fanOutPrevention': Affected by hasMany elsewhere — outer query uses MAX
+     */
+    cteReason: 'hasMany' | 'fanOutPrevention';
+}
+/**
+ * Keys-based deduplication for multiplied measures.
+ */
+export interface KeysDeduplication extends LogicalNodeBase {
+    readonly type: 'keysDeduplication';
+    /** SELECT DISTINCT PKs + dims */
+    keysSource: LogicalNode;
+    /** Aggregated measures source */
+    measureSource: LogicalNode;
+    /** Primary key columns to join on */
+    joinOn: ColumnRef[];
+    /** Measure names NOT from the multiplied cube (pre-aggregated in keys CTE) */
+    regularMeasures?: string[];
+}
+/**
+ * Multi-fact merge: combines independent fact subqueries
+ * that share dimensions.
+ */
+export interface MultiFactMerge extends LogicalNodeBase {
+    readonly type: 'multiFactMerge';
+    /** Independent fact subqueries */
+    groups: LogicalNode[];
+    /** Shared dimensions for the merge */
+    sharedDimensions: DimensionRef[];
+    /** How to combine the groups */
+    mergeStrategy: 'fullJoin' | 'leftJoin' | 'innerJoin';
+}
+export type LogicalNode = QueryNode | SimpleSource | FullKeyAggregate | CTEPreAggregate | KeysDeduplication | MultiFactMerge;

package/dist/server/measure-classification.d.ts

@@ -0,0 +1,40 @@
+import { Cube } from './types/index.js';
+/**
+ * Measure types that are window functions. Window functions require special
+ * handling: no GROUP BY in the CTE, no re-aggregation in the outer query, and
+ * they return individual rows rather than grouped results.
+ */
+export declare const WINDOW_FUNCTION_TYPES: readonly ["lag", "lead", "rank", "denseRank", "rowNumber", "ntile", "firstValue", "lastValue", "movingAvg", "movingSum"];
+/** Check if a measure type is a window function. */
+export declare function isWindowFunction(measureType: string): boolean;
+/**
+ * Check if a measure is a post-aggregation window function.
+ * Post-aggregation windows reference a base `measure` in their windowConfig,
+ * indicating they operate on aggregated data rather than raw rows.
+ */
+export declare function isPostAggregationWindow(measure: any): boolean;
+/**
+ * Resolve the base-measure reference for a post-aggregation window function to a
+ * fully qualified name (e.g. 'totalRevenue' -> 'Sales.totalRevenue').
+ * Returns null when the measure is not a post-aggregation window.
+ */
+export declare function getWindowBaseMeasure(measure: any, cubeName: string): string | null;
+/**
+ * Default operation for a window function type.
+ * - lag/lead default to 'difference' (compare current vs previous/next)
+ * - all others default to 'raw'
+ */
+export declare function getDefaultWindowOperation(windowType: string): 'raw' | 'difference' | 'ratio' | 'percentChange';
+/**
+ * Categorize measures for post-aggregation window-function handling.
+ * - aggregateMeasures: regular aggregates (count, sum, avg, etc.)
+ * - postAggWindowMeasures: window functions referencing a base measure
+ * - requiredBaseMeasures: base measures those windows depend on (auto-added)
+ */
+export declare function categorizeForPostAggregation(measureNames: string[], cubeMap: Map<string, Cube>): {
+    aggregateMeasures: string[];
+    postAggWindowMeasures: string[];
+    requiredBaseMeasures: Set<string>;
+};
+/** Whether any measure in the list is a post-aggregation window function. */
+export declare function hasPostAggregationWindows(measureNames: string[], cubeMap: Map<string, Cube>): boolean;

package/dist/server/{openai-B5jEiqiB.js → openai-CmVRIbUg.js}

@@ -119,7 +119,7 @@ var ce = (e, t) => {
 	} catch {
 		return;
 	}
-}, ue = (e) => new Promise((t) => setTimeout(t, e)), de = "6.42.0", fe = () => typeof window < "u" && window.document !== void 0 && typeof navigator < "u";
+}, ue = (e) => new Promise((t) => setTimeout(t, e)), de = "6.43.0", fe = () => typeof window < "u" && window.document !== void 0 && typeof navigator < "u";
 function pe() {
 	return typeof Deno < "u" && Deno.build != null ? "deno" : typeof EdgeRuntime < "u" ? "edge" : Object.prototype.toString.call(globalThis.process === void 0 ? 0 : globalThis.process) === "[object process]" ? "node" : "unknown";
 }
@@ -1399,7 +1399,10 @@ I = /* @__PURE__ */ new WeakSet(), hn = function() {
 }, _n = function() {
 	for (let e = this.messages.length - 1; e >= 0; e--) {
 		let t = this.messages[e];
-		if (Qt(t) && t?.tool_calls?.length) return t.tool_calls.filter((e) => e.type === "function").at(-1)?.function;
+		if (Qt(t) && t?.tool_calls?.length) for (let e = t.tool_calls.length - 1; e >= 0; e--) {
+			let n = t.tool_calls[e];
+			if (n?.type === "function") return n.function;
+		}
 	}
 }, vn = function() {
 	for (let e = this.messages.length - 1; e >= 0; e--) {
@@ -2080,6 +2083,12 @@ var Gn = class extends N {
 			__security: { adminAPIKeyAuth: !0 }
 		});
 	}
+	retrieve(e, t) {
+		return this._client.get(P`/organization/spend_alerts/${e}`, {
+			...t,
+			__security: { adminAPIKeyAuth: !0 }
+		});
+	}
 	update(e, t, n) {
 		return this._client.post(P`/organization/spend_alerts/${e}`, {
 			body: t,
@@ -2469,6 +2478,13 @@ var nr = class extends N {
 			__security: { adminAPIKeyAuth: !0 }
 		});
 	}
+	retrieve(e, t, n) {
+		let { project_id: r } = t;
+		return this._client.get(P`/organization/projects/${r}/spend_alerts/${e}`, {
+			...n,
+			__security: { adminAPIKeyAuth: !0 }
+		});
+	}
 	update(e, t, n) {
 		let { project_id: r, ...i } = t;
 		return this._client.post(P`/organization/projects/${r}/spend_alerts/${e}`, {

package/dist/server/{openai-cDlFSTk6.js → openai-CtXqeznO.js}

@@ -70,7 +70,7 @@ var r = class {
 		try {
 			let t = await import(
 				/* webpackIgnore: true */
-				"./openai-B5jEiqiB.js"
+				"./openai-CmVRIbUg.js"
 );
 			e = t.default || t.OpenAI || t;
 		} catch {