drizzle-cube 0.5.7 → 0.6.0

package/dist/server/server/builders/analysis-utils.d.ts

@@ -0,0 +1,106 @@
+import { SQL } from 'drizzle-orm';
+import { Cube, Filter, QueryContext } from '../types';
+/**
+ * Type for CTE objects created by db.$with()
+ * These can be used with db.with(...ctes).select().from(cte)
+ */
+export type WithSubquery = ReturnType<ReturnType<any['$with']>['as']>;
+/**
+ * Combine an array of WHERE/JOIN conditions into a single SQL expression.
+ *
+ * - `[]`            → undefined (no condition)
+ * - single element  → that element verbatim
+ * - multiple        → `and(...conditions)`
+ *
+ * Mirrors the inline `conditions.length === 1 ? conditions[0] : and(...conditions) as SQL`
+ * pattern that was duplicated across the analysis builders.
+ */
+export declare function combineWhere(conditions: SQL[]): SQL | undefined;
+/** The combinator + children of a client-style group filter. */
+export interface GroupFilterParts {
+    /** True for an AND group, false for OR. */
+    isAnd: boolean;
+    filters: Filter[];
+}
+/**
+ * Normalise a client-style group filter.
+ *
+ * The analysis UIs sometimes emit groups as `{ type: 'and' | 'or', filters: [...] }`
+ * rather than the canonical `{ and: [...] }` / `{ or: [...] }` (this shape is not part
+ * of the `Filter` type; the builders accept it defensively). Returns the group's
+ * combinator + children, or `null` if `filter` isn't a client group filter.
+ */
+export declare function asGroupFilter(filter: Filter): GroupFilterParts | null;
+/**
+ * A single multi-cube field mapping (binding key or time dimension), e.g.
+ * `{ cube: 'Events', dimension: 'Events.userId' }`.
+ */
+type FieldMapping = {
+    cube: string;
+    dimension: string;
+};
+/**
+ * The i18n namespaces whose binding-key / time-dimension leaf keys are identical.
+ * Funnel and flow share the exact same leaf keys under these two prefixes, which
+ * is what lets the resolution logic below be shared. (Retention uses a different
+ * leaf-key set — see `bindingKeyErrorsForPrefix` vs the bespoke config it passes.)
+ */
+type AnalysisErrorPrefix = 'server.errors.funnel' | 'server.errors.flow';
+/**
+ * Extract the dimension name from a `'Cube.dim'` or bare `'dim'` reference.
+ * (`'Cube.dim'` → `'dim'`, `'dim'` → `'dim'`.) Funnel/flow only ever pass the
+ * qualified form, so this is a strict superset of their old `.split('.')[1]`.
+ */
+export declare function extractDimensionName(dimension: string): string;
+/**
+ * Builders of the i18n error strings thrown while resolving a binding key.
+ * Each builder receives the resolved context so callers can preserve their exact
+ * existing message keys/params (funnel/flow and retention use different leaf keys).
+ */
+export interface BindingKeyErrors {
+    /** Array form: no mapping in the array matched the current cube. */
+    noMapping: (ctx: {
+        cubeName: string;
+    }) => string;
+    /** The cube named in the key/mapping was not found in the `cubes` registry. */
+    cubeNotFound?: (ctx: {
+        cubeName: string;
+    }) => string;
+    /** String form: the binding-key dimension was not found on the resolved cube. */
+    keyDimNotFound: (ctx: {
+        bindingKey: string;
+        cubeName: string;
+        dimName: string;
+    }) => string;
+    /** Array form: the mapped dimension was not found on the resolved cube. */
+    mappingDimNotFound: (ctx: {
+        dimension: string;
+        cubeName: string;
+        dimName: string;
+    }) => string;
+}
+/**
+ * Build the binding-key error messages for funnel/flow from their shared i18n
+ * namespace (the leaf keys are identical across the two prefixes).
+ */
+export declare function bindingKeyErrorsForPrefix(errorPrefix: AnalysisErrorPrefix): BindingKeyErrors;
+/**
+ * Resolve a binding-key SQL expression for the analysis builders.
+ *
+ * Accepts a `'Cube.dim'` string or an array of `{ cube, dimension }` mappings.
+ * `errors` supplies the i18n messages (funnel/flow share one leaf-key set via
+ * `bindingKeyErrorsForPrefix`; retention passes its own). When `cubes` is given,
+ * the dimension is resolved on the cube named in the key (retention's multi-cube
+ * semantics); otherwise it is resolved on `cube` (funnel/flow).
+ */
+export declare function resolveBindingKeyExpr(bindingKey: string | FieldMapping[], cube: Cube, context: QueryContext, errors: BindingKeyErrors, cubes?: Map<string, Cube>): SQL;
+/**
+ * Resolve a time-dimension SQL expression for funnel/flow builders.
+ *
+ * Accepts a `'Cube.dim'` string or an array of `{ cube, dimension }` mappings.
+ * `errorPrefix` selects the i18n namespace (the leaf keys are identical across
+ * funnel and flow): `<prefix>.timeDimNotFound`, `<prefix>.noTimeDimMapping`,
+ * `<prefix>.timeDimMappingNotFound`.
+ */
+export declare function resolveTimeDimensionExpr(timeDimension: string | FieldMapping[], cube: Cube, context: QueryContext, errorPrefix: AnalysisErrorPrefix): SQL;
+export {};

