@hypequery/clickhouse 2.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @hypequery/clickhouse
 
-Typed ClickHouse query builder for hypequery.
+Typed query builder for ClickHouse.
 
 Use it when you want schema-aware queries, typed results, and a fluent API that stays close to how ClickHouse actually works.
 

package/dist/cli/generate-types.d.ts

@@ -1,5 +1,39 @@
+/**
+ * Minimal ClickHouse client surface needed by the type generator.
+ */
+export interface TypeGenerationClickHouseClient {
+  query(options: { query: string; format: 'JSONEachRow' }): Promise<{
+    json(): Promise<Array<Record<string, string>>>;
+  }>;
+}
+
+/**
+ * Options for generating TypeScript type definitions from ClickHouse.
+ */
+export interface GenerateTypesOptions {
+  includeTables?: string[];
+  excludeTables?: string[];
+  client?: TypeGenerationClickHouseClient;
+  generatedBy?: string;
+  includeUsageExample?: boolean;
+}
+
+/**
+ * Converts a ClickHouse type string to a TypeScript type string.
+ */
+export declare function clickhouseToTsType(type: string): string;
+
 /**
  * Generates TypeScript type definitions from the ClickHouse database schema
  * @param outputPath - The file path where the type definitions will be written
+ * @param options - Options for type generation
+ */
+export declare function generateTypes(outputPath: string, options?: GenerateTypesOptions): Promise<void>;
+
+/**
+ * Generates TypeScript type definition contents from a ClickHouse client.
  */
-export declare function generateTypes(outputPath: string): Promise<void>; 
+export declare function generateTypeDefinitions(
+  client: TypeGenerationClickHouseClient,
+  options?: GenerateTypesOptions,
+): Promise<string>;

package/dist/cli/generate-types.js

@@ -19,6 +19,9 @@ dotenv.config();
  * @typedef {Object} GenerateTypesOptions
  * @property {string[]} [includeTables] - List of tables to include
  * @property {string[]} [excludeTables] - List of tables to exclude
