drizzle-cube 0.5.7 → 0.6.0

package/dist/server/server/executor.d.ts

@@ -0,0 +1,186 @@
+import { SecurityContext, SemanticQuery, QueryResult, DatabaseExecutor, Cube, CacheConfig, ExplainOptions, ExplainResult, ExecutionOptions, QueryAnalysis, RLSSetupFn } from './types';
+import { PlanOptimiser } from './logical-plan';
+export declare class QueryExecutor {
+    private dbExecutor;
+    private queryBuilder;
+    private drizzlePlanBuilder;
+    private databaseAdapter;
+    private comparisonQueryBuilder;
+    private funnelQueryBuilder;
+    private flowQueryBuilder;
+    private retentionQueryBuilder;
+    private logicalPlanBuilder;
+    private planOptimiser;
+    private modeRouter;
+    private resultCache;
+    private filterCachePreloader;
+    private rlsSetup?;
+    constructor(dbExecutor: DatabaseExecutor, cacheConfig?: CacheConfig, rlsSetup?: RLSSetupFn, planOptimiser?: PlanOptimiser);
+    /**
+     * Execute a function within a RLS-configured transaction context.
+     * If no rlsSetup function is configured, the function is called directly.
+     * Otherwise, opens a transaction, calls rlsSetup to configure RLS, then
+     * runs fn with this.dbExecutor replaced by a transaction-scoped executor.
+     *
+     * Concurrency-safe: the dbExecutor is per-request (created fresh by
+     * SemanticLayerCompiler.createQueryExecutor), so reassigning this.dbExecutor
+     * only affects this request.
+     */
+    private withRLSContext;
+    /**
+     * Unified query execution method that handles both single and multi-cube queries
+     * @param options.skipCache - Skip cache lookup (but still cache the fresh result)
+     */
+    execute(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext, options?: ExecutionOptions): Promise<QueryResult>;
+    /**
+     * Build a logical plan for a query without executing it.
+     * Useful for testing, debugging, and plan inspection.
+     */
+    buildLogicalPlan(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): import('./logical-plan').QueryNode;
+    /**
+     * Analyze planning decisions for a regular query using the same logical
+     * planning path as execution and dry-run SQL generation.
+     */
+    analyzeQuery(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): QueryAnalysis;
+    /**
+     * Legacy interface for single cube queries
+     */
+    executeQuery(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<QueryResult>;
+    /**
+     * Execute a comparison query with caching support
+     * Wraps executeComparisonQuery with cache set logic
+     */
+    private executeComparisonQueryWithCache;
+    /**
+     * Execute a comparison query with multiple date periods
+     * Expands compareDateRange into multiple sub-queries and merges results
+     */
+    private executeComparisonQuery;
+    private buildComparisonExecutionPlan;
+    /**
+     * Execute an analysis query (funnel/flow/retention) with caching support.
+     * Wraps the inner execute callback with cache-set logic; the three analysis
+     * modes share identical wrapper behaviour, differing only in which inner
+     * execute method they invoke.
+     *
+     * Cache metadata is intentionally NOT attached here: fresh results across all
+     * query modes (regular, comparison, and analysis) uniformly carry no `cache`
+     * field — only cache *hits* (handled in execute()) carry cache metadata.
+     */
+    private executeAnalysisQueryWithCache;
+    /**
+     * Execute a funnel analysis query
+     */
+    private executeFunnelQuery;
+    /**
+     * Execute a flow analysis query
+     * Produces Sankey diagram data (nodes and links)
+     */
+    private executeFlowQuery;
+    /**
+     * Execute a retention analysis query
+     * Calculates cohort-based retention rates
+     */
+    private executeRetentionQuery;
+    /**
+     * Standard (regular/non-comparison) query execution.
+     *
+     * This is the single core execution path used by both the regular query mode
+     * and comparison-mode period sub-queries. It always runs the dev-time
+     * security-context validation and propagates planner warnings; the optional
+     * `cacheKey` controls whether the fresh result is written to the cache.
+     *
+     * @param cacheKey - When provided (and a cache provider is configured), the
+     *   fresh result is written to the cache. Pass `undefined` to skip caching
+     *   (e.g. comparison period sub-queries cache at the comparison level).
+     */
+    private executeStandardQuery;
+    /**
+     * Create a query context with optional filter cache.
+     */
+    private createQueryContext;
+    /**
+     * Resolve the real database engine type for optimiser passes.
+     * Returns the true engine for all 7 supported engines (no collapsing);
+     * passes decide for themselves whether to treat e.g. SingleStore like MySQL.
+     */
+    private getOptimiserEngineType;
+    /**
+     * Shared regular-query planning pipeline used by execute, dry-run SQL,
+     * and analysis. This is the single source of planning truth.
+     */
+    private buildRegularQueryArtifacts;
+    /**
+     * Validate that all cubes in the query plan have proper security filtering.
+     * Emits a warning if a cube's sql() function doesn't return a WHERE clause.
+     *
+     * Security is critical in multi-tenant applications - this validation helps
+     * detect cubes that may leak data across tenants.
+     */
+    private validateSecurityContext;
+    /**
+     * Generate raw SQL for debugging (without execution) - unified approach
+     */
+    generateSQL(cube: Cube, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate raw SQL for multi-cube queries without execution - unified approach
+     */
+    generateMultiCubeSQL(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a funnel query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
+     */
+    dryRunFunnel(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a flow query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
+     */
+    dryRunFlow(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL for a retention query without execution (dry-run)
+     * Returns the actual CTE-based SQL that would be executed
+     */
+    dryRunRetention(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generic dry-run SQL generator for analysis modes (funnel/flow/retention).
+     * The three modes share an identical shape (mode guard → config validation →
+     * build query → toSQL()), differing only in which builder/config they use.
+     */
+    private dryRunAnalysis;
+    /**
+     * Execute EXPLAIN on a query to get the execution plan
+     * Generates the SQL using the same secure path as execute/generateSQL,
+     * then runs EXPLAIN on the database.
+     */
+    explainQuery(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext, options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Generate SQL for any query mode without execution.
+     * This is the canonical dry-run SQL entrypoint used by explain/adapters.
+     */
+    dryRunSQL(cubes: Map<string, Cube>, query: SemanticQuery, securityContext: SecurityContext): Promise<{
+        sql: string;
+        params?: any[];
+    }>;
+    /**
+     * Generate SQL using unified approach (works for both single and multi-cube)
+     */
+    private generateUnifiedSQL;
+    private executeQueryByModeWithCache;
+    private generateSqlForMode;
+    private generateComparisonSQL;
+}

package/dist/server/server/executors/base-executor.d.ts

@@ -0,0 +1,16 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, DatabaseExecutor, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { DatabaseAdapter } from '../adapters/base-adapter';
+/**
+ * Abstract base class for database executors
+ */
+export declare abstract class BaseDatabaseExecutor implements DatabaseExecutor {
+    db: DrizzleDatabase;
+    schema?: any | undefined;
+    databaseAdapter: DatabaseAdapter;
+    constructor(db: DrizzleDatabase, schema?: any | undefined, engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake');
+    abstract execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    abstract getEngineType(): 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake';
+    abstract explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    abstract getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}

package/dist/server/server/executors/databend-executor.d.ts

@@ -0,0 +1,33 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class DatabendExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Extract SQL string and params from a query object for error logging
+     */
+    private extractSqlFromQuery;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'databend';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     * Databend supports EXPLAIN and EXPLAIN ANALYZE
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     * Databend uses system tables for index information
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating Databend executors
+ */
+export declare function createDatabendExecutor(db: DrizzleDatabase, schema?: any): DatabendExecutor;

package/dist/server/server/executors/duckdb-executor.d.ts

@@ -0,0 +1,33 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class DuckDBExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Extract SQL string and params from a query object for error logging
+     */
+    private extractSqlFromQuery;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'duckdb';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     * DuckDB supports EXPLAIN and EXPLAIN ANALYZE
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     * DuckDB uses duckdb_indexes() table function
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating DuckDB executors
+ */
+export declare function createDuckDBExecutor(db: DrizzleDatabase, schema?: any): DuckDBExecutor;

package/dist/server/server/executors/explain-utils.d.ts

@@ -0,0 +1,28 @@
+import { SQL } from 'drizzle-orm';
+/**
+ * Rebuild a parameterized SQL string into a Drizzle SQL object with `params`
+ * bound as real driver parameters.
+ *
+ * @param sqlString - SQL produced by Drizzle's `.toSQL()`, containing either `?`
+ *   placeholders (mysql/sqlite/singlestore/snowflake) or `$n` placeholders
+ *   (postgres/duckdb/databend)
+ * @param params - Bound parameter values, in order
+ * @param style - Placeholder style used by `sqlString`
+ */
+export declare function buildBoundSql(sqlString: string, params: unknown[], style: 'question' | 'dollar'): SQL;
+/**
+ * Normalize raw MySQL EXPLAIN result rows into the column shape the MySQL parser
+ * expects. Extracted from MySQLExecutor.explainQuery to keep that method simple.
+ */
+export declare function normalizeMySQLExplainRows(result: unknown): any[];
+/**
+ * Normalize raw SQLite EXPLAIN QUERY PLAN result rows into the column shape the
+ * SQLite parser expects. Extracted from SQLiteExecutor.explainQuery.
+ */
+export declare function normalizeSQLiteExplainRows(result: unknown): any[];
+/**
+ * Extract the textual plan lines from PostgreSQL EXPLAIN result rows. Handles the
+ * differing column-name casing across drivers. Extracted from
+ * PostgresExecutor.explainQuery.
+ */
+export declare function extractPostgresExplainLines(rows: any[]): string[];

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

@@ -0,0 +1,21 @@
+import { DrizzleDatabase, DatabaseExecutor } from '../types';
+/**
+ * Database executors for different database engines
+ * Handles SQL execution with proper type coercion
+ */
+export { BaseDatabaseExecutor } from './base-executor';
+export { PostgresExecutor, createPostgresExecutor } from './postgres-executor';
+export { MySQLExecutor, createMySQLExecutor } from './mysql-executor';
+export { SQLiteExecutor, createSQLiteExecutor } from './sqlite-executor';
+export { SingleStoreExecutor, createSingleStoreExecutor } from './singlestore-executor';
+export { DuckDBExecutor, createDuckDBExecutor } from './duckdb-executor';
+export { DatabendExecutor, createDatabendExecutor } from './databend-executor';
+export { SnowflakeExecutor, createSnowflakeExecutor } from './snowflake-executor';
+/**
+ * Auto-detect database type and create appropriate executor
+ * @param db - Drizzle database instance
+ * @param schema - Optional schema for type inference
+ * @param engineType - Optional explicit engine type override
+ * @returns Appropriate database executor
+ */
+export declare function createDatabaseExecutor(db: DrizzleDatabase, schema?: any, engineType?: 'postgres' | 'mysql' | 'sqlite' | 'singlestore' | 'duckdb' | 'databend' | 'snowflake'): DatabaseExecutor;

package/dist/server/server/executors/mysql-executor.d.ts

@@ -0,0 +1,27 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class MySQLExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Convert numeric string fields to numbers (measure fields + numeric dimensions)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'mysql' | 'singlestore';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating MySQL executors
+ */
+export declare function createMySQLExecutor(db: DrizzleDatabase, schema?: any): MySQLExecutor;

package/dist/server/server/executors/postgres-executor.d.ts

@@ -0,0 +1,27 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class PostgresExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'postgres';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating PostgreSQL executors
+ */
+export declare function createPostgresExecutor(db: DrizzleDatabase, schema?: any): PostgresExecutor;

package/dist/server/server/executors/singlestore-executor.d.ts

@@ -0,0 +1,9 @@
+import { DrizzleDatabase } from '../types';
+import { MySQLExecutor } from './mysql-executor';
+export declare class SingleStoreExecutor extends MySQLExecutor {
+    getEngineType(): 'singlestore';
+}
+/**
+ * Factory function for creating SingleStore executors
+ */
+export declare function createSingleStoreExecutor(db: DrizzleDatabase, schema?: any): SingleStoreExecutor;

package/dist/server/server/executors/snowflake-executor.d.ts

@@ -0,0 +1,33 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class SnowflakeExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Extract SQL string and params from a query object for error logging
+     */
+    private extractSqlFromQuery;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'snowflake';
+    /**
+     * Execute EXPLAIN on a SQL query to get the execution plan
+     * Snowflake supports EXPLAIN and EXPLAIN USING TEXT/JSON/TABULAR
+     */
+    explainQuery(sqlString: string, params: unknown[], options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     * Snowflake doesn't use traditional indexes (it uses micro-partitioning)
+     */
+    getTableIndexes(_tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating Snowflake executors
+ */
+export declare function createSnowflakeExecutor(db: DrizzleDatabase, schema?: any): SnowflakeExecutor;

package/dist/server/server/executors/sqlite-executor.d.ts

@@ -0,0 +1,28 @@
+import { SQL } from 'drizzle-orm';
+import { DrizzleDatabase, ExplainOptions, ExplainResult, IndexInfo } from '../types';
+import { BaseDatabaseExecutor } from './base-executor';
+export declare class SQLiteExecutor extends BaseDatabaseExecutor {
+    execute<T = any[]>(query: SQL | any, numericFields?: string[]): Promise<T>;
+    /**
+     * Convert numeric string fields to numbers (only for measure fields)
+     */
+    private convertNumericFields;
+    /**
+     * Coerce a value to a number if it represents a numeric type
+     */
+    private coerceToNumber;
+    getEngineType(): 'sqlite';
+    /**
+     * Execute EXPLAIN QUERY PLAN on a SQL query to get the execution plan
+     * Note: SQLite doesn't support EXPLAIN ANALYZE
+     */
+    explainQuery(sqlString: string, params: unknown[], _options?: ExplainOptions): Promise<ExplainResult>;
+    /**
+     * Get existing indexes for the specified tables
+     */
+    getTableIndexes(tableNames: string[]): Promise<IndexInfo[]>;
+}
+/**
+ * Factory function for creating SQLite executors
+ */
+export declare function createSQLiteExecutor(db: DrizzleDatabase, schema?: any): SQLiteExecutor;

package/dist/server/server/explain/databend-parser.d.ts

@@ -0,0 +1,16 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * Parse Databend EXPLAIN output
+ *
+ * Databend EXPLAIN output is typically indented text showing the query plan tree.
+ * Example:
+ * "Filter"
+ * "├── filters: [employees.organisation_id = 1]"
+ * "├── TableScan"
+ * "│   ├── table: employees"
+ * "│   ├── estimated rows: 1000"
+ */
+export declare function parseDatabendExplain(rawOutput: string[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;

package/dist/server/server/explain/duckdb-parser.d.ts

@@ -0,0 +1,28 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * Parse DuckDB EXPLAIN output
+ *
+ * Example DuckDB EXPLAIN output:
+ * "┌───────────────────────────┐"
+ * "│      EXPLANATION OF       │"
+ * "│     QUERY PLAN            │"
+ * "└───────────────────────────┘"
+ * "┌─────────────────────────────────────────────────────────────────────┐"
+ * "│                     QUERY PLAN                                      │"
+ * "├─────────────────────────────────────────────────────────────────────┤"
+ * "│  HASH_JOIN                                                          │"
+ * "│  ├──SEQ_SCAN employees                                              │"
+ * "│  │  (cost=100.0 rows=1000)                                          │"
+ * "│  └──SEQ_SCAN departments                                            │"
+ * "│     (cost=50.0 rows=500)                                            │"
+ * "└─────────────────────────────────────────────────────────────────────┘"
+ *
+ * Or simpler format:
+ * "HASH_JOIN"
+ * "├──SEQ_SCAN employees"
+ * "└──SEQ_SCAN departments"
+ */
+export declare function parseDuckDBExplain(rawOutput: string[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;

package/dist/server/server/explain/explain-tree.d.ts

@@ -0,0 +1,20 @@
+import { ExplainOperation } from '../types/executor';
+/** Stack entry tracking an operation and its indentation depth. */
+export interface ExplainStackEntry {
+    indent: number;
+    op: ExplainOperation;
+}
+/**
+ * Insert an operation into the hierarchical tree using the indentation stack.
+ *
+ * Pops the stack until the top entry has strictly less indentation than the
+ * incoming operation, then attaches the operation either as a root (pushed to
+ * `operations`) or as a child of the current stack top. Finally pushes the
+ * operation onto the stack so subsequent deeper lines can nest under it.
+ */
+export declare function pushOperationToTree(stack: ExplainStackEntry[], operations: ExplainOperation[], operation: ExplainOperation, indent: number): void;
+/**
+ * Count indentation level based on tree drawing characters and spaces.
+ * Used by DuckDB and Databend parsers.
+ */
+export declare function countTreeIndent(line: string): number;

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

@@ -0,0 +1,9 @@
+/**
+ * EXPLAIN plan parsers
+ * Normalize raw EXPLAIN output from different databases to a common format
+ */
+export { parsePostgresExplain } from './postgres-parser';
+export { parseMySQLExplain } from './mysql-parser';
+export { parseSQLiteExplain } from './sqlite-parser';
+export { parseDuckDBExplain } from './duckdb-parser';
+export type { ExplainOperation, ExplainResult, ExplainSummary, ExplainOptions } from '../types/executor';

package/dist/server/server/explain/mysql-parser.d.ts

@@ -0,0 +1,38 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * MySQL EXPLAIN row structure
+ * Standard columns returned by EXPLAIN
+ */
+interface MySQLExplainRow {
+    id: number;
+    select_type: string;
+    table: string | null;
+    partitions: string | null;
+    type: string;
+    possible_keys: string | null;
+    key: string | null;
+    key_len: string | null;
+    ref: string | null;
+    rows: number;
+    filtered: number;
+    Extra: string | null;
+}
+/**
+ * Parse MySQL EXPLAIN output
+ *
+ * MySQL EXPLAIN returns rows with columns:
+ * id, select_type, table, partitions, type, possible_keys, key, key_len, ref, rows, filtered, Extra
+ *
+ * The 'type' column indicates access method:
+ * - ALL: Full table scan (like Seq Scan)
+ * - index: Full index scan
+ * - range: Index range scan
+ * - ref: Index lookup using non-unique index
+ * - eq_ref: Index lookup using unique index
+ * - const: Single row lookup
+ */
+export declare function parseMySQLExplain(rows: MySQLExplainRow[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;
+export {};

package/dist/server/server/explain/postgres-parser.d.ts

@@ -0,0 +1,18 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * Parse PostgreSQL EXPLAIN output (text format)
+ *
+ * Example input:
+ * "Hash Join  (cost=1.09..2.19 rows=1 width=68)"
+ * "  Hash Cond: (e.department_id = d.id)"
+ * "  ->  Seq Scan on employees e  (cost=0.00..1.05 rows=5 width=44)"
+ * "        Filter: (organisation_id = 'org-1'::text)"
+ * "  ->  Hash  (cost=1.04..1.04 rows=4 width=36)"
+ * "        ->  Seq Scan on departments d  (cost=0.00..1.04 rows=4 width=36)"
+ * "Planning Time: 0.123 ms"
+ * "Execution Time: 0.456 ms"  (only with ANALYZE)
+ */
+export declare function parsePostgresExplain(rawOutput: string[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;

package/dist/server/server/explain/snowflake-parser.d.ts

@@ -0,0 +1,17 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * Parse Snowflake EXPLAIN output
+ *
+ * Snowflake EXPLAIN output shows the query plan as indented text.
+ * Example:
+ * "GlobalStats:"
+ * "    partitionsTotal=1"
+ * "    partitionsAssigned=1"
+ * "1:0     ->Result"
+ * "1:1         ->Filter"
+ * "1:2             ->TableScan"
+ */
+export declare function parseSnowflakeExplain(rawOutput: string[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;

package/dist/server/server/explain/sqlite-parser.d.ts

@@ -0,0 +1,23 @@
+import { ExplainResult } from '../types/executor';
+/**
+ * SQLite EXPLAIN QUERY PLAN row structure
+ */
+interface SQLiteExplainRow {
+    id: number;
+    parent: number;
+    notused: number;
+    detail: string;
+}
+/**
+ * Parse SQLite EXPLAIN QUERY PLAN output
+ *
+ * SQLite EXPLAIN QUERY PLAN returns rows with columns:
+ * id, parent, notused, detail
+ *
+ * The 'detail' column contains human-readable operation descriptions
+ */
+export declare function parseSQLiteExplain(rows: SQLiteExplainRow[], sqlQuery: {
+    sql: string;
+    params?: unknown[];
+}): ExplainResult;
+export {};