package/dist/server/server/builders/comparison-query-builder.d.ts

@@ -0,0 +1,70 @@
+import { SemanticQuery, TimeDimension, QueryResult, TimeGranularity } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+/**
+ * Normalized period range with start/end dates and metadata
+ */
+export interface NormalizedPeriod {
+    /** Start date of the period */
+    start: Date;
+    /** End date of the period */
+    end: Date;
+    /** Human-readable label for the period */
+    label: string;
+    /** Index in the comparison (0 = first/current, 1 = second/prior, etc.) */
+    index: number;
+}
+/**
+ * Extended result row with period metadata for alignment
+ */
+export interface ComparisonResultRow extends Record<string, unknown> {
+    /** Period label (e.g., "2024-01-01 - 2024-01-31") */
+    __period: string;
+    /** Period index (0 = current, 1 = prior, etc.) */
+    __periodIndex: number;
+    /** Day-of-period index for alignment in overlay mode */
+    __periodDayIndex: number;
+}
+export declare class ComparisonQueryBuilder {
+    private dateTimeBuilder;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if a query contains compareDateRange
+     */
+    hasComparison(query: SemanticQuery): boolean;
+    /**
+     * Get the time dimension with compareDateRange
+     */
+    getComparisonTimeDimension(query: SemanticQuery): TimeDimension | undefined;
+    /**
+     * Normalize compareDateRange entries to concrete date ranges
+     * Handles both relative strings ('last 30 days') and explicit arrays (['2024-01-01', '2024-01-31'])
+     */
+    normalizePeriods(compareDateRange: (string | [string, string])[]): NormalizedPeriod[];
+    /**
+     * Create sub-query for a specific period
+     * Replaces compareDateRange with a concrete dateRange for that period
+     */
+    createPeriodQuery(query: SemanticQuery, period: NormalizedPeriod): SemanticQuery;
+    /**
+     * Calculate the day-of-period index for a date
+     * Used for aligning data points across periods in overlay mode
+     */
+    calculatePeriodDayIndex(date: Date | string, periodStart: Date, granularity: TimeGranularity): number;
+    /**
+     * Add period metadata to result rows
+     */
+    addPeriodMetadata(data: Record<string, unknown>[], period: NormalizedPeriod, timeDimensionKey: string, granularity: TimeGranularity): ComparisonResultRow[];
+    /**
+     * Merge results from multiple period queries
+     * Adds period metadata and creates combined result with annotation
+     */
+    mergeComparisonResults(periodResults: Array<{
+        result: QueryResult;
+        period: NormalizedPeriod;
+    }>, timeDimension: TimeDimension, granularity: TimeGranularity): QueryResult;
+    /**
+     * Sort merged results by period index and then by time dimension
+     * Ensures consistent ordering for client-side processing
+     */
+    sortComparisonResults(data: ComparisonResultRow[], timeDimensionKey: string): ComparisonResultRow[];
+}