+ * @property {object} [client] - ClickHouse client to use instead of ClickHouseConnection
+ * @property {string} [generatedBy] - Package name to include in the generated file header
+ * @property {boolean} [includeUsageExample] - Whether to append the historical usage example
  */
 
 /**
@@ -28,8 +31,30 @@ dotenv.config();
  * @returns {Promise<void>}
  */
 export async function generateTypes(outputPath, options = {}) {
-  const client = ClickHouseConnection.getClient();
-  const { includeTables = [], excludeTables = [] } = options;
+  const client = options.client || ClickHouseConnection.getClient();
+  const typeDefinitions = await generateTypeDefinitions(client, options);
+
+  // Ensure the output directory exists
+  const outputDir = path.dirname(path.resolve(outputPath));
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // Write the file
+  await fs.writeFile(path.resolve(outputPath), typeDefinitions);
+}
+
+/**
+ * Generates TypeScript type definition contents from a ClickHouse client.
+ * @param {object} client - ClickHouse client with a query method
+ * @param {GenerateTypesOptions} [options] - Options for type generation
+ * @returns {Promise<string>}
+ */
+export async function generateTypeDefinitions(client, options = {}) {
+  const {
+    includeTables = [],
+    excludeTables = [],
+    generatedBy = '@hypequery/clickhouse',
+    includeUsageExample = true,
+  } = options;
 
   // Get all tables
   const tablesQuery = await client.query({
@@ -52,7 +77,7 @@ export async function generateTypes(outputPath, options = {}) {
     console.warn('Warning: No tables match the filter criteria. Check your include/exclude options.');
   }
 
-  let typeDefinitions = `// Generated by @hypequery/clickhouse
+  let typeDefinitions = `// Generated by ${generatedBy}
 // This file defines TypeScript types based on your ClickHouse database schema
 
 /**
@@ -95,8 +120,8 @@ export interface IntrospectedSchema {`;
     typeDefinitions += '\n}\n\n';
   }
 
-  // Add a usage example
-  typeDefinitions += `
+  if (includeUsageExample) {
+    typeDefinitions += `
 /**
  * Usage example:
  * 
@@ -114,13 +139,9 @@ export interface IntrospectedSchema {`;
  *   .execute();
  */
 `;
+  }
 
-  // Ensure the output directory exists
-  const outputDir = path.dirname(path.resolve(outputPath));
-  await fs.mkdir(outputDir, { recursive: true });
-
-  // Write the file
-  await fs.writeFile(path.resolve(outputPath), typeDefinitions);
+  return typeDefinitions;
 }
 
 /**

package/dist/cli/index.d.ts

@@ -1,2 +1,8 @@
 // CLI module type declarations
-export { generateTypes } from './generate-types'; 
+export {
+  clickhouseToTsType,
+  generateTypeDefinitions,
+  generateTypes,
+  type GenerateTypesOptions,
+  type TypeGenerationClickHouseClient,
+} from './generate-types';

package/dist/cli/index.js

@@ -1,2 +1,2 @@
 // CLI module exports
-export { generateTypes } from './generate-types.js'; 
+export { clickhouseToTsType, generateTypeDefinitions, generateTypes } from './generate-types.js';

package/dist/cli/type-parsing.js

@@ -33,10 +33,20 @@ function splitTopLevelArgs(value) {
 }
 
 function unwrapType(type, wrapperName) {
-  const prefix = `${wrapperName}(`;
-  return type.startsWith(prefix) && type.endsWith(')')
-    ? type.slice(prefix.length, -1)
-    : null;
+  // Trim whitespace and handle case-insensitive matching
+  const trimmedType = type.trim();
+  const lowerType = trimmedType.toLowerCase();
+  const lowerWrapper = wrapperName.toLowerCase();
+  const prefix = `${lowerWrapper}(`;
+
+  if (lowerType.startsWith(prefix) && trimmedType.endsWith(')')) {
+    // Extract inner type, preserving original case
+    const innerStart = trimmedType.indexOf('(') + 1;
+    const innerEnd = trimmedType.lastIndexOf(')');
+    return trimmedType.slice(innerStart, innerEnd).trim();
+  }
+
+  return null;
 }
 
 function getPrimitiveTsType(type) {
@@ -45,6 +55,8 @@ function getPrimitiveTsType(type) {
   switch (lowerType) {
     case 'string':
     case 'uuid':
+    case 'ipv4':
+    case 'ipv6':
       return 'string';
     case 'int8':
     case 'int16':
@@ -72,9 +84,15 @@ function getPrimitiveTsType(type) {
     case 'bool':
     case 'boolean':
       return 'boolean';
+    case 'json':
+      return 'unknown';
     default:
       if (type.startsWith('FixedString(')) return 'string';
       if (type.startsWith('Decimal(')) return 'number';
+      if (type.startsWith('Decimal32(')) return 'number';
+      if (type.startsWith('Decimal64(')) return 'number';
+      if (type.startsWith('Decimal128(')) return 'number';
+      if (type.startsWith('Decimal256(')) return 'number';
       if (type.startsWith('DateTime64(')) return 'string';
       if (type.startsWith('DateTime(')) return 'string';
       if (type.startsWith('Enum8(')) return 'string';

package/dist/core/dialects/clickhouse-dialect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse-dialect.d.ts","sourceRoot":"","sources":["../../../src/core/dialects/clickhouse-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAExE,qBAAa,iBAAkB,YAAW,UAAU;IAClD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,SAAS,CAAsB;IAEvC,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,mBAAmB,GAAG,aAAa;IA6D3F,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAQ5E,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;CAK1D"}
+{"version":3,"file":"clickhouse-dialect.d.ts","sourceRoot":"","sources":["../../../src/core/dialects/clickhouse-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAExE,qBAAa,iBAAkB,YAAW,UAAU;IAClD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,SAAS,CAAsB;IAEvC,YAAY,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,mBAAmB,GAAG,aAAa;IA6D3F,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAQ5E,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;CAK1D"}

package/dist/core/dialects/clickhouse-dialect.js

@@ -1,4 +1,5 @@
 import { SQLFormatter } from '../formatters/sql-formatter.js';
+import { formatIntervalLiteral } from '../utils/sql-literals.js';
 export class ClickHouseDialect {
     name = 'clickhouse';
     formatter = new SQLFormatter();
@@ -52,7 +53,7 @@ export class ClickHouseDialect {
     }
     formatTimeInterval(column, interval, method) {
         if (method === 'toStartOfInterval') {
-            return `${method}(${column}, INTERVAL ${interval})`;
+            return `${method}(${column}, INTERVAL ${formatIntervalLiteral(interval)})`;
         }
         return `${method}(${column})`;
     }

package/dist/core/tests/integration/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/core/tests/integration/setup.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,SAAS,EASV,MAAM,kDAAkD,CAAC;AA4B1D,eAAO,MAAM,wBAAwB;;;;;;EAyBpC,CAAC;AAGF,eAAO,MAAM,2BAA2B,yGAevC,CAAC;AAGF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,OAAO,CAE/E,CAAC;AAGF,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CAO7D,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAC5B,oBAAgB,EAChB,sBAAoB,KACnB,OAAO,CAAC,IAAI,CAOd,CAAC;AAGF,eAAO,MAAM,uBAAuB,QAAa,OAAO,CAAC,IAAI,CAU5D,CAAC;AAGF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,KAAK,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;QACnB,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,SAAS,EAAE,CAAC;AAKxE,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,IAAI,CAuBtD,CAAC"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/core/tests/integration/setup.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,SAAS,EAQV,MAAM,kDAAkD,CAAC;AA4B1D,eAAO,MAAM,wBAAwB;;;;;;EAyBpC,CAAC;AAGF,eAAO,MAAM,2BAA2B,yGAevC,CAAC;AAGF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,OAAO,CAE/E,CAAC;AAGF,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CAO7D,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAC5B,oBAAgB,EAChB,sBAAoB,KACnB,OAAO,CAAC,IAAI,CAOd,CAAC;AAGF,eAAO,MAAM,uBAAuB,QAAa,OAAO,CAAC,IAAI,CAU5D,CAAC;AAGF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,KAAK,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;QACnB,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,SAAS,EAAE,CAAC;AAKxE,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,IAAI,CAuBtD,CAAC"}

package/dist/core/tests/integration/setup.js

@@ -1,8 +1,6 @@
 import { ClickHouseConnection } from '../../connection.js';
 import { logger as hypeQueryLogger } from '../../utils/logger.js';
-import { CLICKHOUSE_CONTAINER_NAME, TEST_CONNECTION_CONFIG, TEST_DATA, detectComposeCommand, ensureDockerDaemon, isContainerRunning as sharedIsContainerRunning, seedClickHouseDatabase, startClickHouseContainer as sharedStartClickHouseContainer, stopClickHouseContainer as sharedStopClickHouseContainer, waitForClickHouse as sharedWaitForClickHouse,
-// @ts-expect-error: shared test harness is plain JS
- } from '../../../../../../testing/clickhouse/harness.mjs';
+import { CLICKHOUSE_CONTAINER_NAME, TEST_CONNECTION_CONFIG, TEST_DATA, detectComposeCommand, ensureDockerDaemon, isContainerRunning as sharedIsContainerRunning, seedClickHouseDatabase, startClickHouseContainer as sharedStartClickHouseContainer, stopClickHouseContainer as sharedStopClickHouseContainer, waitForClickHouse as sharedWaitForClickHouse, } from '../../../../../../testing/clickhouse/harness.mjs';
 // Disable the hypequery logger to prevent "logs after tests" errors
 // This must be done early in the setup, before any queries run
 hypeQueryLogger.configure({ enabled: false });

package/dist/core/utils/sql-expressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql-expressions.d.ts","sourceRoot":"","sources":["../../../src/core/utils/sql-expressions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sql-expressions.d.ts","sourceRoot":"","sources":["../../../src/core/utils/sql-expressions.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/sql-expressions.js

@@ -1,3 +1,4 @@
+import { formatIntervalLiteral, quoteStringLiteral } from './sql-literals.js';
 /**
  * Creates a raw SQL expression
  * @param sql The SQL expression string
@@ -34,17 +35,18 @@ export function toDateTime(field, alias) {
 }
 export function formatDateTime(field, format, options = {}) {
     const { timezone, alias } = options;
-    let sql = `formatDateTime(${field}, '${format}'`;
+    let sql = `formatDateTime(${field}, ${quoteStringLiteral(format)}`;
     if (timezone) {
-        sql += `, '${timezone}'`;
+        sql += `, ${quoteStringLiteral(timezone)}`;
     }
     sql += ')';
     return alias ? rawAs(sql, alias) : raw(sql);
 }
 export function toStartOfInterval(field, interval, alias) {
+    const sql = `toStartOfInterval(${field}, INTERVAL ${formatIntervalLiteral(interval)})`;
     return alias
-        ? rawAs(`toStartOfInterval(${field}, INTERVAL ${interval})`, alias)
-        : raw(`toStartOfInterval(${field}, INTERVAL ${interval})`);
+        ? rawAs(sql, alias)
+        : raw(sql);
 }
 function toStartOfUnit(functionName, field, alias) {
     return alias

package/dist/core/utils/sql-literals.d.ts

@@ -0,0 +1,3 @@
+export declare function formatIntervalLiteral(interval: string): string;
+export declare function quoteStringLiteral(value: string): string;
+//# sourceMappingURL=sql-literals.d.ts.map

package/dist/core/utils/sql-literals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-literals.d.ts","sourceRoot":"","sources":["../../../src/core/utils/sql-literals.ts"],"names":[],"mappings":"AA2BA,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAc9D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/core/utils/sql-literals.js

@@ -0,0 +1,39 @@
+const INTERVAL_UNITS = {
+    second: 'SECOND',
+    seconds: 'SECOND',
+    minute: 'MINUTE',
+    minutes: 'MINUTE',
+    hour: 'HOUR',
+    hours: 'HOUR',
+    day: 'DAY',
+    days: 'DAY',
+    week: 'WEEK',
+    weeks: 'WEEK',
+    month: 'MONTH',
+    months: 'MONTH',
+    quarter: 'QUARTER',
+    quarters: 'QUARTER',
+    year: 'YEAR',
+    years: 'YEAR',
+    millisecond: 'MILLISECOND',
+    milliseconds: 'MILLISECOND',
+    microsecond: 'MICROSECOND',
+    microseconds: 'MICROSECOND',
+    nanosecond: 'NANOSECOND',
+    nanoseconds: 'NANOSECOND',
+};
+const INTERVAL_PATTERN = /^(\d+)\s+([a-z]+)$/i;
+export function formatIntervalLiteral(interval) {
+    const normalized = interval.trim();
+    const match = normalized.match(INTERVAL_PATTERN);
+    const unit = match ? INTERVAL_UNITS[match[2].toLowerCase()] : undefined;
+    if (!match || !unit) {
+        throw new Error(`Invalid time interval: "${interval}". Expected "<number> <unit>" where unit is ` +
+            'one of second, minute, hour, day, week, month, quarter, year, millisecond, microsecond, nanosecond ' +
+            '(e.g. "1 day", "15 minute").');
+    }
+    return `${match[1]} ${unit}`;
+}
+export function quoteStringLiteral(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
+}

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,53 @@
+/**
+ * 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 (recommended): pass the query builder you already use for
+ * hand-written queries, so semantic and ad hoc queries share one connection.
+ * ```ts
+ * import { createDatasetClient } from '@hypequery/datasets';
+ * import { createQueryBuilder } from '@hypequery/clickhouse';
+ *
+ * const db = createQueryBuilder({
+ *   url: process.env.CLICKHOUSE_URL,
+ *   username: process.env.CLICKHOUSE_USER,
+ *   password: process.env.CLICKHOUSE_PASSWORD,
+ *   database: process.env.CLICKHOUSE_DATABASE,
+ * });
+ *
+ * const analytics = createDatasetClient({ queryBuilder: db });
+ * ```
+ *
+ * Advanced: `createBackend` exposes the database-agnostic SemanticBackend
+ * protocol directly. Reach for it when you want a standalone backend instance
+ * rather than sharing a query builder.
+ * ```ts
+ * import { createBackend } from '@hypequery/clickhouse/datasets';
+ *
+ * const analytics = createDatasetClient({
+ *   backend: createBackend({ url, username, password, 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,CAqDjB"}

package/dist/datasets.js

@@ -0,0 +1,401 @@
+/**
+ * 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 (recommended): pass the query builder you already use for
+ * hand-written queries, so semantic and ad hoc queries share one connection.
+ * ```ts
+ * import { createDatasetClient } from '@hypequery/datasets';
+ * import { createQueryBuilder } from '@hypequery/clickhouse';
+ *
+ * const db = createQueryBuilder({
+ *   url: process.env.CLICKHOUSE_URL,
+ *   username: process.env.CLICKHOUSE_USER,
+ *   password: process.env.CLICKHOUSE_PASSWORD,
+ *   database: process.env.CLICKHOUSE_DATABASE,
+ * });
+ *
+ * const analytics = createDatasetClient({ queryBuilder: db });
+ * ```
+ *
+ * Advanced: `createBackend` exposes the database-agnostic SemanticBackend
+ * protocol directly. Reach for it when you want a standalone backend instance
+ * rather than sharing a query builder.
+ * ```ts
+ * import { createBackend } from '@hypequery/clickhouse/datasets';
+ *
+ * const analytics = createDatasetClient({
+ *   backend: createBackend({ url, username, password, 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, plan.tenant.operator, 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?.operator === 'eq' ? plan.tenant.value : undefined,
+                    },
+                };
+            }
+            // 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?.operator === 'eq'
+                ? 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/clickhouse",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "ClickHouse typescript query builder",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,6 +14,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./datasets": {
+      "types": "./dist/datasets.d.ts",
+      "import": "./dist/datasets.js",
+      "require": "./dist/datasets.js"
+    },
     "./cli": {
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js",
@@ -33,11 +38,15 @@
     "dotenv": "^16.0.0"
   },
   "peerDependencies": {
-    "@clickhouse/client-web": "^0.2.0 || ^1.0.0"
+    "@clickhouse/client-web": "^0.2.0 || ^1.0.0",
+    "@hypequery/datasets": "^0.1.0 || ^0.2.0"
   },
   "peerDependenciesMeta": {
     "@clickhouse/client-web": {
       "optional": true
+    },
+    "@hypequery/datasets": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -51,7 +60,8 @@
     "typedoc-plugin-markdown": "^4.6.0",
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^2.1.6",
-    "vitest": "^2.1.6"
+    "vitest": "^2.1.6",
+    "@hypequery/datasets": "0.2.0"
   },
   "ts-node": {
     "esm": true,