@hypequery/clickhouse 2.0.1 → 2.0.2

package/dist/migrations/sql/render.js

@@ -0,0 +1,347 @@
+import { createMigrationPlan, isMigrationPlan } from '../plan/index.js';
+/**
+ * Renders a snapshot diff into reviewable migration artifacts.
+ *
+ * The renderer produces forward SQL, best-effort reverse SQL, and metadata. It
+ * also sequences dependent materialized views around table mutations so stored
+ * view SELECT definitions are dropped and recreated with the target snapshot.
+ */
+export function renderMigrationArtifacts(input, options) {
+    const plan = isMigrationPlan(input) ? input : createMigrationPlan(input);
+    assertNoPlanBlockers(plan);
+    const upStatements = [];
+    const downStatements = [];
+    const consumedViewNames = new Set();
+    const renderedOperations = [];
+    let containsManualSteps = false;
+    for (const plannedOperation of normalizeOperationsForRendering(plan.operations)) {
+        const { operation } = plannedOperation;
+        if (isMaterializedViewOperation(operation) && consumedViewNames.has(getOperationViewName(operation))) {
+            continue;
+        }
+        renderedOperations.push({
+            kind: operation.kind,
+            classification: plannedOperation.classification,
+        });
+        upStatements.push(...renderOperationUp(operation, { plan, cluster: options.cluster }, consumedViewNames));
+        const renderedDown = renderOperationDown(operation, {
+            previousSnapshot: plan.previousSnapshot,
+            nextSnapshot: plan.nextSnapshot,
+            cluster: options.cluster,
+        }, consumedViewNames);
+        downStatements.unshift(...renderedDown.statements);
+        containsManualSteps = containsManualSteps || renderedDown.manual;
+    }
+    return {
+        upSql: joinStatements(upStatements),
+        downSql: joinStatements(downStatements),
+        meta: {
+            name: options.name,
+            timestamp: options.timestamp,
+            operations: renderedOperations,
+            sourceSnapshotHash: plan.sourceSnapshotHash,
+            targetSnapshotHash: plan.targetSnapshotHash,
+            custom: false,
+            unsafe: plan.diagnostics.some(diagnostic => diagnostic.level === 'warning') ||
+                plan.blockers.length > 0 ||
+                containsManualSteps,
+            containsManualSteps,
+        },
+        plan,
+    };
+}
+function renderOperationUp(operation, context, consumedViewNames) {
+    switch (operation.kind) {
+        case 'CreateTable':
+            return [renderCreateTable(operation.table, context.cluster)];
+        case 'DropTable':
+            return [renderDropTable(operation.tableName, context.cluster)];
+        case 'AddColumn':
+            return [renderAlterTableAddColumn(operation.tableName, operation.column, context.cluster)];
+        case 'DropColumn':
+            return [renderAlterTableDropColumn(operation.tableName, operation.columnName, context.cluster)];
+        case 'ModifyColumnDefault':
+        case 'ModifyColumnType': {
+            const nextColumn = requireColumn(context.plan.nextSnapshot, operation.tableName, operation.columnName);
+            return [renderAlterTableModifyColumn(operation.tableName, nextColumn, context.cluster)];
+        }
+        case 'CreateMaterializedView':
+            return [renderCreateMaterializedView({ view: operation.view, cluster: context.cluster })];
+        case 'DropMaterializedView':
+            return [renderDropMaterializedView(operation.viewName, context.cluster)];
+        case 'RecreateMaterializedView':
+            return [
+                renderDropMaterializedView(operation.previousView.name, context.cluster),
+                renderCreateMaterializedView({ view: operation.nextView, cluster: context.cluster }),
+            ];
+        case 'AlterTableWithDependentViews':
+            return renderAlterTableWithDependentViewsUp(operation, context, consumedViewNames);
+        default: {
+            const exhaustiveCheck = operation;
+            return exhaustiveCheck;
+        }
+    }
+}
+function renderOperationDown(operation, lookup, consumedViewNames) {
+    switch (operation.kind) {
+        case 'CreateTable':
+            return { statements: [renderDropTable(operation.table.name, lookup.cluster)], manual: false };
+        case 'DropTable':
+            return { statements: [manualDownComment(`recreate dropped table "${operation.tableName}" manually`)], manual: true };
+        case 'AddColumn':
+            return {
+                statements: [renderAlterTableDropColumn(operation.tableName, operation.column.name, lookup.cluster)],
+                manual: false,
+            };
+        case 'DropColumn':
+            return {
+                statements: [manualDownComment(`recreate dropped column "${operation.tableName}.${operation.columnName}" manually`)],
+                manual: true,
+            };
+        case 'ModifyColumnDefault': {
+            const previousColumn = requireColumn(lookup.previousSnapshot, operation.tableName, operation.columnName);
+            return {
+                statements: [renderAlterTableModifyColumn(operation.tableName, previousColumn, lookup.cluster)],
+                manual: false,
+            };
+        }
+        case 'ModifyColumnType':
+            return {
+                statements: [manualDownComment(`revert type change for "${operation.tableName}.${operation.columnName}" manually`)],
+                manual: true,
+            };
+        case 'CreateMaterializedView':
+            return { statements: [renderDropMaterializedView(operation.view.name, lookup.cluster)], manual: false };
+        case 'DropMaterializedView': {
+            const previousView = requireMaterializedView(lookup.previousSnapshot, operation.viewName);
+            return {
+                statements: [renderCreateMaterializedView({ view: previousView, cluster: lookup.cluster })],
+                manual: false,
+            };
+        }
+        case 'RecreateMaterializedView':
+            return {
+                statements: [
+                    renderDropMaterializedView(operation.nextView.name, lookup.cluster),
+                    renderCreateMaterializedView({ view: operation.previousView, cluster: lookup.cluster }),
+                ],
+                manual: false,
+            };
+        case 'AlterTableWithDependentViews':
+            return renderAlterTableWithDependentViewsDown(operation, lookup, consumedViewNames);
+        default: {
+            const exhaustiveCheck = operation;
+            return exhaustiveCheck;
+        }
+    }
+}
+function renderAlterTableWithDependentViewsUp(operation, context, consumedViewNames) {
+    const statements = [];
+    for (const viewName of operation.dependentViewNames) {
+        statements.push(renderDropMaterializedView(viewName, context.cluster));
+        consumedViewNames.add(viewName);
+    }
+    for (const nestedOperation of normalizeTableMutationOperations(operation.operations)) {
+        statements.push(...renderOperationUp(nestedOperation, context, consumedViewNames));
+    }
+    for (const viewName of operation.dependentViewNames) {
+        statements.push(renderCreateMaterializedView({
+            view: requireMaterializedView(context.plan.nextSnapshot, viewName),
+            cluster: context.cluster,
+        }));
+    }
+    return statements;
+}
+function renderAlterTableWithDependentViewsDown(operation, lookup, consumedViewNames) {
+    const statements = [];
+    let manual = false;
+    for (const viewName of operation.dependentViewNames) {
+        statements.push(renderDropMaterializedView(viewName, lookup.cluster));
+        consumedViewNames.add(viewName);
+    }
+    for (const nestedOperation of [...normalizeTableMutationOperations(operation.operations)].reverse()) {
+        const rendered = renderOperationDown(nestedOperation, lookup, consumedViewNames);
+        statements.push(...rendered.statements);
+        manual = manual || rendered.manual;
+    }
+    for (const viewName of operation.dependentViewNames) {
+        statements.push(renderCreateMaterializedView({
+            view: requireMaterializedView(lookup.previousSnapshot, viewName),
+            cluster: lookup.cluster,
+        }));
+    }
+    return { statements, manual };
+}
+function renderCreateTable(table, cluster) {
+    const columns = table.columns
+        .map(column => `  ${quoteIdentifier(column.name)} ${column.type}${renderColumnDefault(column)}`)
+        .join(',\n');
+    const settings = Object.keys(table.settings).length > 0
+        ? `\nSETTINGS ${Object.entries(table.settings).map(([key, value]) => `${key} = ${value}`).join(', ')}`
+        : '';
+    return [
+        `CREATE TABLE ${quoteIdentifier(table.name)}${renderClusterClause(cluster)} (`,
+        columns,
+        `) ENGINE = ${renderTableEngine(table)}${settings};`,
+    ].join('\n');
+}
+function renderDropTable(tableName, cluster) {
+    return `DROP TABLE ${quoteIdentifier(tableName)}${renderClusterClause(cluster)};`;
+}
+function renderAlterTableAddColumn(tableName, column, cluster) {
+    return `ALTER TABLE ${quoteIdentifier(tableName)}${renderClusterClause(cluster)} ADD COLUMN ` +
+        `${quoteIdentifier(column.name)} ${column.type}${renderColumnDefault(column)};`;
+}
+function renderAlterTableDropColumn(tableName, columnName, cluster) {
+    return `ALTER TABLE ${quoteIdentifier(tableName)}${renderClusterClause(cluster)} DROP COLUMN ${quoteIdentifier(columnName)};`;
+}
+function renderAlterTableModifyColumn(tableName, column, cluster) {
+    return `ALTER TABLE ${quoteIdentifier(tableName)}${renderClusterClause(cluster)} MODIFY COLUMN ` +
+        `${quoteIdentifier(column.name)} ${column.type}${renderColumnDefault(column)};`;
+}
+function renderCreateMaterializedView(context) {
+    const toClause = context.view.to ? `\nTO ${quoteIdentifier(context.view.to)}` : '';
+    return [
+        `CREATE MATERIALIZED VIEW ${quoteIdentifier(context.view.name)}${renderClusterClause(context.cluster)}${toClause} AS`,
+        context.view.select,
+        ';',
+    ].join('\n');
+}
+function renderDropMaterializedView(viewName, cluster) {
+    return `DROP TABLE ${quoteIdentifier(viewName)}${renderClusterClause(cluster)};`;
+}
+function renderTableEngine(table) {
+    const parts = [table.engine.type, `ORDER BY (${table.engine.orderBy.join(', ')})`];
+    if (table.engine.partitionBy) {
+        parts.push(`PARTITION BY ${table.engine.partitionBy}`);
+    }
+    if (table.engine.primaryKey.length > 0) {
+        parts.push(`PRIMARY KEY (${table.engine.primaryKey.join(', ')})`);
+    }
+    if (table.engine.sampleBy) {
+        parts.push(`SAMPLE BY ${table.engine.sampleBy}`);
+    }
+    return parts.join('\n');
+}
+function renderColumnDefault(column) {
+    return column.default !== undefined ? ` DEFAULT ${renderDefaultValue(column.default)}` : '';
+}
+function renderClusterClause(cluster) {
+    return cluster ? ` ON CLUSTER ${quoteIdentifier(cluster)}` : '';
+}
+function quoteIdentifier(identifier) {
+    if (identifier.trim() === '') {
+        throw new Error('Invalid ClickHouse identifier: identifiers must not be empty.');
+    }
+    return `\`${identifier.replace(/`/g, '``')}\``;
+}
+function requireColumn(snapshot, tableName, columnName) {
+    const table = snapshot.tables.find(candidate => candidate.name === tableName);
+    if (!table) {
+        throw new Error(`Table "${tableName}" not found in snapshot.`);
+    }
+    const column = table.columns.find(candidate => candidate.name === columnName);
+    if (!column) {
+        throw new Error(`Column "${tableName}.${columnName}" not found in snapshot.`);
+    }
+    return column;
+}
+function requireMaterializedView(snapshot, viewName) {
+    const view = snapshot.materializedViews.find(candidate => candidate.name === viewName);
+    if (!view) {
+        throw new Error(`Materialized view "${viewName}" not found in snapshot.`);
+    }
+    return view;
+}
+function isMaterializedViewOperation(operation) {
+    return operation.kind === 'DropMaterializedView' ||
+        operation.kind === 'CreateMaterializedView' ||
+        operation.kind === 'RecreateMaterializedView';
+}
+function getOperationViewName(operation) {
+    switch (operation.kind) {
+        case 'DropMaterializedView':
+            return operation.viewName;
+        case 'CreateMaterializedView':
+            return operation.view.name;
+        case 'RecreateMaterializedView':
+            return operation.nextView.name;
+        default: {
+            const exhaustiveCheck = operation;
+            return exhaustiveCheck;
+        }
+    }
+}
+function manualDownComment(message) {
+    return `-- MANUAL STEP REQUIRED: ${message}`;
+}
+function joinStatements(statements) {
+    return statements.join('\n\n').trim();
+}
+function renderDefaultValue(defaultValue) {
+    if (defaultValue.kind === 'sql') {
+        return defaultValue.value;
+    }
+    if (defaultValue.value === null) {
+        return 'NULL';
+    }
+    if (typeof defaultValue.value === 'number') {
+        return String(defaultValue.value);
+    }
+    if (typeof defaultValue.value === 'boolean') {
+        return defaultValue.value ? 'true' : 'false';
+    }
+    return `'${escapeStringLiteral(defaultValue.value)}'`;
+}
+function escapeStringLiteral(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/\0/g, '\\0')
+        .replace(/\x08/g, '\\b')
+        .replace(/\f/g, '\\f')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(/\v/g, '\\v')
+        .replace(/'/g, "\\'");
+}
+function normalizeOperationsForRendering(operations) {
+    return operations.map(plannedOperation => {
+        if (plannedOperation.operation.kind !== 'AlterTableWithDependentViews') {
+            return plannedOperation;
+        }
+        return {
+            ...plannedOperation,
+            operation: {
+                ...plannedOperation.operation,
+                operations: normalizeTableMutationOperations(plannedOperation.operation.operations),
+            },
+        };
+    }).filter(plannedOperation => {
+        if (plannedOperation.operation.kind !== 'ModifyColumnDefault') {
+            return true;
+        }
+        const operation = plannedOperation.operation;
+        return !operations.some(candidate => candidate.operation.kind === 'ModifyColumnType' &&
+            candidate.operation.tableName === operation.tableName &&
+            candidate.operation.columnName === operation.columnName);
+    });
+}
+function normalizeTableMutationOperations(operations) {
+    return operations.filter(operation => {
+        if (operation.kind !== 'ModifyColumnDefault') {
+            return true;
+        }
+        return !operations.some(candidate => candidate.kind === 'ModifyColumnType' &&
+            candidate.tableName === operation.tableName &&
+            candidate.columnName === operation.columnName);
+    });
+}
+function assertNoPlanBlockers(plan) {
+    if (plan.blockers.length === 0) {
+        return;
+    }
+    throw new Error('Cannot render migration with unsupported changes:\n' +
+        plan.blockers.map(blocker => `- ${blocker.message}`).join('\n') +
+        '\n\nUse a custom SQL migration for this change, or split the schema evolution into supported steps.');
+}

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