package/dist/server/server/builders/cte-builder.d.ts

@@ -0,0 +1,108 @@
+import { SQL } from 'drizzle-orm';
+import { SemanticQuery, QueryContext, PhysicalQueryPlan, PropagatingFilter } from '../types';
+import { DrizzleSqlBuilder } from '../physical-plan/drizzle-sql-builder';
+/**
+ * CTE information type extracted from runtime physical plan context
+ */
+export type CTEInfo = NonNullable<PhysicalQueryPlan['preAggregationCTEs']>[0];
+/**
+ * CTEBuilder handles the construction of Common Table Expressions
+ * for pre-aggregation in hasMany relationship queries.
+ *
+ * This enables efficient aggregation of "many" side data before joining,
+ * preventing the Cartesian product explosion that would occur with direct JOINs.
+ */
+export declare class CTEBuilder {
+    private queryBuilder;
+    constructor(queryBuilder: DrizzleSqlBuilder);
+    /**
+     * Build pre-aggregation CTE for hasMany relationships
+     *
+     * Creates a CTE that:
+     * 1. Selects join keys and aggregated measures
+     * 2. Applies security context filtering
+     * 3. Groups by join keys and requested dimensions
+     * 4. Handles propagating filters from related cubes
+     * 5. Handles multi-hop join paths by absorbing intermediate tables (fan-out prevention)
+     */
+    buildPreAggregationCTE(cteInfo: CTEInfo, query: SemanticQuery, context: QueryContext, queryPlan: PhysicalQueryPlan, preBuiltFilterMap?: Map<string, SQL[]>): any;
+    /**
+     * Build the SELECT map for a pre-aggregation CTE: join keys (or the
+     * intermediate primary-connected column), downstream join keys, aggregated
+     * measures, and requested dimensions / time dimensions from this cube.
+     */
+    private buildCTESelections;
+    /** Add join-key columns (or the intermediate primary-connected column) to the CTE SELECT. */
+    private addJoinKeySelections;
+    /** Add downstream join-key columns so downstream cubes can be joined through this CTE. */
+    private addDownstreamKeySelections;
+    /** Add aggregated measure expressions to the CTE SELECT. */
+    private addMeasureSelections;
+    /** Add requested dimensions and time dimensions (from this cube) to the CTE SELECT. */
+    private addDimensionSelections;
+    /**
+     * Add JOINs to intermediate tables inside the CTE (multi-hop fan-out
+     * prevention). Joins from CTE-nearest to primary-nearest so each ON clause
+     * only references tables already in scope.
+     */
+    private applyIntermediateJoins;
+    /**
+     * Assemble the full WHERE condition list for a pre-aggregation CTE: security
+     * context, regular dimension filters, time-dimension date filters, and
+     * propagating filters from related cubes.
+     *
+     * IMPORTANT: Only dimension filters are applied here; measure filters belong
+     * in the main query's HAVING clause.
+     */
+    private buildCTEWhereConditions;
+    /**
+     * Build the time-dimension date filters (from `timeDimensions.dateRange` and
+     * `inDateRange` simple filters) plus propagating-filter subqueries for a CTE.
+     */
+    private buildCTETimeFilters;
+    /**
+     * Build the GROUP BY fields for a pre-aggregation CTE: join keys (or the
+     * intermediate primary-connected column), downstream join keys, and requested
+     * dimensions / time dimensions. De-dupes named columns.
+     */
+    private buildCTEGroupByFields;
+    /**
+     * Add join keys (and downstream join keys) to the CTE GROUP BY via the de-dupe
+     * callback. For multi-hop paths uses the intermediate table's
+     * primary-connected column (e.g. employees.department_id).
+     */
+    private addJoinKeyGroupBy;
+    /**
+     * Build join condition for CTE
+     *
+     * Creates the ON clause for joining a CTE to the main query.
+     * Uses stored column objects for type-safe joins.
+     *
+     * For multi-hop paths with intermediate joins:
+     * - The CTE includes columns from intermediate tables
+     * - The join condition uses the intermediate's primary-connected column
+     * - Example: departments.id = employeeteams_agg.department_id (not employee_id!)
+     */
+    buildCTEJoinCondition(joinCube: PhysicalQueryPlan['joinCubes'][0], cteAlias: string, queryPlan: PhysicalQueryPlan): SQL;
+    /**
+     * Resolve source-side join expression for CTE joins.
+     *
+     * When two cubes are both materialized as CTEs in the same query, join keys can
+     * still point to the original table column object (e.g. departments.id). In that
+     * case the table is no longer present in FROM/JOIN, so rewrite to the upstream CTE
+     * alias column (e.g. departments_agg.id).
+     */
+    private resolveCTEJoinSourceColumn;
+    /**
+     * Build a subquery filter for propagating filters from related cubes.
+     *
+     * This generates: cteCube.FK IN (SELECT sourceCube.PK FROM sourceCube WHERE filters...)
+     *
+     * Example: For Productivity CTE with Employees.createdAt filter:
+     * employee_id IN (SELECT id FROM employees WHERE organisation_id = $1 AND created_at >= $date)
+     *
+     * For composite keys, uses EXISTS instead of IN for better database compatibility:
+     * EXISTS (SELECT 1 FROM source WHERE source.pk1 = cte.fk1 AND source.pk2 = cte.fk2 AND <filters>)
+     */
+    buildPropagatingFilterSubquery(propFilter: PropagatingFilter, context: QueryContext): SQL | null;
+}

