@hypequery/datasets 0.23.1 → 0.24.0

package/dist/utils/by-name.js

@@ -0,0 +1,44 @@
+/**
+ * The weights a name sorts by: underscore, then digits, then letters
+ * compared without case; ties then go lowercase first. This is what
+ * `localeCompare` gives RFC 0002 names (ASCII letters, digits, underscores)
+ * under the root collation, fixed so it cannot change with the host locale.
+ * Python's `portable_name_key` is the same collation.
+ */
+function nameWeights(value) {
+    const base = [];
+    const caseWeights = [];
+    for (const char of value) {
+        if (char === '_') {
+            base.push(0);
+            caseWeights.push(0);
+        }
+        else if (char >= '0' && char <= '9') {
+            base.push(char.charCodeAt(0) - 48 + 1);
+            caseWeights.push(0);
+        }
+        else {
+            const lower = char.toLowerCase();
+            base.push(lower.charCodeAt(0) - 97 + 11);
+            caseWeights.push(char === lower ? 0 : 1);
+        }
+    }
+    return { base, caseWeights };
+}
+function compareWeights(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        if (left[index] !== right[index])
+            return left[index] - right[index];
+    }
+    return left.length - right.length;
+}
+/**
+ * The order protocol artifacts list named things in, so the same definitions
+ * produce the same bytes whatever order they were supplied in, on any host.
+ */
+export function byName(left, right) {
+    const a = nameWeights(left.name);
+    const b = nameWeights(right.name);
+    return compareWeights(a.base, b.base) || compareWeights(a.caseWeights, b.caseWeights);
+}

package/dist/utils/calendar-shift-sql.d.ts

@@ -1,3 +1,4 @@
+import type { DatasetSqlDialectRules } from '../dataset-sql-dialect.js';
 import type { MeasureTimeInterval } from '../types.js';
 /**
  * Shift a point inside a bucket by a calendar interval, relative to the
@@ -10,9 +11,9 @@ import type { MeasureTimeInterval } from '../types.js';
  * the 2024-01-26 week, so a partial bucket's range came out empty or
  * overlapping the next week.
  *
- * The point keeps its own wall-clock time (`subtractMonths` and `addDays` both
- * preserve it) and moves by whole calendar days to the anchor's day plus the
- * point's day offset within its bucket.
+ * The point keeps its own wall-clock time (calendar subtraction and day
+ * addition both preserve it) and moves by whole calendar days to the anchor's
+ * day plus the point's day offset within its bucket.
  */
-export declare function anchoredCalendarShiftSql(point: string, anchor: string, interval: MeasureTimeInterval): string;
+export declare function anchoredCalendarShiftSql(dialect: DatasetSqlDialectRules, point: string, anchor: string, interval: MeasureTimeInterval): string;
 //# sourceMappingURL=calendar-shift-sql.d.ts.map