@@ -0,0 +1,53 @@
+import type { MigrationOperation, SnapshotDiffResult } from '../diff/types.js';
+import type { MigrationOperationClassification, MigrationPlan, MigrationPlanInput } from '../plan/types.js';
+import type { Snapshot, SnapshotMaterializedView } from '../snapshot/types.js';
+export interface MigrationMeta {
+    name: string;
+    timestamp: string;
+    operations: Array<{
+        kind: MigrationOperation['kind'];
+        classification: MigrationOperationClassification;
+    }>;
+    sourceSnapshotHash: string;
+    targetSnapshotHash: string;
+    custom: boolean;
+    unsafe: boolean;
+    containsManualSteps: boolean;
+}
+export interface RenderMigrationArtifactsOptions {
+    name: string;
+    timestamp: string;
+    cluster?: string;
+}
+export interface RenderMigrationArtifactsResult {
+    upSql: string;
+    downSql: string;
+    meta: MigrationMeta;
+    plan: MigrationPlan;
+}
+export interface RenderSqlContext {
+    plan: MigrationPlan;
+    cluster?: string;
+}
+export interface MaterializedViewRenderContext {
+    view: SnapshotMaterializedView;
+    cluster?: string;
+}
+export interface WriteMigrationArtifactsOptions {
+    outDir: string;
+    migrationName: string;
+    artifacts: RenderMigrationArtifactsResult;
+}
+export interface WriteMigrationArtifactsResult {
+    migrationDir: string;
+    upPath: string;
+    downPath: string;
+    metaPath: string;
+    planPath: string;
+}
+export interface SnapshotLookup {
+    previousSnapshot: Snapshot;
+    nextSnapshot: Snapshot;
+}
+export type RenderMigrationArtifactsInput = MigrationPlanInput | SnapshotDiffResult;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/migrations/sql/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EACV,gCAAgC,EAChC,aAAa,EACb,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACjC,cAAc,EAAE,gCAAgC,CAAC;KAClD,CAAC,CAAC;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,wBAAwB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,8BAA8B,CAAC;CAC3C;AAED,MAAM,WAAW,6BAA6B;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,QAAQ,CAAC;IAC3B,YAAY,EAAE,QAAQ,CAAC;CACxB;AAED,MAAM,MAAM,6BAA6B,GAAG,kBAAkB,GAAG,kBAAkB,CAAC"}