package/dist/server/server/builders/date-time-builder.d.ts

@@ -0,0 +1,34 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { QueryContext } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+export declare class DateTimeBuilder {
+    private databaseAdapter;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Build time dimension expression with granularity using database adapter
+     */
+    buildTimeDimensionExpression(dimensionSql: any, granularity: string | undefined, context: QueryContext): SQL;
+    /**
+     * Build date range condition for time dimensions
+     */
+    buildDateRangeCondition(fieldExpr: AnyColumn | SQL, dateRange: string | string[]): SQL | null;
+    private rangeBetween;
+    /** Shift a normalized end value to end-of-day when its source was a date-only string. */
+    private endOfDayValue;
+    private buildArrayDateRangeCondition;
+    private buildStringDateRangeCondition;
+    /**
+     * Parse relative date range expressions like "today", "yesterday", "last 7 days", "this month", etc.
+     * Handles all 14 DATE_RANGE_OPTIONS from the client
+     */
+    parseRelativeDateRange(dateRange: string): {
+        start: Date;
+        end: Date;
+    } | null;
+    /**
+     * Normalize date values to handle strings, numbers, and Date objects
+     * Returns ISO string for PostgreSQL/MySQL, Unix timestamp for SQLite, or null
+     * Ensures dates are in the correct format for each database engine
+     */
+    normalizeDate(value: any): string | number | null;
+}

package/dist/server/server/builders/date-time-helpers.d.ts

@@ -0,0 +1,34 @@
+import { DatabaseAdapter } from '../adapters/base-adapter';
+/**
+ * Convert a millisecond epoch to the engine's wire format:
+ * - SQLite: Unix seconds (integer)
+ * - other integer-timestamp engines: Unix milliseconds (integer)
+ * - PostgreSQL/MySQL: ISO string
+ */
+export declare function epochMsToEngineValue(databaseAdapter: DatabaseAdapter, timeMs: number): string | number;
+/**
+ * Convert a Date to the engine's wire format (see epochMsToEngineValue).
+ */
+export declare function dateToEngineValue(databaseAdapter: DatabaseAdapter, date: Date): string | number;
+/**
+ * Reconstruct a Date from a normalized value (the output of normalizeDate):
+ * a SQLite Unix-seconds integer, a millisecond integer, or an ISO string.
+ */
+export declare function engineValueToDate(databaseAdapter: DatabaseAdapter, value: string | number): Date;
+/** Detect a date-only string (YYYY-MM-DD). */
+export declare function isDateOnlyString(value: unknown): value is string;
+/**
+ * Normalize a date value to the engine's wire format, or null when falsy or
+ * unparseable.
+ */
+export declare function normalizeDateValue(databaseAdapter: DatabaseAdapter, value: any): string | number | null;
+type DateRange = {
+    start: Date;
+    end: Date;
+};
+/**
+ * Parse relative date range expressions like "today", "yesterday",
+ * "last 7 days", "this month", etc. Handles all 14 DATE_RANGE_OPTIONS.
+ */
+export declare function parseRelativeDateRangeValue(dateRange: string): DateRange | null;
+export {};