package/dist/utils/calendar-shift-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calendar-shift-sql.d.ts","sourceRoot":"","sources":["../../src/utils/calendar-shift-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAI7G"}
+{"version":3,"file":"calendar-shift-sql.d.ts","sourceRoot":"","sources":["../../src/utils/calendar-shift-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAK9I"}

package/dist/utils/calendar-shift-sql.js

@@ -1,4 +1,3 @@
-import { subtractTimeSql } from './time-arithmetic-sql.js';
 /**
  * Shift a point inside a bucket by a calendar interval, relative to the
  * bucket's shifted anchor rather than on its own.
@@ -10,12 +9,13 @@ import { subtractTimeSql } from './time-arithmetic-sql.js';
  * the 2024-01-26 week, so a partial bucket's range came out empty or
  * overlapping the next week.
  *
- * The point keeps its own wall-clock time (`subtractMonths` and `addDays` both
- * preserve it) and moves by whole calendar days to the anchor's day plus the
- * point's day offset within its bucket.
+ * The point keeps its own wall-clock time (calendar subtraction and day
+ * addition both preserve it) and moves by whole calendar days to the anchor's
+ * day plus the point's day offset within its bucket.
  */
-export function anchoredCalendarShiftSql(point, anchor, interval) {
-    const shiftedPoint = subtractTimeSql(point, interval.amount, interval.unit);
-    const shiftedAnchor = subtractTimeSql(anchor, interval.amount, interval.unit);
-    return `addDays(${shiftedPoint}, dateDiff('day', ${shiftedPoint}, ${shiftedAnchor}) + dateDiff('day', ${anchor}, ${point}))`;
+export function anchoredCalendarShiftSql(dialect, point, anchor, interval) {
+    const shiftedPoint = dialect.subtractTime(point, interval.amount, interval.unit);
+    const shiftedAnchor = dialect.subtractTime(anchor, interval.amount, interval.unit);
+    const days = `${dialect.timeDiff('day', shiftedPoint, shiftedAnchor)} + ${dialect.timeDiff('day', anchor, point)}`;
+    return dialect.addTime(shiftedPoint, days, 'day');
 }

package/dist/utils/clickhouse-dataset-sql-dialect.d.ts

@@ -1,4 +1,4 @@
-import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
+import type { DatasetSqlDialectRules } from '../dataset-sql-dialect.js';
 /** Preserve the existing ClickHouse spelling and escaping byte for byte. */
-export declare const clickhouseDatasetSqlDialect: DatasetSqlDialect;
+export declare const clickhouseDatasetSqlDialect: DatasetSqlDialectRules;
 //# sourceMappingURL=clickhouse-dataset-sql-dialect.d.ts.map

package/dist/utils/clickhouse-dataset-sql-dialect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse-dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,EAAE,iBAGxC,CAAC"}
+{"version":3,"file":"clickhouse-dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/clickhouse-dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAwClG,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,EAAE,sBA8GP,CAAC"}

package/dist/utils/clickhouse-dataset-sql-dialect.js

@@ -1,6 +1,145 @@
-import { quoteSQLIdentifier } from '../sql-utils.js';
+import { quoteSQLIdentifier, stripSqlLiterals } from '../sql-utils.js';
+import { assertAggregateStateFunction, mergeStateExpression } from './aggregate-state-functions.js';
+const TRUNCATE_FUNCTIONS = {
+    minute: 'toStartOfMinute',
+    hour: 'toStartOfHour',
+    day: 'toStartOfDay',
+    // Mode 0 (Sunday) is the shipped behaviour; Monday weeks wait for a major.
+    week: 'toStartOfWeek',
+    month: 'toStartOfMonth',
+    quarter: 'toStartOfQuarter',
+    year: 'toStartOfYear',
+};
+const INTERVAL_UNITS = {
+    minute: 'Minutes', hour: 'Hours', day: 'Days', week: 'Weeks', month: 'Months', quarter: 'Quarters', year: 'Years',
+};
+const BINARY_OPERATORS = {
+    add: '+', subtract: '-', multiply: '*', divide: '/',
+};
+/**
+ * Statement terminators and comment openers. A raw `sql` value is spliced into
+ * a larger expression, so any of these turns one expression into something
+ * else: `;` starts a second statement, `--` and `/*` comment out whatever the
+ * builder appends after it.
+ */
+const STATEMENT_BREAKERS = /;|--|\/\*/;
+// ClickHouse also treats backslash as a string escape. Doubling quotes without
+// escaping backslashes lets a value ending in \\ before a quote break out of
+// the literal and change the predicate.
+function stringLiteral(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
+}
 /** Preserve the existing ClickHouse spelling and escaping byte for byte. */
 export const clickhouseDatasetSqlDialect = Object.freeze({
     name: 'clickhouse',
     quoteIdentifier: quoteSQLIdentifier,
+    // The adapter substitutes positional `?` on the client, one value per marker.
+    placeholder: () => '?',
+    reusesPlaceholders: false,
+    embedsPositionalPieces: true,
+    orderTerm: (expression, direction) => direction ? `${expression} ${direction}` : expression,
+    paginate: (limit, offset) => `${limit === undefined ? '' : ` LIMIT ${limit}`}${offset === undefined ? '' : ` OFFSET ${offset}`}`,
+    quoteQualifiedName: (name) => name.split('.').map(quoteSQLIdentifier).join('.'),
+    finalTable: (quotedSource) => `${quotedSource} FINAL`,
+    rawSqlExpressionError(sql) {
+        let code;
+        try {
+            // Quoted spans are blanked first, so a terminator inside a literal is data.
+            code = stripSqlLiterals(sql);
+        }
+        catch {
+            return 'unterminated-literal';
+        }
+        return STATEMENT_BREAKERS.test(code) ? 'statement-break' : undefined;
+    },
+    stringLiteral,
+    measureFilterLiteral(value) {
+        if (value === null)
+            return 'NULL';
+        if (typeof value === 'string')
+            return stringLiteral(value);
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value)) {
+                throw new Error(`Invalid non-finite numeric literal in measure filter: ${value}`);
+            }
+            return String(value);
+        }
+        if (typeof value === 'boolean')
+            return value ? '1' : '0';
+        throw new Error(`Unsupported literal type in measure filter: ${typeof value}`);
+    },
+    truncateTime: (time, grain) => `${TRUNCATE_FUNCTIONS[grain]}(${time})`,
+    addTime: (time, amount, grain) => `add${INTERVAL_UNITS[grain]}(${time}, ${amount})`,
+    subtractTime: (time, amount, grain) => `subtract${INTERVAL_UNITS[grain]}(${time}, ${amount})`,
+    timeDiff: (grain, start, end) => `dateDiff('${grain}', ${start}, ${end})`,
+    toQueryTimezone: (time, timezone) => `toDateTime64(${time}, 9, '${timezone}')`,
+    parseTimestamp: (value, timezone) => `parseDateTime64BestEffort(${value}, 9, ${timezone})`,
+    timezoneOf: (time) => `timezoneOf(${time})`,
+    clockPart: (part, time) => `to${part}(${time})`,
+    isDateOnlyType: (value) => `position(toTypeName(${value}), 'Date') > 0 AND position(toTypeName(${value}), 'DateTime') = 0`,
+    guard: (condition, message) => `throwIf(${condition}, ${stringLiteral(message)})`,
+    ifElse: (condition, then, otherwise) => `if(${condition}, ${then}, ${otherwise})`,
+    greatest: (...values) => `greatest(${values.join(', ')})`,
+    least: (...values) => `least(${values.join(', ')})`,
+    isNotDistinctFrom: (left, right) => `isNotDistinctFrom(${left}, ${right})`,
+    isNotNull: (value) => `isNotNull(${value})`,
+    assumeNotNull: (value) => `assumeNotNull(${value})`,
+    toNullable: (value) => `toNullable(${value})`,
+    countIf: (condition) => `countIf(${condition})`,
+    seriesIndex: (count) => `arrayJoin(range(toUInt64(${count})))`,
+    anyIndex: (index, count, predicate) => `arrayExists(${index} -> ${predicate}, range(toUInt64(${count})))`,
+    packRow: (values) => `tuple(${values.join(', ')})`,
+    rowElement: (row, position) => `tupleElement(${row}, ${position})`,
+    selectAllExcept: (relation, columns) => `${relation}.* EXCEPT (${columns.join(', ')})`,
+    asofLeftJoin: 'LEFT ASOF JOIN',
+    filteredAggregateInput: (condition, value, fallback) => `if(${condition}, ${value}, ${fallback})`,
+    windowAggregate(definition, value, arg) {
+        switch (definition.aggregation) {
+            case 'count': return `count(${value})`;
+            case 'countDistinct': return `uniqExact(${value})`;
+            case 'approxCountDistinct': return `uniq(${value})`;
+            // -Merge cannot take -OrNull (the state type names the bare function); a
+            // window group always has rows, and counts coalesce to 0 downstream.
+            case 'merge': return mergeStateExpression(requireStateFunction(definition), value);
+            case 'percentile': return `quantileOrNull(${definition.level})(${value})`;
+            case 'argMax': return `argMaxOrNull(${value}, ${arg})`;
+            case 'argMin': return `argMinOrNull(${value}, ${arg})`;
+            case 'stddev': return `stddevSampOrNull(${value})`;
+            case 'variance': return `varSampOrNull(${value})`;
+            default: return `${definition.aggregation}OrNull(${value})`;
+        }
+    },
+    reaggregate: (aggregation, value) => `${aggregation}OrNull(${value})`,
+    formulaLiteral(value) {
+        if (value === null)
+            return 'NULL';
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                throw new Error('Formula contains a non-finite number.');
+            return String(value);
+        }
+        if (typeof value === 'boolean')
+            return value ? 'true' : 'false';
+        return stringLiteral(value);
+    },
+    formulaBinary(operator, left, right) {
+        const symbol = BINARY_OPERATORS[operator];
+        if (!symbol)
+            throw new Error('Formula contains an unsupported binary operator.');
+        return `(${left} ${symbol} ${right})`;
+    },
+    formulaFunction(name, args) {
+        switch (name) {
+            case 'nullIfZero': return `NULLIF(${args[0]}, 0)`;
+            case 'coalesce': return `COALESCE(${args.join(', ')})`;
+            case 'round': return `ROUND(${args.join(', ')})`;
+            case 'floor': return `FLOOR(${args[0]})`;
+            case 'ceil': return `CEIL(${args[0]})`;
+            default: throw new Error('Formula contains an unsupported function.');
+        }
+    },
 });