package/dist/migrations/sql/types.js

@@ -0,0 +1 @@
+export {};

package/dist/migrations/sql/write.d.ts

@@ -0,0 +1,10 @@
+import type { WriteMigrationArtifactsOptions, WriteMigrationArtifactsResult } from './types.js';
+/**
+ * Writes rendered migration artifacts to a migration directory.
+ *
+ * The migration name must be a single safe path segment. The writer creates
+ * `up.sql`, `down.sql`, `meta.json`, and `plan.json` files under
+ * `outDir/migrationName`.
+ */
+export declare function writeMigrationArtifacts(options: WriteMigrationArtifactsOptions): Promise<WriteMigrationArtifactsResult>;
+//# sourceMappingURL=write.d.ts.map

package/dist/migrations/sql/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/migrations/sql/write.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,8BAA8B,EAC9B,6BAA6B,EAC9B,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,6BAA6B,CAAC,CAuBxC"}

package/dist/migrations/sql/write.js

@@ -0,0 +1,35 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Writes rendered migration artifacts to a migration directory.
+ *
+ * The migration name must be a single safe path segment. The writer creates
+ * `up.sql`, `down.sql`, `meta.json`, and `plan.json` files under
+ * `outDir/migrationName`.
+ */
+export async function writeMigrationArtifacts(options) {
+    assertValidMigrationName(options.migrationName);
+    const migrationDir = path.join(options.outDir, options.migrationName);
+    await mkdir(migrationDir, { recursive: true });
+    const upPath = path.join(migrationDir, 'up.sql');
+    const downPath = path.join(migrationDir, 'down.sql');
+    const metaPath = path.join(migrationDir, 'meta.json');
+    const planPath = path.join(migrationDir, 'plan.json');
+    await writeFile(upPath, `${options.artifacts.upSql}\n`, 'utf8');
+    await writeFile(downPath, `${options.artifacts.downSql}\n`, 'utf8');
+    await writeFile(metaPath, `${JSON.stringify(options.artifacts.meta, null, 2)}\n`, 'utf8');
+    await writeFile(planPath, `${JSON.stringify(options.artifacts.plan, null, 2)}\n`, 'utf8');
+    return {
+        migrationDir,
+        upPath,
+        downPath,
+        metaPath,
+        planPath,
+    };
+}
+function assertValidMigrationName(migrationName) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(migrationName)) {
+        throw new Error(`Invalid migration name "${migrationName}". ` +
+            'Migration names must be a single path segment containing only letters, numbers, underscores, and hyphens.');
+    }
+}