package/dist/server/server/builders/filter-builder.d.ts

@@ -0,0 +1,25 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { FilterOperator, Filter, Cube, QueryContext } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { DateTimeBuilder } from './date-time-builder';
+export declare class FilterBuilder {
+    private databaseAdapter;
+    private dateTimeBuilder;
+    constructor(databaseAdapter: DatabaseAdapter, dateTimeBuilder: DateTimeBuilder);
+    /**
+     * Build filter condition using Drizzle operators
+     */
+    buildFilterCondition(fieldExpr: AnyColumn | SQL, operator: FilterOperator, values: any[], field?: any, dateRange?: string | string[]): SQL | null;
+    /**
+     * Build a logical filter (AND/OR) - used by executor for cache preloading
+     * This handles nested filter structures and builds combined SQL
+     */
+    buildLogicalFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
+    /** Build + AND/OR-combine a list of sub-filters, collapsing the 0- and 1-element cases. */
+    private combineFilters;
+    /**
+     * Build SQL for a single filter condition (simple or logical)
+     * Used for cache preloading to build filters independently of query context
+     */
+    buildSingleFilter(filter: Filter, cubes: Map<string, Cube>, context: QueryContext): SQL | null;
+}

package/dist/server/server/builders/filter-operators.d.ts

@@ -0,0 +1,23 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { FilterOperator } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { DateTimeBuilder } from './date-time-builder';
+/**
+ * Context passed to every operator handler. Carries the resolved field
+ * expression, the (already filtered/converted) value list, plus the
+ * collaborators a handler may need.
+ */
+export interface FilterOperatorContext {
+    fieldExpr: AnyColumn | SQL;
+    values: any[];
+    filteredValues: any[];
+    value: any;
+    field?: any;
+    databaseAdapter: DatabaseAdapter;
+    dateTimeBuilder: DateTimeBuilder;
+}
+/**
+ * Dispatch a single filter operator to its handler. Returns null for any
+ * unknown operator (matching the original `default` case).
+ */
+export declare function applyFilterOperator(operator: FilterOperator, ctx: FilterOperatorContext): SQL | null;

package/dist/server/server/builders/flow-query-builder.d.ts