+function requireStateFunction(definition) {
+    assertAggregateStateFunction(definition.stateFunction, 'A merge measure');
+    return definition.stateFunction;
+}

package/dist/utils/compile-dataset-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-dataset-query.d.ts","sourceRoot":"","sources":["../../src/utils/compile-dataset-query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAA2D,MAAM,2BAA2B,CAAC;AAC7H,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AASpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CAC/C;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,GAAE,WAAW,GAAG,SAAuB,GAC1C,oBAAoB,CA6DtB"}
+{"version":3,"file":"compile-dataset-query.d.ts","sourceRoot":"","sources":["../../src/utils/compile-dataset-query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAA2D,MAAM,2BAA2B,CAAC;AAC7H,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAUpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CAC/C;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,GAAE,WAAW,GAAG,SAAuB,GAC1C,oBAAoB,CA+DtB"}

package/dist/utils/compile-dataset-query.js

@@ -7,6 +7,7 @@ import { overfetchLimit } from './pagination.js';
 import { resolveResultLimit } from './result-limits.js';
 import { buildTimeMeasureDatasetSql } from './time-measure-dataset-sql.js';
 import { selectedTimeMeasures } from './time-query-measures.js';
+import { renderStatement } from './statement-parameters.js';
 /** The one dispatch point for dataset preview and query-builder execution. */
 export function prepareDatasetQuery(dataset, input, options, mode = 'execution') {
     const query = structuredClone({
@@ -25,17 +26,19 @@ export function prepareDatasetQuery(dataset, input, options, mode = 'execution')
     const abortSignal = options.context?.abortSignal;
     if (selectedTimeMeasures(dataset, query).size) {
         plan = 'time';
-        const compiled = buildTimeMeasureDatasetSql(dataset, query, executionOptions);
-        statement = compiled;
-        preflightStatements.push({ sql: compiled.timeAxisSql, parameters: compiled.parameters });
+        const planned = buildTimeMeasureDatasetSql(dataset, query, executionOptions);
+        const main = renderStatement(planned.statement);
+        const preflight = renderStatement(planned.preflight);
+        statement = main;
+        preflightStatements.push(preflight);
         execute = async () => {
-            await options.builderFactory.rawQuery(compiled.timeAxisSql, compiled.parameters, { abortSignal });
-            return options.builderFactory.rawQuery(compiled.sql, compiled.parameters, { abortSignal });
+            await options.builderFactory.rawQuery(preflight.sql, preflight.parameters, { abortSignal });
+            return options.builderFactory.rawQuery(main.sql, main.parameters, { abortSignal });
         };
     }
     else if (needsOuterDatasetQuery(dataset, query)) {
         plan = hasSelectedDerivedMeasure(dataset, query) ? 'derived' : 'aggregate';
-        statement = buildDerivedDatasetSql(dataset, query, executionOptions, buildDatasetQueryBuilder);
+        statement = renderStatement(buildDerivedDatasetSql(dataset, query, executionOptions, buildDatasetQueryBuilder));
         execute = () => options.builderFactory.rawQuery(statement.sql, statement.parameters, { abortSignal });
     }
     else {

package/dist/utils/composite-time-measure-sql.d.ts

@@ -1,10 +1,8 @@
 import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
 import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
 import type { TimeMeasureAxis } from './time-measure-axis.js';
+import type { StatementParameters } from './statement-parameters.js';
+import type { PlannedTimeMeasureStatements } from './time-measure-dataset-sql.js';
 /** Aggregate each dependency in its evaluation context, then evaluate formulas. */
-export declare function buildCompositeTimeMeasureSql(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, axis: TimeMeasureAxis): {
-    sql: string;
-    parameters: unknown[];
-    timeAxisSql: string;
-};
+export declare function buildCompositeTimeMeasureSql(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, axis: TimeMeasureAxis, parameters: StatementParameters): PlannedTimeMeasureStatements;
 //# sourceMappingURL=composite-time-measure-sql.d.ts.map

package/dist/utils/composite-time-measure-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-time-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/composite-time-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAW9D,mFAAmF;AACnF,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,4BAA4B,EAAE,IAAI,EAAE,eAAe;;;;EAgDrJ"}
+{"version":3,"file":"composite-time-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/composite-time-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAS9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAElF,mFAAmF;AACnF,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,mBAAmB,GAC9B,4BAA4B,CAgD9B"}

package/dist/utils/composite-time-measure-sql.js

@@ -1,5 +1,4 @@
 import { queryMeasureDefinitions } from './relationship-measures.js';
-import { quoteSQLIdentifier } from '../sql-utils.js';
 import { isDerivedMeasure, isWindowMeasure } from './dataset-measures.js';
 import { buildMeasureEvaluationGraph, evaluationFormula } from './measure-evaluation-graph.js';
 import { buildTimeMeasureSourceSql } from './time-measure-source-sql.js';
@@ -9,17 +8,18 @@ import { timeMeasureLeafSql } from './time-measure-leaf-sql.js';
 import { derivedProjection } from './derived-measure-sql.js';
 import { buildTimeMeasureResultSql } from './time-measure-result-sql.js';
 /** Aggregate each dependency in its evaluation context, then evaluate formulas. */
-export function buildCompositeTimeMeasureSql(ds, query, options, axis) {
+export function buildCompositeTimeMeasureSql(ds, query, options, axis, parameters) {
+    const { dialect } = parameters;
     const graph = buildMeasureEvaluationGraph(queryMeasureDefinitions(ds, query.measures ?? []), query.measures ?? []);
     const leaves = graph.nodes.filter(node => !isDerivedMeasure(node.definition));
     const baseNames = new Set(leaves.map(node => isWindowMeasure(node.definition) ? node.definition.measure : node.name));
-    const source = buildTimeMeasureSourceSql(ds, query, baseNames, axis.filters, options);
-    const timeAxis = buildTimeMeasureAxisSql(source, axis);
-    const contexts = timeMeasureContextCtes(graph.contexts, axis);
+    const source = buildTimeMeasureSourceSql(ds, query, baseNames, axis.filters, options, parameters);
+    const timeAxis = buildTimeMeasureAxisSql(parameters, source, axis);
+    const contexts = timeMeasureContextCtes(dialect, graph.contexts, axis);
     const inputs = leaves.map(node => {
         const window = isWindowMeasure(node.definition) ? node.definition : undefined;
         const base = source.bases.find(base => base.name === (window?.measure ?? node.name));
-        return { node, ...timeMeasureLeafSql(node.id, node.context, base, window, axis, source.dimensions) };
+        return { node, ...timeMeasureLeafSql(dialect, node.id, node.context, base, window, axis, source.dimensions) };
     });
     const keys = source.dimensions.map(dim => dim.alias);
     const combinations = keys.length ? ` CROSS JOIN (SELECT DISTINCT ${keys.join(', ')} FROM (${inputs.map(input => `SELECT ${keys.join(', ')} FROM ${input.population}`).join(' UNION ALL ')})) AS _hq_combinations` : '';
@@ -33,29 +33,28 @@ export function buildCompositeTimeMeasureSql(ds, query, options, axis) {
         const next = `_hq_evaluated${node.id}`;
         const value = input.count ? `coalesce(m.${output}, 0)` : `m.${output}`;
         if (input.cumulative) {
-            const partition = keys.length ? `tuple(${keys.map(key => `s.${key}`).join(', ')})` : 'tuple(0)';
+            const partition = dialect.packRow(keys.length ? keys.map(key => `s.${key}`) : ['0']);
             const lookup = `_hq_lookup${node.id}`;
             ctes.push(`${lookup} AS (SELECT s.*, c._hq_eval_end, ${partition} AS _hq_partition FROM ${previous} AS s INNER JOIN _hq_context${input.context} AS c ON s._hq_period = c._hq_period)`);
-            ctes.push(`${next} AS (SELECT s.* EXCEPT (_hq_eval_end, _hq_partition), ${value} AS ${output} FROM ${lookup} AS s LEFT ASOF JOIN ${input.aggregate} AS m ON s._hq_partition = m._hq_partition AND s._hq_eval_end > m._hq_time)`);
+            ctes.push(`${next} AS (SELECT ${dialect.selectAllExcept('s', ['_hq_eval_end', '_hq_partition'])}, ${value} AS ${output} FROM ${lookup} AS s ${dialect.asofLeftJoin} ${input.aggregate} AS m ON s._hq_partition = m._hq_partition AND s._hq_eval_end > m._hq_time)`);
         }
         else {
-            const condition = ['s._hq_period = m._hq_period', ...keys.map(key => `isNotDistinctFrom(s.${key}, m.${key})`)];
+            const condition = ['s._hq_period = m._hq_period', ...keys.map(key => dialect.isNotDistinctFrom(`s.${key}`, `m.${key}`))];
             ctes.push(`${next} AS (SELECT s.*, ${value} AS ${output} FROM ${previous} AS s LEFT JOIN ${input.aggregate} AS m ON ${condition.join(' AND ')})`);
         }
         previous = next;
     }
     for (const node of graph.nodes.filter(node => isDerivedMeasure(node.definition))) {
         const next = `_hq_formula${node.id}`;
-        ctes.push(`${next} AS (SELECT *, ${derivedProjection(`_hq_value${node.id}`, evaluationFormula(node))} FROM ${previous})`);
+        ctes.push(`${next} AS (SELECT *, ${derivedProjection(dialect, `_hq_value${node.id}`, evaluationFormula(node))} FROM ${previous})`);
         previous = next;
     }
-    const projections = ['v._hq_period AS period', ...source.dimensions.map(dim => `v.${dim.alias} AS ${quoteSQLIdentifier(dim.name)}`),
-        ...Object.entries(graph.outputs).map(([name, id]) => `v._hq_value${id} AS ${quoteSQLIdentifier(name)}`)];
+    const projections = ['v._hq_period AS period', ...source.dimensions.map(dim => `v.${dim.alias} AS ${dialect.quoteIdentifier(dim.name)}`),
+        ...Object.entries(graph.outputs).map(([name, id]) => `v._hq_value${id} AS ${dialect.quoteIdentifier(name)}`)];
     ctes.push(`_hq_values AS (SELECT ${projections.join(', ')} FROM ${previous} AS v)`);
-    const guard = [timeAxis.guard, timeAxis.rangeGuard, ...graph.contexts.map(context => timeMeasureContextGuard(context, axis)), ...inputs.map(input => input.guard)].join(' + ');
+    const guard = [timeAxis.guard, timeAxis.rangeGuard, ...graph.contexts.map(context => timeMeasureContextGuard(dialect, context, axis)), ...inputs.map(input => input.guard)].join(' + ');
     return {
-        sql: buildTimeMeasureResultSql(ds, query, options, source.dimensions, ctes, guard, true),
-        parameters: source.parameters,
-        timeAxisSql: `WITH ${guardCtes.join(',\n')} SELECT ${guard} AS _hq_validated FROM _hq_bounds`,
+        statement: { text: buildTimeMeasureResultSql(ds, query, options, source.dimensions, ctes, guard, true), parameters },
+        preflight: { text: `WITH ${guardCtes.join(',\n')} SELECT ${guard} AS _hq_validated FROM _hq_bounds`, parameters },
     };
 }

package/dist/utils/count-aggregations.d.ts

@@ -0,0 +1,4 @@
+import type { MeasureDefinition } from '../types.js';
+/** Counts are 0, not NULL, over an empty population. */
+export declare function isCountAggregation(definition: MeasureDefinition): boolean;
+//# sourceMappingURL=count-aggregations.d.ts.map

package/dist/utils/count-aggregations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"count-aggregations.d.ts","sourceRoot":"","sources":["../../src/utils/count-aggregations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,wDAAwD;AACxD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAGzE"}

package/dist/utils/count-aggregations.js

@@ -0,0 +1,6 @@
+import { isCountStateMerge } from './aggregate-state-functions.js';
+/** Counts are 0, not NULL, over an empty population. */
+export function isCountAggregation(definition) {
+    return ['count', 'countDistinct', 'approxCountDistinct'].includes(definition.aggregation)
+        || isCountStateMerge(definition);
+}

package/dist/utils/dataset-definition-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-definition-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-definition-validation.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EAEnB,sBAAsB,EAEvB,MAAM,aAAa,CAAC;AAQrB,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AACzD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAC5D,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAwR/D;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,CAAC,aAAa,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAClE,IAAI,CA2DN"}
+{"version":3,"file":"dataset-definition-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-definition-validation.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EAGnB,sBAAsB,EAEvB,MAAM,aAAa,CAAC;AAWrB,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AACzD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAC5D,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AA2R/D;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,CAAC,aAAa,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAClE,IAAI,CA+DN"}

package/dist/utils/dataset-definition-validation.js

@@ -1,18 +1,13 @@
 import { validateShiftMeasures } from './shift-measure-validation.js';
 import { escapeRegExp, isSafeSQLIdentifier, stripSqlLiterals } from '../sql-utils.js';
+import { clickhouseDatasetSqlDialect } from './clickhouse-dataset-sql-dialect.js';
+import { rawSqlErrorMessage } from './raw-sql-dialect-check.js';
 import { SEMANTIC_FILTER_OPERATORS, isSemanticFilterOperator } from '../constants.js';
 import { validateDerivedMeasures } from './derived-measure-validation.js';
 import { isDerivedMeasure, isWindowMeasure, isShiftMeasure } from './dataset-measures.js';
 import { validateWindowMeasures } from './window-measure-validation.js';
 import { validateDatasetAgentMetadata } from './semantic-metadata-validation.js';
-/**
- * Statement terminators and comment openers.
- *
- * A raw `sql` value is spliced into a larger expression, so any of these turns
- * one expression into something else: `;` starts a second statement, `--` and
- * `/*` comment out whatever the builder appends after it.
- */
-const STATEMENT_BREAKERS = /;|--|\/\*/;
+import { AGGREGATE_STATE_FUNCTIONS, isAggregateStateFunction } from './aggregate-state-functions.js';
 /** Dataset, dimension and measure names address fields as `<relationship>.<dimension>`. */
 const QUALIFIED_SEPARATOR = '.';
 function fail(datasetName, message) {
@@ -63,24 +58,16 @@ function validateRawSql(datasetName, kind, name, sql, dependencies) {
     if (sql.trim().length === 0) {
         fail(datasetName, `${kind} "${name}" declares an empty sql expression.`);
     }
-    // Quoted spans are blanked first, so a terminator or comment opener *inside* a
-    // string literal is data rather than syntax. An unterminated quote is itself a
-    // rejection: left as data, an open quote would hide everything after it.
-    let code;
-    let referenceable;
-    try {
-        code = stripSqlLiterals(sql);
-        // A quoted identifier is a column reference, so the dependency check below
-        // needs its text even though the terminator check above must not see it.
-        referenceable = stripSqlLiterals(sql, { keepQuotedIdentifiers: true });
-    }
-    catch {
-        fail(datasetName, `${kind} "${name}" sql has an unterminated quoted literal.`);
-    }
-    if (STATEMENT_BREAKERS.test(code)) {
-        fail(datasetName, `${kind} "${name}" sql must be a single expression without statement terminators or ` +
-            'comments (";", "--", "/*") outside a quoted literal.');
-    }
+    // Definitions are engine-neutral, so this checks ClickHouse lexical rules;
+    // compilation re-checks under any other engine's rules (raw-sql-dialect-check).
+    // An unterminated quote is itself a rejection: left as data, an open quote
+    // would hide everything after it.
+    const lexicalError = clickhouseDatasetSqlDialect.rawSqlExpressionError(sql);
+    if (lexicalError)
+        fail(datasetName, rawSqlErrorMessage(kind, name, lexicalError));
+    // A quoted identifier is a column reference, so the dependency check below
+    // needs its text even though the terminator check above must not see it.
+    const referenceable = stripSqlLiterals(sql, { keepQuotedIdentifiers: true });
     for (const dependency of dependencies ?? []) {
         // Dependencies are qualified identifiers (`analytics.orders.amount`); the
         // expression references the column itself, so the final segment is what has
@@ -176,6 +163,9 @@ function validateMeasures(datasetName, measures, dimensions, declaredFilters) {
             validateRawSql(datasetName, 'measure', name, definition.sql, definition.dependencies);
         }
         validateMeasureFilters(datasetName, name, definition.filters ?? [], dimensions, declaredFilters);
+        if (definition.aggregation === 'merge') {
+            validateMergeMeasure(datasetName, name, definition);
+        }
         // `field` and `argField` name either a declared dimension or a physical
         // column that the model deliberately does not expose (the `allowHiddenField`
         // case in metric validation). Either way the value reaches SQL, so a name
@@ -191,6 +181,23 @@ function validateMeasures(datasetName, measures, dimensions, declaredFilters) {
         }
     }
 }
+/**
+ * A merge measure names its state function (interpolated into SQL as
+ * `<fn>Merge`) and reads a plain column: raw SQL or filters would wrap the
+ * state column in an expression the `-Merge` combinator rejects.
+ */
+function validateMergeMeasure(datasetName, name, definition) {
+    if (!isAggregateStateFunction(definition.stateFunction)) {
+        fail(datasetName, `measure "${name}" merges unsupported aggregate state "${String(definition.stateFunction)}". ` +
+            `Supported state functions: ${AGGREGATE_STATE_FUNCTIONS.join(', ')}.`);
+    }
+    if (definition.filters?.length) {
+        fail(datasetName, `measure "${name}" cannot have filters: merge measures read stored states.`);
+    }
+    if (definition.sql !== undefined) {
+        fail(datasetName, `measure "${name}" cannot use sql: merge measures read a stored state column.`);
+    }
+}
 function validateLimits(datasetName, limits) {
     if (!limits) {
         return;
@@ -226,6 +233,9 @@ export function validateDatasetDefinition(name, config) {
         fail(name, `source "${config.source}" is not a safe table identifier. Expected "table" or ` +
             '"database.table", each segment containing only letters, numbers and underscores.');
     }
+    if (config.final !== undefined && typeof config.final !== 'boolean') {
+        fail(name, 'final must be true or false.');
+    }
     // The tenant key is the isolation boundary: it becomes a WHERE predicate on
     // every query against a tenant-scoped dataset, so it is checked here rather
     // than trusted wherever that predicate is assembled.

package/dist/utils/dataset-derived-query.d.ts

@@ -1,6 +1,7 @@
 import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
 import type { QueryBuilderLike } from '../query-builder-protocol.js';
 import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
+import { type PlannedStatement } from './statement-parameters.js';
 type BuildBaseQuery = (dataset: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions) => QueryBuilderLike;
 export declare function hasSelectedDerivedMeasure(ds: AnyDatasetInstance, query: DatasetQuery): boolean;
 /**
@@ -8,9 +9,6 @@ export declare function hasSelectedDerivedMeasure(ds: AnyDatasetInstance, query:
  * measures are computed there, and `having` conditions filter there.
  */
 export declare function needsOuterDatasetQuery(ds: AnyDatasetInstance, query: DatasetQuery): boolean;
-export declare function buildDerivedDatasetSql(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, buildBaseQuery: BuildBaseQuery): {
-    sql: string;
-    parameters: unknown[];
-};
+export declare function buildDerivedDatasetSql(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, buildBaseQuery: BuildBaseQuery): PlannedStatement;
 export {};
 //# sourceMappingURL=dataset-derived-query.d.ts.map

package/dist/utils/dataset-derived-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-derived-query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAGxE,KAAK,cAAc,GAAG,CACpB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,KAClC,gBAAgB,CAAC;AAEtB,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE9F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE3F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CAqDxC"}
+{"version":3,"file":"dataset-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-derived-query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,KAAK,cAAc,GAAG,CACpB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,KAClC,gBAAgB,CAAC;AAEtB,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE9F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE3F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B,gBAAgB,CAmDlB"}

package/dist/utils/dataset-derived-query.js

@@ -6,6 +6,7 @@ import { baseMeasureNames, getBaseMeasure, getDerivedMeasure } from './dataset-m
 import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
 import { validateDatasetQueryInput } from './dataset-query-validation.js';
 import { datasetHavingSql } from './dataset-having.js';
+import { StatementParameters } from './statement-parameters.js';
 export function hasSelectedDerivedMeasure(ds, query) {
     return (query.measures ?? []).some(name => getDerivedMeasure(ds.measures, name) !== undefined);
 }
@@ -26,7 +27,7 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
     const baseMeasures = measureDependencyNames(queryMeasureDefinitions(ds, selected), selected).filter(name => name.includes('.') || getBaseMeasure(ds.measures, name));
     const resolve = (name) => {
         const derived = getDerivedMeasure(ds.measures, name);
-        return derived ? `(${derivedExpressionSql(derived, resolve)})` : dialect.quoteIdentifier(name);
+        return derived ? `(${derivedExpressionSql(dialect, derived, resolve)})` : dialect.quoteIdentifier(name);
     };
     const inner = buildBaseQuery(ds, {
         ...query,
@@ -36,7 +37,8 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
         limit: undefined,
         offset: undefined,
     }, { ...options, executionLimit: undefined, skipDefaultOrderBy: true });
-    const { sql: innerSql, parameters } = inner.toSQLWithParams();
+    const parameters = new StatementParameters(dialect);
+    const base = parameters.embedBuilder(inner);
     const projections = [];
     if (query.by)
         projections.push(dialect.quoteIdentifier('period'));
@@ -45,27 +47,22 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
     for (const name of selected) {
         const derived = getDerivedMeasure(ds.measures, name);
         projections.push(derived
-            ? `${derivedExpressionSql(derived, resolve)} AS ${dialect.quoteIdentifier(name)}`
+            ? `${derivedExpressionSql(dialect, derived, resolve)} AS ${dialect.quoteIdentifier(name)}`
             : dialect.quoteIdentifier(name));
     }
-    let sql = `WITH base AS (${innerSql}) SELECT ${projections.join(', ')} FROM base`;
+    let text = `WITH base AS (${base}) SELECT ${projections.join(', ')} FROM base`;
     // Conditions read the same expression the projection does, never the output
     // alias, so the predicate stays valid on dialects without alias resolution.
     if (query.having?.length) {
-        const having = datasetHavingSql(query.having, resolve);
-        sql += ` WHERE ${having.sql}`;
-        parameters.push(...having.parameters);
+        text += ` WHERE ${datasetHavingSql(query.having, resolve, parameters)}`;
     }
     if (query.orderBy?.length) {
-        sql += ` ORDER BY ${query.orderBy.map(order => (`${dialect.quoteIdentifier(order.field)} ${semanticOrderDirection(order.direction)}`)).join(', ')}`;
+        text += ` ORDER BY ${query.orderBy.map(order => (dialect.orderTerm(dialect.quoteIdentifier(order.field), semanticOrderDirection(order.direction)))).join(', ')}`;
     }
     else if (query.by) {
-        sql += ` ORDER BY ${dialect.quoteIdentifier('period')} ASC`;
+        text += ` ORDER BY ${dialect.orderTerm(dialect.quoteIdentifier('period'), 'ASC')}`;
     }
     const limit = options.executionLimit ?? query.limit;
-    if (limit !== undefined)
-        sql += ` LIMIT ${limit}`;
-    if (query.offset !== undefined)
-        sql += ` OFFSET ${query.offset}`;
-    return { sql, parameters };
+    text += dialect.paginate(limit, query.offset);
+    return { text, parameters };
 }