drizzle-cube 0.5.6 → 0.5.8

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

@@ -0,0 +1,143 @@
+import { Filter } from './query';
+/**
+ * Flow query configuration for server-side execution
+ * This is the configuration extracted from SemanticQuery.flow
+ */
+export interface FlowQueryConfig {
+    /**
+     * Binding key that identifies individual entities (e.g., userId)
+     * Can be a single string like 'Events.userId' or array for multi-cube
+     */
+    bindingKey: string | {
+        cube: string;
+        dimension: string;
+    }[];
+    /**
+     * Time dimension used for ordering events
+     * Can be a single string like 'Events.timestamp' or array for multi-cube
+     */
+    timeDimension: string | {
+        cube: string;
+        dimension: string;
+    }[];
+    /**
+     * The starting step from which we explore paths
+     * Defines the anchor point for bidirectional flow analysis
+     */
+    startingStep: {
+        /** Display name for the starting step */
+        name: string;
+        /** Filter(s) that identify events for this starting step */
+        filter?: Filter | Filter[];
+    };
+    /** Number of steps to explore BEFORE the starting step (0-5) */
+    stepsBefore: number;
+    /** Number of steps to explore AFTER the starting step (0-5) */
+    stepsAfter: number;
+    /**
+     * Event dimension that categorizes events (e.g., 'Events.eventType')
+     * This dimension's values become the node labels in the Sankey diagram
+     */
+    eventDimension: string;
+    /**
+     * Optional limit on the number of entities to process
+     * Useful for performance on large datasets
+     */
+    entityLimit?: number;
+    /**
+     * Output mode for flow data aggregation
+     * - 'sankey': Aggregate by (layer, event_type) - standard flow visualization where paths can converge
+     * - 'sunburst': Path-qualified nodes for hierarchical tree visualization where each path is unique
+     * @default 'sankey'
+     */
+    outputMode?: 'sankey' | 'sunburst';
+    /**
+     * Join strategy for fetching before/after steps
+     * - 'auto' (default): Use lateral when supported, otherwise window
+     * - 'lateral': Force lateral joins (error if not supported)
+     * - 'window': Force window-function strategy
+     */
+    joinStrategy?: 'auto' | 'lateral' | 'window';
+}
+/**
+ * A node in the Sankey diagram
+ * Represents an event type at a specific layer (distance from starting step)
+ */
+export interface SankeyNode {
+    /**
+     * Unique identifier for this node
+     * Format: "before_{depth}_{eventType}" or "after_{depth}_{eventType}" or "start_{eventType}"
+     */
+    id: string;
+    /** Display name (typically the event type value) */
+    name: string;
+    /**
+     * Layer position in the Sankey diagram
+     * Negative for steps before starting step, 0 for starting step, positive for after
+     */
+    layer: number;
+    /** Total count of entities passing through this node */
+    value?: number;
+}
+/**
+ * A link (edge) in the Sankey diagram
+ * Represents a transition between two nodes
+ */
+export interface SankeyLink {
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Count of entities that follow this path */
+    value: number;
+}
+/**
+ * Flow result row returned from query execution
+ * Contains the complete Sankey diagram data
+ */
+export interface FlowResultRow {
+    nodes: SankeyNode[];
+    links: SankeyLink[];
+}
+/**
+ * Internal representation of a resolved step during query building
+ */
+export interface ResolvedFlowStep {
+    /** Layer index (-N to +N, 0 is starting step) */
+    layer: number;
+    /** Direction from starting step */
+    direction: 'before' | 'start' | 'after';
+    /** Depth from starting step (0 for start, 1+ for before/after) */
+    depth: number;
+}
+/**
+ * Raw aggregation row from the flow CTEs
+ * Before transformation to SankeyNode/SankeyLink format
+ */
+export interface RawFlowNodeRow {
+    node_id: string;
+    event_type: string;
+    layer: number;
+    count: number;
+}
+/**
+ * Raw link row from the flow CTEs
+ * Before transformation to SankeyLink format
+ */
+export interface RawFlowLinkRow {
+    source_id: string;
+    target_id: string;
+    count: number;
+}
+/**
+ * Flow validation result
+ */
+export interface FlowValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/** Minimum number of steps before/after */
+export declare const FLOW_MIN_DEPTH = 0;
+/** Maximum number of steps before/after */
+export declare const FLOW_MAX_DEPTH = 5;

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