package/dist/semantic-backend.d.ts

@@ -0,0 +1,7 @@
+import { type SemanticBackend } from '@hypequery/datasets';
+export interface ClickHouseSemanticQueryBuilder {
+    table(tableName: string): any;
+    rawQuery<TResult = any>(sql: string, params?: unknown[]): Promise<TResult[]>;
+}
+export declare function createClickHouseSemanticBackendFromQueryBuilder(queryBuilder: ClickHouseSemanticQueryBuilder): SemanticBackend;
+//# sourceMappingURL=semantic-backend.d.ts.map

package/dist/semantic-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-backend.d.ts","sourceRoot":"","sources":["../src/semantic-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EAGrB,MAAM,qBAAqB,CAAC;AAU7B,MAAM,WAAW,8BAA8B;IAC7C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC;IAC9B,QAAQ,CAAC,OAAO,GAAG,GAAG,EACpB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACvB;AAsMD,wBAAgB,+CAA+C,CAC7D,YAAY,EAAE,8BAA8B,GAC3C,eAAe,CAuBjB"}

package/dist/semantic-backend.js

@@ -0,0 +1,208 @@
+const GRAIN_FUNCTIONS = {
+    day: 'toStartOfDay',
+    week: 'toStartOfWeek',
+    month: 'toStartOfMonth',
+    quarter: 'toStartOfQuarter',
+    year: 'toStartOfYear',
+};
+function renderGrain(field, unit) {
+    return `${GRAIN_FUNCTIONS[unit]}(${field})`;
+}
+function applyFilters(builder, filters) {
+    let qb = builder;
+    for (const filter of filters) {
+        qb = qb.where(filter.field, filter.operator, filter.value);
+    }
+    return qb;
+}
+function renderLiteral(value) {
+    if (value === null)
+        return 'NULL';
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? '1' : '0';
+    if (value instanceof Date)
+        return `'${value.toISOString().replace(/'/g, "''")}'`;
+    if (typeof value === 'string')
+        return `'${value.replace(/'/g, "''")}'`;
+    throw new Error(`Unsupported filter literal value: ${String(value)}.`);
+}
+function renderFilterCondition(filter) {
+    switch (filter.operator) {
+        case 'eq':
+            return `${filter.field} = ${renderLiteral(filter.value)}`;
+        case 'neq':
+            return `${filter.field} != ${renderLiteral(filter.value)}`;
+        case 'gt':
+            return `${filter.field} > ${renderLiteral(filter.value)}`;
+        case 'gte':
+            return `${filter.field} >= ${renderLiteral(filter.value)}`;
+        case 'lt':
+            return `${filter.field} < ${renderLiteral(filter.value)}`;
+        case 'lte':
+            return `${filter.field} <= ${renderLiteral(filter.value)}`;
+        case 'like':
+            return `${filter.field} LIKE ${renderLiteral(filter.value)}`;
+        case 'in':
+        case 'notIn': {
+            if (!Array.isArray(filter.value) || filter.value.length === 0) {
+                throw new Error(`"${filter.operator}" filters require a non-empty array.`);
+            }
+            const values = filter.value.map((value) => renderLiteral(value)).join(', ');
+            return `${filter.field} ${filter.operator === 'in' ? 'IN' : 'NOT IN'} (${values})`;
+        }
+        case 'between': {
+            if (!Array.isArray(filter.value) || filter.value.length !== 2) {
+                throw new Error('"between" filters require a two-item array.');
+            }
+            return `${filter.field} BETWEEN ${renderLiteral(filter.value[0])} AND ${renderLiteral(filter.value[1])}`;
+        }
+        default:
+            throw new Error(`Unsupported filter operator "${filter.operator}".`);
+    }
+}
+function renderFilteredAggregationField(aggregation) {
+    if (!aggregation.filters?.length) {
+        return aggregation.field;
+    }
+    const condition = aggregation.filters
+        .map(renderFilterCondition)
+        .map((part) => `(${part})`)
+        .join(' AND ');
+    const fallback = aggregation.aggregation === 'sum' ? '0' : 'NULL';
+    return `if(${condition}, ${aggregation.field}, ${fallback})`;
+}
+function renderExpression(expression) {
+    switch (expression.kind) {
+        case 'ref':
+            return expression.name;
+        case 'literal':
+            return renderLiteral(expression.value);
+        case 'binary': {
+            const operator = {
+                add: '+',
+                subtract: '-',
+                multiply: '*',
+                divide: '/',
+            }[expression.operator];
+            return `(${renderExpression(expression.left)}) ${operator} (${renderExpression(expression.right)})`;
+        }
+        case 'function': {
+            if (expression.name === 'nullIfZero') {
+                return `NULLIF(${renderExpression(expression.args[0])}, 0)`;
+            }
+            if (expression.name === 'coalesce') {
+                return `COALESCE(${expression.args.map(renderExpression).join(', ')})`;
+            }
+            const fn = {
+                round: 'ROUND',
+                floor: 'FLOOR',
+                ceil: 'CEIL',
+            }[expression.name];
+            return `${fn}(${expression.args.map(renderExpression).join(', ')})`;
+        }
+        default:
+            throw new Error('Unsupported semantic expression.');
+    }
+}
+function applyAggregations(builder, plan) {
+    let qb = builder;
+    for (const aggregation of plan.aggregations) {
+        const field = renderFilteredAggregationField(aggregation);
+        switch (aggregation.aggregation) {
+            case 'sum':
+                qb = qb.sum(field, aggregation.name);
+                break;
+            case 'count':
+                qb = qb.count(field, aggregation.name);
+                break;
+            case 'countDistinct':
+                qb = qb.countDistinct(field, aggregation.name);
+                break;
+            case 'avg':
+                qb = qb.avg(field, aggregation.name);
+                break;
+            case 'min':
+                qb = qb.min(field, aggregation.name);
+                break;
+            case 'max':
+                qb = qb.max(field, aggregation.name);
+                break;
+        }
+    }
+    return qb;
+}
+function appendOrderLimitOffset(builder, plan) {
+    let qb = builder;
+    for (const order of plan.orderBy ?? []) {
+        qb = qb.orderBy(order.field, order.direction.toUpperCase());
+    }
+    if (plan.limit != null)
+        qb = qb.limit(plan.limit);
+    if (plan.offset != null)
+        qb = qb.offset(plan.offset);
+    return qb;
+}
+function buildAggregateQuery(queryBuilder, plan) {
+    let qb = queryBuilder.table(plan.source);
+    const selectParts = plan.dimensions.map((dimension) => (dimension.field === dimension.name ? dimension.name : `${dimension.field} AS ${dimension.name}`));
+    const groupByParts = plan.dimensions.map((dimension) => dimension.name);
+    if (plan.grain) {
+        selectParts.unshift(`${renderGrain(plan.grain.field, plan.grain.unit)} AS ${plan.grain.output}`);
+        groupByParts.unshift(plan.grain.output);
+    }
+    if (selectParts.length > 0)
+        qb = qb.select(selectParts);
+    qb = applyAggregations(qb, plan);
+    if (groupByParts.length > 0)
+        qb = qb.groupBy(groupByParts);
+    if (plan.tenant)
+        qb = qb.where(plan.tenant.field, 'eq', plan.tenant.value);
+    qb = applyFilters(qb, plan.filters);
+    return appendOrderLimitOffset(qb, plan);
+}
+function buildDerivedSQL(queryBuilder, plan) {
+    if (plan.input.kind !== 'aggregate') {
+        throw new Error('ClickHouse datasets currently supports derived metrics over aggregate input plans only.');
+    }
+    const inputQuery = buildAggregateQuery(queryBuilder, plan.input);
+    const { sql, parameters } = inputQuery.toSQLWithParams();
+    const passthrough = [
+        ...(plan.input.grain ? [plan.input.grain.output] : []),
+        ...plan.input.dimensions.map((dimension) => dimension.name),
+    ];
+    const metricSelects = plan.metrics.map((metric) => (`${renderExpression(metric.expression)} AS ${metric.name}`));
+    let outerSql = `WITH base AS (${sql}) SELECT ${[...passthrough, ...metricSelects].join(', ')} FROM base`;
+    if (plan.orderBy?.length) {
+        outerSql += ` ORDER BY ${plan.orderBy.map((order) => (`${order.field} ${order.direction.toUpperCase()}`)).join(', ')}`;
+    }
+    if (plan.limit != null)
+        outerSql += ` LIMIT ${plan.limit}`;
+    if (plan.offset != null)
+        outerSql += ` OFFSET ${plan.offset}`;
+    return { sql: outerSql, parameters };
+}
+export function createClickHouseSemanticBackendFromQueryBuilder(queryBuilder) {
+    return {
+        async execute(plan) {
+            const start = Date.now();
+            if (plan.kind === 'aggregate') {
+                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 } };
+            }
+            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 } };
+        },
+        async explain(plan) {
+            if (plan.kind === 'aggregate') {
+                return { sql: buildAggregateQuery(queryBuilder, plan).toSQLWithParams().sql };
+            }
+            return { sql: buildDerivedSQL(queryBuilder, plan).sql };
+        },
+    };
+}