@hypequery/clickhouse 2.0.0 → 2.0.2

package/dist/datasets.js

@@ -0,0 +1,387 @@
+/**
+ * ClickHouse Semantic Backend
+ *
+ * This module implements the SemanticBackend interface from @hypequery/datasets
+ * for ClickHouse databases. It translates database-agnostic semantic plans
+ * (PlanNode) into ClickHouse-specific SQL and executes them.
+ *
+ * Architecture:
+ * - @hypequery/datasets: Owns semantic planning, validation, and execution protocol
+ * - @hypequery/clickhouse: Implements SQL translation and execution for ClickHouse
+ *
+ * Usage:
+ * ```ts
+ * import { createDatasetClient } from '@hypequery/datasets';
+ * import { createBackend } from '@hypequery/clickhouse';
+ *
+ * const analytics = createDatasetClient({
+ *   backend: createBackend({
+ *     url: process.env.CLICKHOUSE_URL,
+ *     username: process.env.CLICKHOUSE_USER,
+ *     password: process.env.CLICKHOUSE_PASSWORD,
+ *     database: process.env.CLICKHOUSE_DATABASE,
+ *   })
+ * });
+ * ```
+ */
+import { createQueryBuilder } from './core/query-builder.js';
+// =============================================================================
+// ClickHouse SQL Generation Utilities
+// =============================================================================
+const GRAIN_FUNCTIONS = {
+    day: 'toStartOfDay',
+    week: 'toStartOfWeek',
+    month: 'toStartOfMonth',
+    quarter: 'toStartOfQuarter',
+    year: 'toStartOfYear',
+};
+/**
+ * SQL Literal Rendering
+ * Safely escapes values for direct SQL inclusion
+ */
+function renderLiteral(value) {
+    if (value === null)
+        return 'NULL';
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? '1' : '0';
+    // SQL string escaping: single quotes are escaped by doubling them
+    return `'${String(value).replace(/'/g, "''")}'`;
+}
+/**
+ * Time Grain Rendering
+ * Converts semantic grain to ClickHouse function
+ */
+function renderGrain(field, unit) {
+    return `${GRAIN_FUNCTIONS[unit]}(${field})`;
+}
+/**
+ * Filter Rendering - Applies filters using query builder WHERE clauses
+ * This is the preferred method when working with the query builder
+ */
+function applyFilters(builder, filters) {
+    let qb = builder;
+    for (const filter of filters) {
+        qb = qb.where(filter.field, filter.operator, filter.value);
+    }
+    return qb;
+}
+/**
+ * Type guard to check if value is a valid literal for SQL rendering
+ */
+function isLiteralValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null);
+}
+/**
+ * Safely render a filter value as a SQL literal
+ * Throws if value is not a valid literal type
+ */
+function renderFilterValue(value) {
+    if (!isLiteralValue(value)) {
+        throw new Error(`Invalid filter value type: ${typeof value}`);
+    }
+    return renderLiteral(value);
+}
+/**
+ * Filter Condition Rendering - Converts filter to SQL WHERE clause string
+ * Used for filtered aggregations (IF conditions) where query builder can't be used
+ */
+function renderFilterCondition(filter) {
+    const { field, operator, value } = filter;
+    switch (operator) {
+        case 'eq':
+            return `${field} = ${renderFilterValue(value)}`;
+        case 'neq':
+            return `${field} != ${renderFilterValue(value)}`;
+        case 'gt':
+            return `${field} > ${renderFilterValue(value)}`;
+        case 'gte':
+            return `${field} >= ${renderFilterValue(value)}`;
+        case 'lt':
+            return `${field} < ${renderFilterValue(value)}`;
+        case 'lte':
+            return `${field} <= ${renderFilterValue(value)}`;
+        case 'like':
+            return `${field} LIKE ${renderFilterValue(value)}`;
+        case 'in':
+        case 'notIn': {
+            if (!Array.isArray(value) || value.length === 0) {
+                throw new Error(`"${operator}" filters require a non-empty array.`);
+            }
+            const values = value.map(renderFilterValue).join(', ');
+            const op = operator === 'in' ? 'IN' : 'NOT IN';
+            return `${field} ${op} (${values})`;
+        }
+        case 'between': {
+            if (!Array.isArray(value) || value.length !== 2) {
+                throw new Error('"between" filters require a two-item array.');
+            }
+            return `${field} BETWEEN ${renderFilterValue(value[0])} AND ${renderFilterValue(value[1])}`;
+        }
+        default:
+            throw new Error(`Unsupported filter operator "${operator}".`);
+    }
+}
+/**
+ * Filtered Aggregation Field Rendering
+ * Generates ClickHouse IF() expressions for conditional aggregations
+ * Example: SUM(if(status = 'completed', amount, 0))
+ */
+function renderFilteredAggregationField(aggregation) {
+    if (!aggregation.filters?.length) {
+        return aggregation.field;
+    }
+    // Combine multiple filters with AND
+    const condition = aggregation.filters
+        .map(renderFilterCondition)
+        .map((part) => `(${part})`)
+        .join(' AND ');
+    // Use appropriate fallback: 0 for SUM, NULL for others
+    const fallback = aggregation.aggregation === 'sum' ? '0' : 'NULL';
+    return `if(${condition}, ${aggregation.field}, ${fallback})`;
+}
+/**
+ * Expression Rendering
+ * Converts semantic expressions (formulas) to SQL
+ * Used for derived metrics
+ */
+function renderExpression(expression) {
+    switch (expression.kind) {
+        case 'ref':
+            return expression.name;
+        case 'literal':
+            return renderLiteral(expression.value);
+        case 'binary': {
+            const operators = {
+                add: '+',
+                subtract: '-',
+                multiply: '*',
+                divide: '/',
+            };
+            const op = operators[expression.operator];
+            const left = renderExpression(expression.left);
+            const right = renderExpression(expression.right);
+            return `(${left}) ${op} (${right})`;
+        }
+        case 'function': {
+            const args = expression.args.map(renderExpression);
+            // Special case functions with custom SQL
+            if (expression.name === 'nullIfZero') {
+                return `NULLIF(${args[0]}, 0)`;
+            }
+            if (expression.name === 'coalesce') {
+                return `COALESCE(${args.join(', ')})`;
+            }
+            // Standard functions
+            const functionMap = {
+                round: 'ROUND',
+                floor: 'FLOOR',
+                ceil: 'CEIL',
+            };
+            const fn = functionMap[expression.name];
+            if (!fn) {
+                throw new Error(`Unsupported function: ${expression.name}`);
+            }
+            return `${fn}(${args.join(', ')})`;
+        }
+        default:
+            throw new Error('Unsupported semantic expression.');
+    }
+}
+// =============================================================================
+// Query Builder Integration
+// =============================================================================
+/**
+ * Apply Aggregations
+ * Translates semantic aggregations to query builder method calls
+ */
+function applyAggregations(builder, plan) {
+    let qb = builder;
+    for (const aggregation of plan.aggregations) {
+        const field = renderFilteredAggregationField(aggregation);
+        const { name, aggregation: aggType } = aggregation;
+        switch (aggType) {
+            case 'sum':
+                qb = qb.sum(field, name);
+                break;
+            case 'count':
+                qb = qb.count(field, name);
+                break;
+            case 'countDistinct':
+                qb = qb.countDistinct(field, name);
+                break;
+            case 'avg':
+                qb = qb.avg(field, name);
+                break;
+            case 'min':
+                qb = qb.min(field, name);
+                break;
+            case 'max':
+                qb = qb.max(field, name);
+                break;
+        }
+    }
+    return qb;
+}
+/**
+ * Append Order/Limit/Offset
+ * Applies result modifiers to query builder
+ */
+function appendOrderLimitOffset(builder, plan) {
+    let qb = builder;
+    // Order by
+    for (const order of plan.orderBy ?? []) {
+        qb = qb.orderBy(order.field, order.direction.toUpperCase());
+    }
+    // Pagination
+    if (plan.limit != null)
+        qb = qb.limit(plan.limit);
+    if (plan.offset != null)
+        qb = qb.offset(plan.offset);
+    return qb;
+}
+// =============================================================================
+// Plan Translation to SQL
+// =============================================================================
+/**
+ * Build Aggregate Query
+ * Translates semantic aggregate plan to ClickHouse query builder
+ */
+function buildAggregateQuery(queryBuilder, plan) {
+    let qb = queryBuilder.table(plan.source);
+    // Build SELECT and GROUP BY for dimensions
+    const selectParts = [];
+    const groupByParts = [];
+    // Time grain (period column)
+    if (plan.grain) {
+        const grainSql = renderGrain(plan.grain.field, plan.grain.unit);
+        selectParts.push(`${grainSql} AS ${plan.grain.output}`);
+        groupByParts.push(plan.grain.output);
+    }
+    // Dimensions
+    for (const dimension of plan.dimensions) {
+        const columnSql = dimension.field === dimension.name
+            ? dimension.name
+            : `${dimension.field} AS ${dimension.name}`;
+        selectParts.push(columnSql);
+        groupByParts.push(dimension.name);
+    }
+    // Apply SELECT clause
+    if (selectParts.length > 0) {
+        qb = qb.select(selectParts);
+    }
+    // Apply aggregations (measures)
+    qb = applyAggregations(qb, plan);
+    // Apply GROUP BY
+    if (groupByParts.length > 0) {
+        qb = qb.groupBy(groupByParts);
+    }
+    // Apply tenant filter (auto-injected)
+    if (plan.tenant) {
+        qb = qb.where(plan.tenant.field, 'eq', plan.tenant.value);
+    }
+    // Apply user filters
+    qb = applyFilters(qb, plan.filters);
+    // Apply order/limit/offset
+    return appendOrderLimitOffset(qb, plan);
+}
+/**
+ * Build Derived Metric SQL
+ * Generates CTE-based query for derived metrics (formulas over base metrics)
+ *
+ * Note: Uses string concatenation for outer query since query builder
+ * doesn't support CTEs natively. Inner query uses query builder for safety.
+ */
+function buildDerivedSQL(queryBuilder, plan) {
+    if (plan.input.kind !== 'aggregate') {
+        throw new Error('ClickHouse datasets currently supports derived metrics over aggregate input plans only.');
+    }
+    // Build inner aggregate query using query builder
+    const inputQuery = buildAggregateQuery(queryBuilder, plan.input);
+    const { sql, parameters } = inputQuery.toSQLWithParams();
+    // Passthrough columns (grain + dimensions)
+    const passthrough = [
+        ...(plan.input.grain ? [plan.input.grain.output] : []),
+        ...plan.input.dimensions.map((dim) => dim.name),
+    ];
+    // Derived metric calculations
+    const metricSelects = plan.metrics.map((metric) => `${renderExpression(metric.expression)} AS ${metric.name}`);
+    // Build outer query with CTE
+    const allSelects = [...passthrough, ...metricSelects];
+    let outerSql = `WITH base AS (${sql}) SELECT ${allSelects.join(', ')} FROM base`;
+    // ORDER BY
+    if (plan.orderBy?.length) {
+        const orderClauses = plan.orderBy.map((order) => `${order.field} ${order.direction.toUpperCase()}`);
+        outerSql += ` ORDER BY ${orderClauses.join(', ')}`;
+    }
+    // LIMIT and OFFSET
+    if (plan.limit != null) {
+        outerSql += ` LIMIT ${plan.limit}`;
+    }
+    if (plan.offset != null) {
+        outerSql += ` OFFSET ${plan.offset}`;
+    }
+    return { sql: outerSql, parameters };
+}
+// =============================================================================
+// Semantic Backend Implementation
+// =============================================================================
+/**
+ * Create ClickHouse Semantic Backend
+ *
+ * Creates a SemanticBackend implementation that translates database-agnostic
+ * semantic plans into ClickHouse SQL and executes them.
+ *
+ * @param config - ClickHouse connection configuration
+ * @returns SemanticBackend interface for executing semantic queries
+ */
+export function createBackend(config) {
+    const queryBuilder = createQueryBuilder(config);
+    return {
+        /**
+         * Execute a semantic plan and return results
+         */
+        async execute(plan) {
+            const start = Date.now();
+            if (plan.kind === 'aggregate') {
+                // Base metrics: use query builder for full safety
+                const query = buildAggregateQuery(queryBuilder, plan);
+                const { sql } = query.toSQLWithParams();
+                const data = await query.execute();
+                return {
+                    data,
+                    meta: {
+                        sql,
+                        timingMs: Date.now() - start,
+                        tenant: plan.tenant?.value,
+                    },
+                };
+            }
+            // Derived metrics: CTE query with formulas
+            const { sql, parameters } = buildDerivedSQL(queryBuilder, plan);
+            const data = await queryBuilder.rawQuery(sql, parameters);
+            const tenant = plan.input.kind === 'aggregate' ? plan.input.tenant?.value : undefined;
+            return {
+                data,
+                meta: {
+                    sql,
+                    timingMs: Date.now() - start,
+                    tenant,
+                },
+            };
+        },
+        /**
+         * Generate SQL without executing
+         */
+        async explain(plan) {
+            if (plan.kind === 'aggregate') {
+                return { sql: buildAggregateQuery(queryBuilder, plan).toSQLWithParams().sql };
+            }
+            return { sql: buildDerivedSQL(queryBuilder, plan).sql };
+        },
+    };
+}