@@ -0,0 +1,118 @@
+import { Filter } from './query';
+/**
+ * Single-cube step definition - all steps use the same cube
+ */
+export interface FunnelStepSingleCube {
+    /** Step display name */
+    name: string;
+    /** Filter conditions for this step */
+    filter?: Filter | Filter[];
+    /**
+     * Time window constraint - max duration from previous step.
+     * Format: ISO 8601 duration (e.g., "P7D" for 7 days, "PT1H" for 1 hour)
+     */
+    timeToConvert?: string;
+}
+/**
+ * Multi-cube step definition - steps can use different cubes
+ */
+export interface FunnelStepMultiCube extends FunnelStepSingleCube {
+    /** Which cube this step uses */
+    cube: string;
+}
+export type FunnelStep = FunnelStepSingleCube | FunnelStepMultiCube;
+/**
+ * Binding key mapping for multi-cube funnels
+ * Maps the user/entity identifier across different cubes
+ */
+export interface FunnelBindingKeyMapping {
+    cube: string;
+    dimension: string;
+}
+/**
+ * Time dimension mapping for multi-cube funnels
+ * Maps the timestamp field across different cubes
+ */
+export interface FunnelTimeDimensionMapping {
+    cube: string;
+    dimension: string;
+}
+/**
+ * Funnel query configuration
+ */
+export interface FunnelQueryConfig {
+    /**
+     * Binding key - dimension that links entities across steps.
+     * This is typically a user ID, session ID, or other entity identifier.
+     * String for single-cube (e.g., 'Events.userId'),
+     * Array for multi-cube with different column names per cube.
+     */
+    bindingKey: string | FunnelBindingKeyMapping[];
+    /**
+     * Time dimension for temporal ordering.
+     * Used to determine event order and calculate time-to-convert.
+     * String for single-cube (e.g., 'Events.timestamp'),
+     * Array for multi-cube with different timestamp columns per cube.
+     */
+    timeDimension: string | FunnelTimeDimensionMapping[];
+    /** Ordered array of funnel steps (minimum 2) */
+    steps: FunnelStep[];
+    /** Include time-to-convert metrics in results (default: false) */
+    includeTimeMetrics?: boolean;
+    /**
+     * Global time window - all steps must complete within this duration
+     * from the first step. Format: ISO 8601 duration.
+     */
+    globalTimeWindow?: string;
+}
+/**
+ * Result row for funnel query
+ */
+export interface FunnelResultRow {
+    /** Step name */
+    step: string;
+    /** Step position (0-indexed) */
+    stepIndex: number;
+    /** Count of entities that reached this step */
+    count: number;
+    /**
+     * Step-to-step conversion rate (count / previous step count).
+     * null for first step.
+     */
+    conversionRate: number | null;
+    /**
+     * Cumulative conversion rate from first step (count / first step count).
+     */
+    cumulativeConversionRate: number;
+    /** Average time to reach this step from previous step (seconds) */
+    avgSecondsToConvert?: number | null;
+    /** Median time to reach this step from previous step (seconds) */
+    medianSecondsToConvert?: number | null;
+    /** 90th percentile time to reach this step (seconds) */
+    p90SecondsToConvert?: number | null;
+    /** Minimum time to reach this step (seconds) */
+    minSecondsToConvert?: number | null;
+    /** Maximum time to reach this step (seconds) */
+    maxSecondsToConvert?: number | null;
+}
+/**
+ * Funnel capabilities per database engine
+ */
+export interface FunnelCapabilities {
+    /** Whether database supports PERCENTILE_CONT */
+    supportsPercentile: boolean;
+    /** Whether database supports INTERVAL arithmetic directly */
+    supportsIntervalArithmetic: boolean;
+}
+/**
+ * Type guard for multi-cube step
+ */
+export declare function isMultiCubeStep(step: FunnelStep): step is FunnelStepMultiCube;
+/**
+ * Type guard for multi-cube binding key
+ */
+export declare function isMultiCubeBindingKey(bindingKey: string | FunnelBindingKeyMapping[]): bindingKey is FunnelBindingKeyMapping[];
+/**
+ * Type guard for multi-cube time dimension
+ */
+export declare function isMultiCubeTimeDimension(timeDimension: string | FunnelTimeDimensionMapping[]): timeDimension is FunnelTimeDimensionMapping[];

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

