@hypequery/clickhouse 2.0.2 → 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/datasets.d.ts

@@ -9,18 +9,30 @@
  * - @hypequery/datasets: Owns semantic planning, validation, and execution protocol
  * - @hypequery/clickhouse: Implements SQL translation and execution for ClickHouse
  *
- * Usage:
+ * 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 { createBackend } from '@hypequery/clickhouse';
+ * 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: process.env.CLICKHOUSE_URL,
- *     username: process.env.CLICKHOUSE_USER,
- *     password: process.env.CLICKHOUSE_PASSWORD,
- *     database: process.env.CLICKHOUSE_DATABASE,
- *   })
+ *   backend: createBackend({ url, username, password, database }),
  * });
  * ```
  */

package/dist/datasets.d.ts.map

@@ -1 +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"}
+{"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

@@ -9,18 +9,30 @@
  * - @hypequery/datasets: Owns semantic planning, validation, and execution protocol
  * - @hypequery/clickhouse: Implements SQL translation and execution for ClickHouse
  *
- * Usage:
+ * 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 { createBackend } from '@hypequery/clickhouse';
+ * 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: process.env.CLICKHOUSE_URL,
- *     username: process.env.CLICKHOUSE_USER,
- *     password: process.env.CLICKHOUSE_PASSWORD,
- *     database: process.env.CLICKHOUSE_DATABASE,
- *   })
+ *   backend: createBackend({ url, username, password, database }),
  * });
  * ```
  */
@@ -282,7 +294,7 @@ function buildAggregateQuery(queryBuilder, plan) {
     }
     // Apply tenant filter (auto-injected)
     if (plan.tenant) {
-        qb = qb.where(plan.tenant.field, 'eq', plan.tenant.value);
+        qb = qb.where(plan.tenant.field, plan.tenant.operator, plan.tenant.value);
     }
     // Apply user filters
     qb = applyFilters(qb, plan.filters);
@@ -357,14 +369,16 @@ export function createBackend(config) {
                     meta: {
                         sql,
                         timingMs: Date.now() - start,
-                        tenant: plan.tenant?.value,
+                        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?.value : undefined;
+            const tenant = plan.input.kind === 'aggregate' && plan.input.tenant?.operator === 'eq'
+                ? plan.input.tenant.value
+                : undefined;
             return {
                 data,
                 meta: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/clickhouse",
-  "version": "2.0.2",
+  "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,