@@ -0,0 +1,136 @@
+import { DatabaseAdapter } from '../adapters/base-adapter';
+import { FlowQueryConfig, FlowResultRow } from '../types/flow';
+import { AnalysisConfigValidationResult } from '../types/validation';
+import { Cube, QueryContext, SemanticQuery } from '../types';
+export declare class FlowQueryBuilder {
+    private filterBuilder;
+    private dateTimeBuilder;
+    private databaseAdapter;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Check if query contains flow configuration
+     */
+    hasFlow(query: SemanticQuery): boolean;
+    /**
+     * Validate flow configuration
+     */
+    validateConfig(config: FlowQueryConfig, cubes: Map<string, Cube>): AnalysisConfigValidationResult;
+    /**
+     * Validate a `Cube.dimension` member string: format, cube existence, and
+     * dimension existence. i18n message factories let each call site supply its
+     * own keys while sharing the branch structure.
+     */
+    private validateMemberDimension;
+    /** Validate the flow binding key (single member or per-cube mappings). */
+    private validateBindingKey;
+    /** Validate the flow starting step (required + filter + name warning). */
+    private validateStartingStep;
+    /** Validate flow step-depth bounds and emit high-depth performance warnings. */
+    private validateDepthBounds;
+    /** Validate the flow join strategy and its engine support. */
+    private validateJoinStrategy;
+    /**
+     * Build complete flow query using Drizzle's query builder pattern
+     *
+     * Creates a series of CTEs to:
+     * 1. Find entities at the starting step
+     * 2. Walk backwards N steps to find preceding events
+     * 3. Walk forwards N steps to find following events
+     * 4. Aggregate into nodes and links for Sankey visualization
+     */
+    buildFlowQuery(config: FlowQueryConfig, cubes: Map<string, Cube>, context: QueryContext): ReturnType<typeof context.db.select>;
+    /**
+     * Transform raw SQL result to FlowResultRow
+     * The raw result contains rows with record_type = 'node' or 'link'
+     */
+    transformResult(rawResult: Record<string, unknown>[]): FlowResultRow;
+    /**
+     * Resolve flow configuration to SQL expressions
+     */
+    private resolveFlowConfig;
+    /**
+     * Resolve the cube for flow analysis
+     */
+    private resolveCube;
+    /**
+     * Resolve binding key expression
+     */
+    private resolveBindingKey;
+    /**
+     * Resolve time dimension expression
+     */
+    private resolveTimeDimension;
+    /**
+     * Resolve event dimension expression
+     */
+    private resolveEventDimension;
+    /**
+     * Build filter conditions for the starting step
+     */
+    private buildStartingStepFilters;
+    /**
+     * Build a single filter condition
+     */
+    private buildFilterCondition;
+    /** Build the non-null sub-conditions of a logical/group filter. */
+    private buildSubConditions;
+    /** Combine sub-conditions with AND/OR, collapsing the 0- and 1-element cases. */
+    private combineConditions;
+    /**
+     * Build the starting entities CTE
+     * Finds all entities matching the starting step filter with their start time and event type
+     * For sunburst mode, also initializes event_path with the starting event type
+     */
+    private buildStartingEntitiesCTE;
+    /**
+     * Build CTEs for steps BEFORE/AFTER the starting point using LATERAL joins
+     *
+     * Direction-parameterised: 'before' walks backwards (time `<` reference,
+     * ORDER BY DESC, `before_step_N` aliases, bounded by `stepsBefore`); 'after'
+     * walks forwards (time `>`, ORDER BY ASC, `after_step_N`, `stepsAfter`).
+     * Uses ORDER BY ... LIMIT 1 to fetch the immediate predecessor/successor via index.
+     */
+    private buildDirectionalCTEsLateral;
+    /**
+     * Build CTEs for steps BEFORE/AFTER the starting point using ROW_NUMBER()
+     *
+     * Direction-parameterised: 'before' finds the immediate predecessor (time `<`
+     * reference, ROW_NUMBER ORDER BY DESC, `before_step_N` aliases, bounded by
+     * `stepsBefore`); 'after' finds the immediate successor (time `>`, ORDER BY ASC,
+     * `after_step_N`, `stepsAfter`). For sunburst mode, accumulates event_path
+     * (prepend for before, append for after).
+     */
+    private buildDirectionalCTEsWindow;
+    /**
+     * Build a single node-aggregation UNION arm for a before/after step.
+     *
+     * Sankey groups by `event_type` (converging paths); sunburst groups by
+     * `event_path` (unique tree branches). The node-id prefix and layer are
+     * emitted via sql.raw() because they're hardcoded constants (not user input)
+     * and avoid multi-digit parameter issues in DuckDB.
+     */
+    private buildNodeArm;
+    /**
+     * Build a single link-aggregation UNION arm between two adjacent step CTEs
+     * (before→before or after→after). Sankey keys transitions on `event_type`,
+     * sunburst on `event_path`. Source/target id prefixes are sql.raw() constants.
+     */
+    private buildAdjacentLinkArm;
+    /**
+     * Build the nodes aggregation CTE
+     * Aggregates counts per (layer, event_type) combination using UNION ALL
+     * For sunburst mode, aggregates by event_path for unique tree branches
+     */
+    private buildNodesAggregationCTE;
+    /**
+     * Build the links aggregation CTE
+     * Counts transitions between adjacent layers
+     * For sunburst mode, uses event_path for unique branch identification
+     */
+    private buildLinksAggregationCTE;
+    /**
+     * Build the final result CTE
+     * Combines nodes and links into a single result set with record_type discriminator
+     */
+    private buildFinalResultCTE;
+}