@@ -0,0 +1,11 @@
+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';

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

@@ -0,0 +1,113 @@
+import { MeasureType, MeasureFormat, DimensionFormat, TimeGranularity } from './core';
+/**
+ * Cube relationship metadata for ERD visualization
+ */
+export interface CubeRelationshipMetadata {
+    targetCube: string;
+    relationship: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    joinFields: Array<{
+        sourceField: string;
+        targetField: string;
+    }>;
+}
+/**
+ * Cube metadata for API responses
+ */
+export interface CubeMetadata {
+    name: string;
+    title: string;
+    description?: string;
+    /**
+     * Example questions that can be answered using this cube
+     * Used by AI agents to understand cube capabilities
+     */
+    exampleQuestions?: string[];
+    measures: MeasureMetadata[];
+    dimensions: DimensionMetadata[];
+    segments: any[];
+    relationships?: CubeRelationshipMetadata[];
+    /**
+     * Hierarchies for structured drill-down paths
+     * Enables navigation through dimension levels (e.g., country -> region -> city)
+     */
+    hierarchies?: HierarchyMetadata[];
+    /** Additional cube metadata (e.g., eventStream configuration for funnel queries) */
+    meta?: Record<string, any>;
+}
+/**
+ * Measure metadata for API responses
+ */
+export interface MeasureMetadata {
+    name: string;
+    title: string;
+    shortTitle: string;
+    type: MeasureType;
+    format?: MeasureFormat;
+    description?: string;
+    /**
+     * Alternative names for this measure
+     * Used by AI agents for natural language matching
+     */
+    synonyms?: string[];
+    /**
+     * Dimension names shown when drilling into this measure
+     * Full names like "CubeName.dimensionName" for cross-cube support
+     * If not specified, drilling is disabled for this measure
+     */
+    drillMembers?: string[];
+}
+/**
+ * Dimension metadata for API responses
+ */
+export interface DimensionMetadata {
+    name: string;
+    title: string;
+    shortTitle: string;
+    type: string;
+    format?: DimensionFormat;
+    description?: string;
+    /**
+     * Alternative names for this dimension
+     * Used by AI agents for natural language matching
+     */
+    synonyms?: string[];
+    /**
+     * Supported granularities for time dimensions
+     * Only present when type is 'time'
+     * Used for time-based drill-down (year -> quarter -> month -> week -> day)
+     */
+    granularities?: TimeGranularity[];
+}
+/**
+ * Hierarchy metadata for structured drill-down paths
+ */
+export interface HierarchyMetadata {
+    /** Unique identifier for the hierarchy */
+    name: string;
+    /** Display title for the hierarchy */
+    title: string;
+    /** Cube name this hierarchy belongs to */
+    cubeName: string;
+    /**
+     * Full dimension names in order from least to most granular
+     * Format: "CubeName.dimensionName"
+     */
+    levels: string[];
+}
+/**
+ * Pre-aggregation configuration
+ */
+export interface SemanticPreAggregation {
+    name: string;
+    measures: string[];
+    dimensions: string[];
+    timeDimension?: {
+        dimension: string;
+        granularity: TimeGranularity[];
+    };
+    refreshKey?: {
+        every: string;
+        sql?: string;
+    };
+    indexes?: Record<string, string[]>;
+}

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

