drizzle-cube 0.5.8 → 0.6.0

package/dist/server/server/adapters/postgres-adapter.d.ts

@@ -1,12 +1,8 @@
 import { SQL, AnyColumn } from 'drizzle-orm';
 import { TimeGranularity } from '../types';
-import { BaseDatabaseAdapter, DatabaseCapabilities, WindowFunctionType, WindowFunctionConfig } from './base-adapter';
+import { BaseDatabaseAdapter, DatabaseCapabilities } from './base-adapter';
 export declare class PostgresAdapter extends BaseDatabaseAdapter {
     getEngineType(): 'postgres';
-    /**
-     * PostgreSQL supports LATERAL joins since version 9.3
-     */
-    supportsLateralJoins(): boolean;
     /**
      * Build PostgreSQL INTERVAL from ISO 8601 duration
      * PostgreSQL supports INTERVAL literal syntax: INTERVAL '7 days'
@@ -42,78 +38,18 @@ export declare class PostgresAdapter extends BaseDatabaseAdapter {
      * Extracted from executor.ts:649-670 and multi-cube-builder.ts:306-320
      */
     buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
-    /**
-     * Build PostgreSQL string matching conditions using ILIKE (case-insensitive)
-     * Extracted from executor.ts:807-813 and multi-cube-builder.ts:468-474
-     */
-    buildStringCondition(fieldExpr: AnyColumn | SQL, operator: 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex', value: string): SQL;
     /**
      * Build PostgreSQL type casting using :: syntax
      * Extracted from various locations where ::timestamp was used
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
-    /**
-     * Build PostgreSQL AVG aggregation with COALESCE for NULL handling
-     * PostgreSQL AVG returns NULL for empty sets, so we use COALESCE for consistent behavior
-     * Extracted from multi-cube-builder.ts:284
-     */
-    buildAvg(fieldExpr: AnyColumn | SQL): SQL;
-    /**
-     * Build PostgreSQL CASE WHEN conditional expression
-     */
-    buildCaseWhen(conditions: Array<{
-        when: SQL;
-        then: any;
-    }>, elseValue?: any): SQL;
-    /**
-     * Build PostgreSQL boolean literal
-     * PostgreSQL uses TRUE/FALSE keywords
-     */
-    buildBooleanLiteral(value: boolean): SQL;
-    /**
-     * Convert filter values - PostgreSQL uses native types
-     * No conversion needed for PostgreSQL
-     */
-    convertFilterValue(value: any): any;
-    /**
-     * Prepare date value for PostgreSQL
-     * PostgreSQL accepts Date objects directly
-     */
-    prepareDateValue(date: Date): any;
-    /**
-     * PostgreSQL stores timestamps as native timestamp types
-     */
-    isTimestampInteger(): boolean;
-    /**
-     * PostgreSQL time dimensions already return proper values
-     * No conversion needed
-     */
-    convertTimeDimensionResult(value: any): any;
     /**
      * PostgreSQL has full support for statistical and window functions
      */
     getCapabilities(): DatabaseCapabilities;
-    /**
-     * Build PostgreSQL STDDEV aggregation
-     * Uses STDDEV_POP for population, STDDEV_SAMP for sample
-     */
-    buildStddev(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
-    /**
-     * Build PostgreSQL VARIANCE aggregation
-     * Uses VAR_POP for population, VAR_SAMP for sample
-     */
-    buildVariance(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
     /**
      * Build PostgreSQL PERCENTILE_CONT aggregation
      * Uses ordered-set aggregate function
      */
     buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL;
-    /**
-     * Build PostgreSQL window function expression
-     * PostgreSQL has full window function support
-     */
-    buildWindowFunction(type: WindowFunctionType, fieldExpr: AnyColumn | SQL | null, partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
-        field: AnyColumn | SQL;
-        direction: 'asc' | 'desc';
-    }>, config?: WindowFunctionConfig): SQL;
 }

package/dist/server/server/adapters/snowflake-adapter.d.ts

@@ -1,19 +1,12 @@
 import { SQL, AnyColumn } from 'drizzle-orm';
 import { TimeGranularity } from '../types';
-import { BaseDatabaseAdapter, DatabaseCapabilities, WindowFunctionType, WindowFunctionConfig } from './base-adapter';
+import { BaseDatabaseAdapter, DatabaseCapabilities } from './base-adapter';
 export declare class SnowflakeAdapter extends BaseDatabaseAdapter {
     getEngineType(): 'snowflake';
-    /**
-     * Snowflake supports LATERAL joins
-     */
-    supportsLateralJoins(): boolean;
     /**
      * Build Snowflake INTERVAL from ISO 8601 duration
-     * Snowflake doesn't support INTERVAL literal syntax directly in all contexts,
-     * so we chain DATEADD calls. For standalone interval expressions, we return
-     * a DATEADD chain applied to TIMESTAMP '1970-01-01' and subtract it back.
-     * However, buildIntervalFromISO is typically used with buildDateAddInterval,
-     * so we return a structured representation.
+     * Snowflake doesn't have a standalone INTERVAL type like PostgreSQL.
+     * We convert to total seconds for use in DATEADD; callers should prefer buildDateAddInterval.
      */
     buildIntervalFromISO(duration: string): SQL;
     /**
@@ -26,11 +19,6 @@ export declare class SnowflakeAdapter extends BaseDatabaseAdapter {
      * Uses chained DATEADD(unit, amount, timestamp) calls
      */
     buildDateAddInterval(timestamp: SQL, duration: string): SQL;
-    /**
-     * Build Snowflake conditional aggregation using CASE WHEN
-     * Snowflake supports FILTER clause but CASE WHEN is more portable
-     */
-    buildConditionalAggregation(aggFn: 'count' | 'avg' | 'min' | 'max' | 'sum', expr: SQL | null, condition: SQL): SQL;
     /**
      * Build Snowflake date difference in periods using DATEDIFF
      */
@@ -45,72 +33,21 @@ export declare class SnowflakeAdapter extends BaseDatabaseAdapter {
      */
     buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
     /**
-     * Build Snowflake string matching conditions using native ILIKE
-     * Snowflake supports ILIKE natively
+     * Snowflake uses function-style regex matching: REGEXP_LIKE(field, pattern)
      */
-    buildStringCondition(fieldExpr: AnyColumn | SQL, operator: 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex', value: string): SQL;
+    protected regexCondition(fieldExpr: AnyColumn | SQL, value: string, negated: boolean): SQL;
     /**
      * Build Snowflake type casting using :: syntax
      * Snowflake supports both :: syntax and CAST() function
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
-    /**
-     * Build Snowflake AVG aggregation with COALESCE for NULL handling
-     */
-    buildAvg(fieldExpr: AnyColumn | SQL): SQL;
-    /**
-     * Build Snowflake CASE WHEN conditional expression
-     */
-    buildCaseWhen(conditions: Array<{
-        when: SQL;
-        then: any;
-    }>, elseValue?: any): SQL;
-    /**
-     * Build Snowflake boolean literal
-     * Snowflake uses TRUE/FALSE keywords
-     */
-    buildBooleanLiteral(value: boolean): SQL;
-    /**
-     * Convert filter values - Snowflake uses native types
-     */
-    convertFilterValue(value: any): any;
-    /**
-     * Prepare date value for Snowflake
-     * Snowflake accepts Date objects directly
-     */
-    prepareDateValue(date: Date): any;
-    /**
-     * Snowflake stores timestamps as native timestamp types
-     */
-    isTimestampInteger(): boolean;
-    /**
-     * Snowflake time dimensions already return proper values
-     */
-    convertTimeDimensionResult(value: any): any;
     /**
      * Snowflake capabilities - full SQL support
      */
     getCapabilities(): DatabaseCapabilities;
-    /**
-     * Build Snowflake STDDEV aggregation
-     */
-    buildStddev(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
-    /**
-     * Build Snowflake VARIANCE aggregation
-     * Snowflake supports native VAR_POP/VAR_SAMP
-     */
-    buildVariance(fieldExpr: AnyColumn | SQL, useSample?: boolean): SQL;
     /**
      * Build Snowflake PERCENTILE_CONT aggregation
      * Uses ordered-set aggregate function
      */
     buildPercentile(fieldExpr: AnyColumn | SQL, percentile: number): SQL;
-    /**
-     * Build Snowflake window function expression
-     * Snowflake has full window function support
-     */
-    buildWindowFunction(type: WindowFunctionType, fieldExpr: AnyColumn | SQL | null, partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
-        field: AnyColumn | SQL;
-        direction: 'asc' | 'desc';
-    }>, config?: WindowFunctionConfig): SQL;
 }

package/dist/server/server/adapters/sqlite-adapter.d.ts

@@ -1,13 +1,8 @@
 import { SQL, AnyColumn } from 'drizzle-orm';
 import { TimeGranularity } from '../types';
-import { BaseDatabaseAdapter, DatabaseCapabilities, WindowFunctionType, WindowFunctionConfig } from './base-adapter';
+import { BaseDatabaseAdapter, DatabaseCapabilities } from './base-adapter';
 export declare class SQLiteAdapter extends BaseDatabaseAdapter {
     getEngineType(): 'sqlite';
-    /**
-     * SQLite does not support LATERAL joins
-     * Flow queries require LATERAL for efficient execution and are not supported on SQLite
-     */
-    supportsLateralJoins(): boolean;
     /**
      * Build SQLite INTERVAL from ISO 8601 duration
      * SQLite doesn't have native interval types, so we convert to seconds
@@ -25,12 +20,6 @@ export declare class SQLiteAdapter extends BaseDatabaseAdapter {
      * Since SQLite stores timestamps as Unix seconds, just add the seconds
      */
     buildDateAddInterval(timestamp: SQL, duration: string): SQL;
-    /**
-     * Build SQLite conditional aggregation using CASE WHEN
-     * SQLite doesn't support FILTER clause, so we use CASE WHEN pattern
-     * Example: AVG(CASE WHEN step_1_time IS NOT NULL THEN time_diff END)
-     */
-    buildConditionalAggregation(aggFn: 'count' | 'avg' | 'min' | 'max' | 'sum', expr: SQL | null, condition: SQL): SQL;
     /**
      * Build SQLite date difference in periods
      * SQLite uses Julian day calculations for date arithmetic
@@ -50,22 +39,26 @@ export declare class SQLiteAdapter extends BaseDatabaseAdapter {
      */
     buildTimeDimension(granularity: TimeGranularity, fieldExpr: AnyColumn | SQL): SQL;
     /**
-     * Build SQLite string matching conditions using LOWER() + LIKE for case-insensitive matching
-     * SQLite LIKE is case-insensitive by default, but LOWER() ensures consistency
+     * SQLite has no ILIKE — use LOWER()+LIKE with the pattern lowercased in JS.
+     */
+    protected caseInsensitiveLike(fieldExpr: AnyColumn | SQL, pattern: string, negated: boolean): SQL;
+    /**
+     * SQLite regex requires loading an extension, so GLOB is used as a fallback.
      */
-    buildStringCondition(fieldExpr: AnyColumn | SQL, operator: 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'like' | 'notLike' | 'ilike' | 'regex' | 'notRegex', value: string): SQL;
+    protected regexCondition(fieldExpr: AnyColumn | SQL, value: string, negated: boolean): SQL;
     /**
      * Build SQLite type casting using CAST() function
      * SQLite has dynamic typing but supports CAST for consistency
      */
     castToType(fieldExpr: AnyColumn | SQL, targetType: 'timestamp' | 'decimal' | 'integer'): SQL;
     /**
-     * Build SQLite AVG aggregation with IFNULL for NULL handling
-     * SQLite AVG returns NULL for empty sets, using IFNULL for consistency
+     * SQLite AVG uses IFNULL rather than COALESCE for null-to-zero handling.
      */
-    buildAvg(fieldExpr: AnyColumn | SQL): SQL;
+    protected nullToZero(expr: SQL): SQL;
     /**
-     * Build SQLite CASE WHEN conditional expression
+     * Build SQLite CASE WHEN conditional expression.
+     * Unlike the base implementation, SQLite must detect embedded SQL objects in THEN/ELSE
+     * and inline them rather than binding them as parameters.
      */
     buildCaseWhen(conditions: Array<{
         when: SQL;
@@ -104,11 +97,6 @@ export declare class SQLiteAdapter extends BaseDatabaseAdapter {
      * SQLite stores timestamps as integers (milliseconds)
      */
     isTimestampInteger(): boolean;
-    /**
-     * Convert SQLite time dimension results back to Date objects
-     * SQLite time dimensions return datetime strings, but clients expect Date objects
-     */
-    convertTimeDimensionResult(value: any): any;
     /**
      * SQLite has limited statistical support (no native STDDEV/VARIANCE/PERCENTILE)
      * but supports window functions since SQLite 3.25
@@ -129,12 +117,4 @@ export declare class SQLiteAdapter extends BaseDatabaseAdapter {
      * Returns null for graceful degradation
      */
     buildPercentile(_fieldExpr: AnyColumn | SQL, _percentile: number): SQL | null;
-    /**
-     * Build SQLite window function expression
-     * SQLite 3.25+ supports window functions
-     */
-    buildWindowFunction(type: WindowFunctionType, fieldExpr: AnyColumn | SQL | null, partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
-        field: AnyColumn | SQL;
-        direction: 'asc' | 'desc';
-    }>, config?: WindowFunctionConfig): SQL;
 }

package/dist/server/server/adapters/window-function-builder.d.ts

@@ -0,0 +1,11 @@
+import { SQL, AnyColumn } from 'drizzle-orm';
+import { WindowFunctionType, WindowFunctionConfig } from './base-adapter';
+type FieldExpr = AnyColumn | SQL | null;
+/** Build the full `OVER (...)` clause from partition/order/frame components. */
+export declare function buildWindowOverClause(partitionBy?: (AnyColumn | SQL)[], orderBy?: Array<{
+    field: AnyColumn | SQL;
+    direction: 'asc' | 'desc';
+}>, config?: WindowFunctionConfig): SQL;
+/** Build the window function expression for a given type and pre-built OVER clause. */
+export declare function buildWindowExpression(type: WindowFunctionType, fieldExpr: FieldExpr, over: SQL, config?: WindowFunctionConfig): SQL;
+export {};

package/dist/server/server/agent/chart-validation.d.ts

@@ -13,11 +13,6 @@ interface ValidationResult {
  * Validate chartConfig against the chart type's drop zone requirements.
  */
 export declare function validateChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, _query: Record<string, unknown>): ValidationResult;
-/**
- * Auto-infer missing chartConfig fields from the query structure.
- * Fills in xAxis, yAxis, series, sizeField, etc. based on query measures/dimensions
- * and the chart type's drop zone acceptTypes.
- */
 export declare function inferChartConfig(chartType: string, chartConfig: Record<string, unknown> | undefined, query: Record<string, unknown>): Record<string, unknown>;
 /**
  * Build per-chart-type requirements text for the agent tool description.

package/dist/server/server/agent/handler-steps.d.ts

@@ -0,0 +1,37 @@
+import { AgentSSEEvent, AgentHistoryMessage, AgentConfig } from './types';
+import { ContentBlock, InternalMessage, ToolResult, LLMProvider } from './providers/types';
+import { ToolExecutionResult } from './tools';
+type AgentObservability = AgentConfig['observability'];
+type ToolExecutorMap = Map<string, (input: Record<string, unknown>) => Promise<ToolExecutionResult>>;
+/** Push provider-formatted tool results onto the message list (array or single). */
+export declare function pushFormattedResults(messages: InternalMessage[], formatted: unknown): void;
+/** Run an observability callback, swallowing any error (must never break the agent). */
+export declare function safeObserve(fn: (() => void) | undefined): void;
+/** Rebuild conversation messages from stored history (e.g. after notebook reload). */
+export declare function rebuildMessagesFromHistory(history: AgentHistoryMessage[] | undefined, provider: LLMProvider): InternalMessage[];
+/** Accumulated result of consuming one assistant generation stream. */
+export interface ConsumedStream {
+    contentBlocks: ContentBlock[];
+    stopReason: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/**
+ * Consume a provider's normalized stream, accumulating the assistant's content
+ * blocks and yielding text/tool SSE events. Returns the accumulated blocks,
+ * stop reason and token usage.
+ */
+export declare function consumeAssistantStream(provider: LLMProvider, stream: AsyncIterable<unknown>): AsyncGenerator<AgentSSEEvent, ConsumedStream>;
+/** Context shared across tool executions within a single turn. */
+export interface ToolExecContext {
+    executor: ToolExecutorMap;
+    observability: AgentObservability;
+    traceId: string;
+    turn: number;
+}
+/**
+ * Execute all tool-use blocks in the assistant's response, yielding their SSE
+ * events and returning the collected ToolResults.
+ */
+export declare function executeToolCalls(contentBlocks: ContentBlock[], ctx: ToolExecContext): AsyncGenerator<AgentSSEEvent, ToolResult[]>;
+export {};

package/dist/server/server/ai/discovery-helpers.d.ts

@@ -0,0 +1,29 @@
+import { CubeMetadata } from '../types/metadata';
+/** A measure or dimension as carried in cube metadata. */
+type Field = CubeMetadata['measures'][number] | CubeMetadata['dimensions'][number];
+/** Scoring callbacks shared with discovery.ts (avoids a circular import). */
+export interface ScoreFns {
+    fuzzyMatchScore: (query: string, target: string) => number;
+    matchAgainstArray: (query: string, targets: string[]) => number;
+}
+/**
+ * Score a single field (measure or dimension) against a keyword.
+ * Returns the best score across name, title, description and synonyms.
+ */
+export declare function scoreField(keyword: string, field: Field, fns: ScoreFns): number;
+/**
+ * Accumulate field scores for a keyword into a running totals map.
+ * Adds to `totalScore` (returned) and records the per-field best score when the
+ * field clears the relevance threshold, mutating `scores` and `matchedOn`.
+ */
+export declare function accumulateFieldScores(keyword: string, fields: Field[], fns: ScoreFns, scores: Map<string, number>, matchedOn: {
+    hit: boolean;
+}): number;
+/** Return the top-N field names from a score map, highest score first. */
+export declare function topScoredFields(scores: Map<string, number>, limit: number): string[];
+/**
+ * Score a single field as a best-match candidate (used by findBestFieldMatch).
+ * Returns the best score across name, title and synonyms (no description match).
+ */
+export declare function scoreFieldForBestMatch(fieldName: string, field: Field, fns: ScoreFns): number;
+export {};

package/dist/server/server/ai/discovery.d.ts

@@ -47,6 +47,10 @@ export interface DiscoveryOptions {
     /** Minimum relevance score (0-1) */
     minScore?: number;
 }
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
 /**
  * Discover relevant cubes based on topic or intent
  */

package/dist/server/server/ai/suggestion-helpers.d.ts

@@ -0,0 +1,33 @@
+import { CubeMetadata } from '../types/metadata';
+/** Format a Date as a YYYY-MM-DD string (UTC). */
+export declare function formatDate(d: Date): string;
+/** Resolve a numeric "last N days/weeks/months" expression. */
+export declare function parseRelativeNExpression(n: number, lowerText: string): {
+    dateRange: [string, string];
+    granularity?: string;
+} | null;
+/** Resolve a "Q1".."Q4" quarter expression for the current year. */
+export declare function parseQuarterExpression(quarterMatch: string): {
+    dateRange: [string, string];
+    granularity?: string;
+};
+/**
+ * Match measures in the primary cube against keywords in the text.
+ * Mutates `measures`/`reasoning` and returns the confidence delta to apply.
+ */
+export declare function matchMeasuresInText(primaryCube: CubeMetadata, lowerText: string, measures: string[], reasoning: string[]): number;
+/** Aggregation intent shape produced by detectAggregationIntent. */
+export interface AggregationIntent {
+    type: 'sum' | 'count' | 'avg' | 'max' | 'min';
+    confidence: number;
+}
+/**
+ * Backfill measures when none matched directly, using the aggregation intent.
+ * Mutates `measures`/`reasoning`.
+ */
+export declare function applyAggregationFallback(primaryCube: CubeMetadata, aggregationIntent: AggregationIntent, measures: string[], reasoning: string[]): void;
+/**
+ * Resolve grouping dimensions from grouping keywords and explicit "by/per X" text.
+ * Mutates `dimensions`/`reasoning` and returns the confidence delta to apply.
+ */
+export declare function matchDimensions(relevantCubes: CubeMetadata[], groupingKeywords: string[], lowerText: string, dimensions: string[], reasoning: string[]): number;

package/dist/server/server/ai/suggestion.d.ts

@@ -13,7 +13,4 @@ export interface QuerySuggestion {
     /** Next steps when mode != 'query' */
     nextSteps?: string[];
 }
-/**
- * Suggest a query based on natural language input
- */
 export declare function suggestQuery(metadata: CubeMetadata[], naturalLanguage: string, targetCube?: string): QuerySuggestion;

package/dist/server/server/ai/validation-helpers.d.ts

@@ -0,0 +1,21 @@
+import { TranslationKey } from '../../i18n/types';
+import { CubeMetadata } from '../types/metadata';
+import { SemanticQuery, Filter } from '../types/query';
+import { ValidationError, ValidationWarning } from './validation';
+/** Validate that a required event-stream field is present and (if a string) a valid dimension. */
+export declare function validateRequiredDimensionField(value: unknown, missingMessageKey: TranslationKey, validateDimension: (dimension: string, errors: ValidationError[]) => void, errors: ValidationError[]): void;
+/** Apply field-name corrections to a measures/dimensions string array. */
+export declare function applyCorrectionsToList(list: string[], corrections: Map<string, string>): string[];
+/** Build the corrected query by applying field corrections (returns undefined if none). */
+export declare function buildCorrectedQuery(query: SemanticQuery, corrections: Map<string, string>): SemanticQuery | undefined;
+/** Push performance/best-practice warnings for an oversized standard query. */
+export declare function collectPerformanceWarnings(query: SemanticQuery, warnings: ValidationWarning[]): void;
+/** Warn when a declared time dimension is not actually of time type. */
+export declare function checkTimeDimensionType(dimensionRef: string, metadata: CubeMetadata[], warnings: ValidationWarning[]): void;
+/** Validate a single member-style filter (cube + field existence). */
+export declare function validateMemberFilter(filter: Extract<Filter, {
+    member: string;
+}>, metadata: CubeMetadata[], errors: ValidationError[], corrections: Map<string, string>, findClosestField: (fieldName: string, available: string[]) => {
+    field: string;
+    distance: number;
+} | null): void;

package/dist/server/server/ai/validation.d.ts

@@ -28,7 +28,4 @@ export interface ValidationWarning {
     field?: string;
     suggestion?: string;
 }
-/**
- * Validate a query with helpful corrections
- */
 export declare function validateQuery(query: SemanticQuery, metadata: CubeMetadata[]): ValidationResult;

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/cte-builder.d.ts

@@ -26,6 +26,52 @@ export declare class CTEBuilder {
      * 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
      *

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

@@ -12,6 +12,11 @@ export declare class DateTimeBuilder {
      * 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