package/dist/migrations/config/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_MIGRATIONS_OUT_DIR, DEFAULT_MIGRATIONS_PREFIX, DEFAULT_MIGRATIONS_TABLE, defineConfig, resolveClickHouseConfig, } from './types.js';
+export type { ClickHouseClusterConfig, ClickHouseMigrationDbCredentials, ClickHouseMigrationDirectoryConfig, HypequeryClickHouseConfig, MigrationFilePrefix, ResolvedHypequeryClickHouseConfig, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,uBAAuB,EACvB,gCAAgC,EAChC,kCAAkC,EAClC,yBAAyB,EACzB,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,YAAY,CAAC"}

package/dist/migrations/config/index.js

@@ -0,0 +1 @@
+export { DEFAULT_MIGRATIONS_OUT_DIR, DEFAULT_MIGRATIONS_PREFIX, DEFAULT_MIGRATIONS_TABLE, defineConfig, resolveClickHouseConfig, } from './types.js';

package/dist/migrations/config/types.d.ts

@@ -0,0 +1,45 @@
+export declare const DEFAULT_MIGRATIONS_OUT_DIR = "./migrations";
+export declare const DEFAULT_MIGRATIONS_TABLE = "_hypequery_migrations";
+export declare const DEFAULT_MIGRATIONS_PREFIX: "timestamp";
+export type MigrationFilePrefix = typeof DEFAULT_MIGRATIONS_PREFIX;
+export interface ClickHouseMigrationDirectoryConfig {
+    out: string;
+    table: string;
+    prefix: MigrationFilePrefix;
+}
+export interface ClickHouseMigrationDbCredentials {
+    host: string;
+    port?: number;
+    username: string;
+    password?: string;
+    database: string;
+    secure?: boolean;
+}
+export interface ClickHouseClusterConfig {
+    name: string;
+}
+export interface HypequeryClickHouseConfig {
+    dialect: 'clickhouse';
+    schema: string;
+    migrations?: Partial<ClickHouseMigrationDirectoryConfig>;
+    dbCredentials: ClickHouseMigrationDbCredentials;
+    cluster?: ClickHouseClusterConfig;
+}
+export interface ResolvedHypequeryClickHouseConfig extends Omit<HypequeryClickHouseConfig, 'migrations'> {
+    migrations: ClickHouseMigrationDirectoryConfig;
+}
+/**
+ * Defines a ClickHouse migration configuration while preserving literal TypeScript types.
+ *
+ * Use this from `hypequery.config.ts` so the CLI can load database credentials,
+ * schema entry points, and migration output settings from one typed object.
+ */
+export declare function defineConfig(config: HypequeryClickHouseConfig): HypequeryClickHouseConfig;
+/**
+ * Applies default migration settings to a user-provided ClickHouse config.
+ *
+ * This keeps CLI and programmatic callers aligned on the default output directory,
+ * migration table name, and timestamp-based file prefix strategy.
+ */
+export declare function resolveClickHouseConfig(config: HypequeryClickHouseConfig): ResolvedHypequeryClickHouseConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/migrations/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/migrations/config/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AACzD,eAAO,MAAM,wBAAwB,0BAA0B,CAAC;AAChE,eAAO,MAAM,yBAAyB,EAAG,WAAoB,CAAC;AAE9D,MAAM,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,CAAC;AAEnE,MAAM,WAAW,kCAAkC;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC,kCAAkC,CAAC,CAAC;IACzD,aAAa,EAAE,gCAAgC,CAAC;IAChD,OAAO,CAAC,EAAE,uBAAuB,CAAC;CACnC;AAED,MAAM,WAAW,iCACf,SAAQ,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC;IACrD,UAAU,EAAE,kCAAkC,CAAC;CAChD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,yBAAyB,GAAG,yBAAyB,CAEzF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,yBAAyB,GAChC,iCAAiC,CASnC"}

package/dist/migrations/config/types.js

@@ -0,0 +1,28 @@
+export const DEFAULT_MIGRATIONS_OUT_DIR = './migrations';
+export const DEFAULT_MIGRATIONS_TABLE = '_hypequery_migrations';
+export const DEFAULT_MIGRATIONS_PREFIX = 'timestamp';
+/**
+ * Defines a ClickHouse migration configuration while preserving literal TypeScript types.
+ *
+ * Use this from `hypequery.config.ts` so the CLI can load database credentials,
+ * schema entry points, and migration output settings from one typed object.
+ */
+export function defineConfig(config) {
+    return config;
+}
+/**
+ * Applies default migration settings to a user-provided ClickHouse config.
+ *
+ * This keeps CLI and programmatic callers aligned on the default output directory,
+ * migration table name, and timestamp-based file prefix strategy.
+ */
+export function resolveClickHouseConfig(config) {
+    return {
+        ...config,
+        migrations: {
+            out: config.migrations?.out ?? DEFAULT_MIGRATIONS_OUT_DIR,
+            table: config.migrations?.table ?? DEFAULT_MIGRATIONS_TABLE,
+            prefix: config.migrations?.prefix ?? DEFAULT_MIGRATIONS_PREFIX,
+        },
+    };
+}

package/dist/migrations/diff/diff.d.ts

@@ -0,0 +1,11 @@
+import type { Snapshot } from '../snapshot/types.js';
+import type { SnapshotDiffResult } from './types.js';
+/**
+ * Computes migration operations needed to move from one snapshot to another.
+ *
+ * The diff layer is deliberately SQL-free. It emits structured operations,
+ * warnings for potentially expensive changes, and unsupported-change diagnostics
+ * that the SQL renderer refuses to render automatically.
+ */
+export declare function diffSnapshots(previousSnapshot: Snapshot, nextSnapshot: Snapshot): SnapshotDiffResult;
+//# sourceMappingURL=diff.d.ts.map

package/dist/migrations/diff/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/migrations/diff/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAQV,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,GAAG,kBAAkB,CAqCpG"}