@@ -0,0 +1,153 @@
+import { TimeGranularity } from './core';
+import { FunnelQueryConfig } from './funnel';
+import { FlowQueryConfig } from './flow';
+import { RetentionQueryConfig } from './retention';
+/**
+ * Semantic query structure (Cube.js compatible)
+ */
+export interface SemanticQuery {
+    measures?: string[];
+    dimensions?: string[];
+    filters?: Array<Filter>;
+    timeDimensions?: Array<TimeDimension>;
+    limit?: number;
+    offset?: number;
+    order?: Record<string, 'asc' | 'desc'>;
+    /**
+     * Default value to fill missing time series gaps with.
+     * Used when fillMissingDates is enabled on time dimensions.
+     * Default: 0
+     */
+    fillMissingDatesValue?: number | null;
+    /**
+     * When true, returns raw row-level data without GROUP BY or aggregation.
+     * Measures are rendered as raw column expressions (no aggregation wrappers).
+     * Security context and joins still apply normally.
+     *
+     * Constraints:
+     * - Requires at least one dimension
+     * - Only compatible with sum, avg, min, max, and number measure types
+     * - Incompatible with count, countDistinct, calculated, and window function measures
+     * - Incompatible with measure filters, hasMany joins, funnel/flow/retention modes
+     * - Incompatible with compareDateRange and fillMissingDates
+     */
+    ungrouped?: boolean;
+    /**
+     * Funnel analysis configuration for query-time funnel definition.
+     * When specified, the query executes as a funnel analysis instead of
+     * standard measures/dimensions aggregation.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   funnel: {
+     *     bindingKey: 'Events.userId',
+     *     timeDimension: 'Events.timestamp',
+     *     steps: [
+     *       { name: 'Signup', filter: { member: 'Events.eventType', operator: 'equals', values: ['signup'] } },
+     *       { name: 'Activation', filter: { member: 'Events.eventType', operator: 'equals', values: ['activation'] }, timeToConvert: 'P7D' }
+     *     ]
+     *   }
+     * }
+     * ```
+     */
+    funnel?: FunnelQueryConfig;
+    /**
+     * Flow analysis configuration for bidirectional path exploration.
+     * When specified, the query executes as a flow analysis instead of
+     * standard measures/dimensions aggregation.
+     *
+     * Flow analysis explores paths BEFORE and AFTER a defined starting step,
+     * producing Sankey diagram data (nodes and links).
+     *
+     * @example
+     * ```typescript
+     * {
+     *   flow: {
+     *     bindingKey: 'Events.userId',
+     *     timeDimension: 'Events.timestamp',
+     *     eventDimension: 'Events.eventType',
+     *     startingStep: {
+     *       name: 'Purchase',
+     *       filter: { member: 'Events.eventType', operator: 'equals', values: ['purchase'] }
+     *     },
+     *     stepsBefore: 3,
+     *     stepsAfter: 2
+     *   }
+     * }
+     * ```
+     */
+    flow?: FlowQueryConfig;
+    /**
+     * Retention analysis configuration for cohort-based retention tracking.
+     * When specified, the query executes as a retention analysis instead of
+     * standard measures/dimensions aggregation.
+     *
+     * Retention analysis tracks what percentage of users from each cohort
+     * return in subsequent time periods.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   retention: {
+     *     timeDimension: 'Events.timestamp',
+     *     bindingKey: 'Events.userId',
+     *     dateRange: { start: '2024-01-01', end: '2024-12-31' },
+     *     granularity: 'week',
+     *     periods: 12,
+     *     retentionType: 'classic',
+     *     breakdownDimensions: ['Events.country', 'Events.plan']
+     *   }
+     * }
+     * ```
+     */
+    retention?: RetentionQueryConfig;
+}
+/**
+ * Filter definitions with logical operators
+ */
+export type Filter = FilterCondition | LogicalFilter;
+export interface FilterCondition {
+    member: string;
+    operator: FilterOperator;
+    values: any[];
+    dateRange?: string | string[];
+}
+export interface LogicalFilter {
+    and?: Filter[];
+    or?: Filter[];
+}
+/**
+ * Time dimension with granularity
+ */
+export interface TimeDimension {
+    dimension: string;
+    granularity?: TimeGranularity;
+    dateRange?: string | string[];
+    /**
+     * Fill missing dates in time series with the fill value.
+     * Requires both granularity and dateRange to be set.
+     * Default: true (enabled)
+     */
+    fillMissingDates?: boolean;
+    /**
+     * Array of date ranges for period-over-period comparison.
+     * When specified, queries are executed for each period and results are merged
+     * with period metadata (__periodIndex, __periodDayIndex) for alignment.
+     *
+     * Each range can be:
+     * - A relative string: 'this week', 'last month', 'last 30 days'
+     * - A tuple: ['2024-01-01', '2024-01-31']
+     *
+     * @example
+     * compareDateRange: [
+     *   'last 30 days',                    // Current period
+     *   ['2024-01-01', '2024-01-30']       // Prior period to compare
+     * ]
+     */
+    compareDateRange?: (string | [string, string])[];
+}
+/**
+ * Supported filter operators
+ */
+export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'notStartsWith' | 'endsWith' | 'notEndsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'set' | 'notSet' | 'inDateRange' | 'beforeDate' | 'afterDate' | 'between' | 'notBetween' | 'in' | 'notIn' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex' | 'isEmpty' | 'isNotEmpty' | 'arrayContains' | 'arrayOverlaps' | 'arrayContained';

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

