@hypequery/clickhouse 2.0.1 → 2.0.2

package/dist/core/tests/integration/test-data.json

@@ -0,0 +1,190 @@
+{
+    "test_table": [
+        {
+            "id": 1,
+            "name": "Product A",
+            "category": "A",
+            "price": 10.5,
+            "created_at": "2023-01-01 10:00:00",
+            "is_active": true,
+            "tags": [
+                "new",
+                "sale"
+            ],
+            "attributes": {
+                "color": "red",
+                "size": "M"
+            },
+            "optional_note": "Popular item",
+            "sku": "A-100",
+            "delivery_dates": [
+                "2023-01-05",
+                "2023-01-10"
+            ]
+        },
+        {
+            "id": 2,
+            "name": "Product B",
+            "category": "B",
+            "price": 20.75,
+            "created_at": "2023-01-02 12:30:00",
+            "is_active": true,
+            "tags": [
+                "featured"
+            ],
+            "attributes": {
+                "color": "blue",
+                "size": "L"
+            },
+            "optional_note": null,
+            "sku": "B-200",
+            "delivery_dates": [
+                "2023-01-06"
+            ]
+        },
+        {
+            "id": 3,
+            "name": "Product C",
+            "category": "A",
+            "price": 15.0,
+            "created_at": "2023-01-03 09:45:00",
+            "is_active": false,
+            "tags": [],
+            "attributes": {
+                "color": "green",
+                "size": "S"
+            },
+            "optional_note": "Backordered",
+            "sku": "C-300",
+            "delivery_dates": []
+        },
+        {
+            "id": 4,
+            "name": "Product D",
+            "category": "C",
+            "price": 8.25,
+            "created_at": "2023-01-04 15:15:00",
+            "is_active": true,
+            "tags": [
+                "clearance"
+            ],
+            "attributes": {
+                "color": "yellow",
+                "size": "XL"
+            },
+            "optional_note": null,
+            "sku": "D-400",
+            "delivery_dates": [
+                "2023-01-08"
+            ]
+        },
+        {
+            "id": 5,
+            "name": "Product E",
+            "category": "B",
+            "price": 30.0,
+            "created_at": "2023-01-05 11:20:00",
+            "is_active": true,
+            "tags": [
+                "premium",
+                "gift"
+            ],
+            "attributes": {
+                "color": "black",
+                "size": "M"
+            },
+            "optional_note": "Limited stock",
+            "sku": "E-500",
+            "delivery_dates": [
+                "2023-01-07",
+                "2023-01-09"
+            ]
+        },
+        {
+            "id": 6,
+            "name": "Product F",
+            "category": "D",
+            "price": 12.5,
+            "created_at": "2023-01-06 14:40:00",
+            "is_active": false,
+            "tags": [],
+            "attributes": {
+                "color": "white",
+                "size": "M"
+            },
+            "optional_note": null,
+            "sku": "F-600",
+            "delivery_dates": []
+        }
+    ],
+    "users": [
+        {
+            "id": 1,
+            "user_name": "john_doe",
+            "email": "john@example.com",
+            "status": "active",
+            "created_at": "2023-01-01"
+        },
+        {
+            "id": 2,
+            "user_name": "jane_smith",
+            "email": "jane@example.com",
+            "status": "active",
+            "created_at": "2023-01-02"
+        },
+        {
+            "id": 3,
+            "user_name": "bob_jones",
+            "email": "bob@example.com",
+            "status": "inactive",
+            "created_at": "2023-01-03"
+        }
+    ],
+    "orders": [
+        {
+            "id": 1,
+            "user_id": 1,
+            "product_id": 1,
+            "quantity": 2,
+            "total": 21.0,
+            "status": "completed",
+            "created_at": "2023-01-10"
+        },
+        {
+            "id": 2,
+            "user_id": 1,
+            "product_id": 3,
+            "quantity": 1,
+            "total": 15.0,
+            "status": "completed",
+            "created_at": "2023-01-11"
+        },
+        {
+            "id": 3,
+            "user_id": 2,
+            "product_id": 2,
+            "quantity": 3,
+            "total": 62.25,
+            "status": "pending",
+            "created_at": "2023-01-12"
+        },
+        {
+            "id": 4,
+            "user_id": 2,
+            "product_id": 5,
+            "quantity": 1,
+            "total": 30.0,
+            "status": "completed",
+            "created_at": "2023-01-13"
+        },
+        {
+            "id": 5,
+            "user_id": 3,
+            "product_id": 4,
+            "quantity": 2,
+            "total": 16.5,
+            "status": "cancelled",
+            "created_at": "2023-01-14"
+        }
+    ]
+}

package/dist/core/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAa9C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAgBvE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAc9C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAgBvE"}

package/dist/core/utils.js

@@ -6,7 +6,8 @@ export function escapeValue(value) {
         return value.toString();
     }
     else if (typeof value === 'string') {
-        return `'${value.replace(/'/g, "''")}'`;
+        const escaped = value.replace(/\\/g, '\\\\').replace(/'/g, "''");
+        return `'${escaped}'`;
     }
     else if (value instanceof Date) {
         return `'${value.toISOString()}'`;

package/dist/datasets.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { type SemanticBackend } from '@hypequery/datasets';
+import type { CreateQueryBuilderConfig } from './core/query-builder.js';
+import type { SchemaDefinition } from './core/types/builder-state.js';
+export type CreateBackendConfig = CreateQueryBuilderConfig;
+/**
+ * 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 declare function createBackend<Schema extends SchemaDefinition<Schema>>(config: CreateBackendConfig): SemanticBackend;
+//# sourceMappingURL=datasets.d.ts.map

package/dist/datasets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasets.d.ts","sourceRoot":"","sources":["../src/datasets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAuW3D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACnE,MAAM,EAAE,mBAAmB,GAC1B,eAAe,CAmDjB"}

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';