@@ -0,0 +1,141 @@
+import { Filter } from './query';
+/**
+ * Binding key mapping for multi-cube retention
+ * Maps the user/entity identifier across cohort and activity cubes
+ */
+export interface RetentionBindingKeyMapping {
+    cube: string;
+    dimension: string;
+}
+/**
+ * Time dimension mapping for multi-cube retention
+ * Maps the timestamp field across different cubes
+ */
+export interface RetentionTimeDimensionMapping {
+    cube: string;
+    dimension: string;
+}
+/**
+ * Date range for cohort analysis
+ */
+export interface RetentionDateRange {
+    /** Start date (inclusive), ISO 8601 format (YYYY-MM-DD) */
+    start: string;
+    /** End date (inclusive), ISO 8601 format (YYYY-MM-DD) */
+    end: string;
+}
+/**
+ * Retention query configuration (Simplified Mixpanel-style format)
+ *
+ * Key simplifications from previous version:
+ * - Single timeDimension for both cohort entry and activity
+ * - Single granularity for viewing periods (no separate cohort/period granularity)
+ * - Single cohort (date range defines the cohort) with optional breakdown
+ */
+export interface RetentionQueryConfig {
+    /**
+     * Single timestamp dimension for the analysis.
+     * String for single-cube (e.g., 'Events.timestamp'),
+     * Object for multi-cube with explicit cube reference.
+     */
+    timeDimension: string | RetentionTimeDimensionMapping;
+    /**
+     * Binding key - dimension that links users across events.
+     * This is typically a user ID or other entity identifier.
+     * String for single-cube (e.g., 'Events.userId'),
+     * Array for multi-cube with different column names per cube.
+     */
+    bindingKey: string | RetentionBindingKeyMapping[];
+    /**
+     * Date range for cohort analysis (REQUIRED).
+     * Users who first performed the cohort action within this range are included.
+     */
+    dateRange: RetentionDateRange;
+    /**
+     * Granularity for viewing retention periods.
+     * Determines how period_number is calculated (day/week/month).
+     */
+    granularity: 'day' | 'week' | 'month';
+    /**
+     * Number of periods to calculate (e.g., 12 for 12 weeks).
+     * Period 0 is always the cohort entry period.
+     */
+    periods: number;
+    /**
+     * Retention type:
+     * - 'classic': User returned exactly in period N (bounded)
+     * - 'rolling': User returned in period N or any later period (unbounded)
+     */
+    retentionType: 'classic' | 'rolling';
+    /**
+     * Optional filters on cohort entry events.
+     * Applied when identifying which users enter the cohort.
+     */
+    cohortFilters?: Filter | Filter[];
+    /**
+     * Optional filters on return activity events.
+     * Applied when checking for user activity in each period.
+     */
+    activityFilters?: Filter | Filter[];
+    /**
+     * Optional breakdown dimensions for segmenting the cohort.
+     * When provided, retention is calculated per unique combination of breakdown values.
+     * e.g., ["Events.country", "Events.plan"] to see retention by country and plan.
+     */
+    breakdownDimensions?: string[];
+}
+/**
+ * Single retention data point in the flat result format.
+ * Results are returned as a flat array; client transforms to matrix if needed.
+ *
+ * Simplified format: no cohortPeriod since we use a single cohort model.
+ * When breakdownDimensions are specified, results include breakdownValues.
+ */
+export interface RetentionResultRow {
+    /** Period number (0 = cohort entry, 1 = first retention period, etc.) */
+    period: number;
+    /** Number of users in the cohort (or segment when breakdown is used) */
+    cohortSize: number;
+    /** Number of users retained in this period */
+    retainedUsers: number;
+    /** Retention rate as decimal (0-1), e.g., 0.45 for 45% */
+    retentionRate: number;
+    /**
+     * Breakdown values when breakdownDimensions are specified.
+     * Keyed by dimension name (e.g., { "Events.country": "US", "Events.plan": "pro" })
+     */
+    breakdownValues?: Record<string, string | null>;
+}
+/**
+ * Retention capabilities per database engine
+ */
+export interface RetentionCapabilities {
+    /** Whether database supports DATE_TRUNC natively */
+    supportsDateTrunc: boolean;
+    /** Whether database supports DATE_DIFF with unit specification */
+    supportsDateDiff: boolean;
+    /** Whether database supports generate_series for period generation */
+    supportsGenerateSeries: boolean;
+}
+/**
+ * Type guard for multi-cube binding key
+ */
+export declare function isRetentionMultiCubeBindingKey(bindingKey: string | RetentionBindingKeyMapping[]): bindingKey is RetentionBindingKeyMapping[];
+/**
+ * Type guard for multi-cube time dimension (object form)
+ */
+export declare function isRetentionMultiCubeTimeDimension(timeDimension: string | RetentionTimeDimensionMapping): timeDimension is RetentionTimeDimensionMapping;
+/**
+ * Type guard for retention query
+ */
+export declare function isRetentionQuery(query: unknown): query is {
+    retention: RetentionQueryConfig;
+};
+/**
+ * Extract cube name from a time dimension specification
+ */
+export declare function extractCubeFromTimeDimension(timeDimension: string | RetentionTimeDimensionMapping): string;
+/**
+ * Extract dimension name from a time dimension specification
+ */
+export declare function extractDimensionFromTimeDimension(timeDimension: string | RetentionTimeDimensionMapping): string;

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

@@ -0,0 +1,11 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { QueryContext } from './cube';
+/**
+ * Type-level utility to extract the schema type from a cube reference
+ * Since we removed generics, this now returns 'any'
+ */
+export type ExtractSchemaFromCubeRef = any;
+/**
+ * Type for SQL expressions that can be functions or direct values
+ */
+export type SqlExpression = AnyColumn | SQL | ((ctx: QueryContext) => AnyColumn | SQL);