@hypequery/datasets 0.23.1 → 0.25.0

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.
@@ -243,6 +253,25 @@ export function validateDatasetDefinition(name, config) {
             assertSafeColumn(name, config.timeKey, 'timeKey');
         }
     }
+    if (config.timeKeys !== undefined) {
+        if (!Array.isArray(config.timeKeys)) {
+            fail(name, 'timeKeys must be an array of dimension names or columns.');
+        }
+        if (config.timeKey === undefined) {
+            fail(name, 'timeKeys requires timeKey, the default time axis.');
+        }
+        if (new Set(config.timeKeys).size !== config.timeKeys.length) {
+            fail(name, 'timeKeys must not contain duplicates.');
+        }
+        for (const timeKey of config.timeKeys) {
+            if (typeof timeKey !== 'string' || timeKey.trim().length === 0) {
+                fail(name, 'timeKeys entries must be non-empty strings.');
+            }
+            if (!(timeKey in (config.dimensions ?? {}))) {
+                assertSafeColumn(name, timeKey, 'timeKeys');
+            }
+        }
+    }
     // A dataset with no dimensions is not rejected here: the query layer already
     // refuses an empty dataset query, which is the honest place for it — a
     // measure-only model is a legitimate thing to define.

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

package/dist/utils/dataset-having.d.ts

@@ -1,4 +1,5 @@
 import type { AnyDatasetInstance, DatasetHavingCondition, DatasetQuery } from '../types.js';
+import type { StatementParameters } from './statement-parameters.js';
 /**
  * Validates `having` conditions against the query they belong to.
  *
@@ -8,14 +9,11 @@ import type { AnyDatasetInstance, DatasetHavingCondition, DatasetQuery } from '.
  */
 export declare function datasetHavingErrors(ds: AnyDatasetInstance, query: DatasetQuery, selectedMeasures: readonly string[]): string[];
 /**
- * Renders validated `having` conditions as one parameterized predicate.
+ * Renders validated `having` conditions as one predicate.
  *
  * `measureSql` maps a selected measure to the expression that reads its
- * aggregated value in the outer query. Values are only ever bound as `?`
- * parameters, appended in placeholder order.
+ * aggregated value in the outer query. Values are only ever bound through
+ * `statement`, never written into the SQL text.
  */
-export declare function datasetHavingSql(conditions: readonly DatasetHavingCondition[], measureSql: (measure: string) => string): {
-    sql: string;
-    parameters: unknown[];
-};
+export declare function datasetHavingSql(conditions: readonly DatasetHavingCondition[], measureSql: (measure: string) => string, statement: StatementParameters): string;
 //# sourceMappingURL=dataset-having.d.ts.map

package/dist/utils/dataset-having.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-having.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-having.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmC5F;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,MAAM,EAAE,CA0CV;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,sBAAsB,EAAE,EAC7C,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GACtC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CAmBxC"}
+{"version":3,"file":"dataset-having.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-having.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAkCrE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAClC,MAAM,EAAE,CA0CV;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,sBAAsB,EAAE,EAC7C,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,EACvC,SAAS,EAAE,mBAAmB,GAC7B,MAAM,CAgBR"}

package/dist/utils/dataset-having.js

@@ -77,30 +77,27 @@ export function datasetHavingErrors(ds, query, selectedMeasures) {
     return errors;
 }
 /**
- * Renders validated `having` conditions as one parameterized predicate.
+ * Renders validated `having` conditions as one predicate.
  *
  * `measureSql` maps a selected measure to the expression that reads its
- * aggregated value in the outer query. Values are only ever bound as `?`
- * parameters, appended in placeholder order.
+ * aggregated value in the outer query. Values are only ever bound through
+ * `statement`, never written into the SQL text.
  */
-export function datasetHavingSql(conditions, measureSql) {
-    const parameters = [];
+export function datasetHavingSql(conditions, measureSql, statement) {
+    const bind = (value) => statement.bind(value, 'number');
     const predicates = conditions.map((condition) => {
         const column = measureSql(condition.measure);
         if (condition.operator === 'between') {
-            parameters.push(condition.value[0], condition.value[1]);
-            return `${column} BETWEEN ? AND ?`;
+            return `${column} BETWEEN ${bind(condition.value[0])} AND ${bind(condition.value[1])}`;
         }
         if (condition.operator === 'in' || condition.operator === 'notIn') {
-            parameters.push(...condition.value);
-            const placeholders = condition.value.map(() => '?').join(', ');
+            const placeholders = condition.value.map(bind).join(', ');
             return `${column} ${condition.operator === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`;
         }
         const comparison = COMPARISONS[condition.operator];
         if (!comparison)
             throw new Error(`Unsupported having operator "${String(condition.operator)}".`);
-        parameters.push(condition.value);
-        return `${column} ${comparison} ?`;
+        return `${column} ${comparison} ${bind(condition.value)}`;
     });
-    return { sql: predicates.join(' AND '), parameters };
+    return predicates.join(' AND ');
 }

package/dist/utils/dataset-normalization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-normalization.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-normalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAGrB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAC5D,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACzF,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAChE,WAAW,CAEb;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,CAgB3B;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1F,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,CAEX;AAED,wBAAgB,sBAAsB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAClG,aAAa,EAAE,cAAc,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,cAAc,CAkBhB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,GAC5B,eAAe,CAcjB"}
+{"version":3,"file":"dataset-normalization.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-normalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAGrB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAC5D,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACzF,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAChE,WAAW,CAEb;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,CAgB3B;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1F,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,CAEX;AAED,wBAAgB,sBAAsB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAClG,aAAa,EAAE,cAAc,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,cAAc,CAkBhB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,GAC5B,eAAe,CAejB"}

package/dist/utils/dataset-normalization.js

@@ -45,6 +45,7 @@ export function measureToAggregationSpec(measureName, definition) {
         field: definition.field,
         argField: definition.argField,
         level: definition.level,
+        ...(definition.stateFunction !== undefined ? { stateFunction: definition.stateFunction } : {}),
         sql: definition.sql,
         filters: definition.filters,
     };

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

@@ -1,4 +1,4 @@
 import type { AnyDatasetInstance, DatasetQuery, ExecutionContext } from '../types.js';
 import { type ValidationResult } from '../validation.js';
-export declare function validateDatasetQueryInput(ds: AnyDatasetInstance, query: DatasetQuery, context?: ExecutionContext): ValidationResult;
+export declare function validateDatasetQueryInput(dataset: AnyDatasetInstance, query: DatasetQuery, context?: ExecutionContext): ValidationResult;
 //# sourceMappingURL=dataset-query-validation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAkB9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAyKlB"}
+{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAoB9E,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAqLlB"}

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

@@ -1,3 +1,4 @@
+import { notGroupableError } from './groupable.js';
 import { resolveRelationshipMeasure } from './relationship-measures.js';
 import { semanticQuerySyntaxErrors } from './semantic-query-syntax.js';
 import { queryTimezoneErrors } from './query-timezone.js';
@@ -8,10 +9,19 @@ import { getRuntimeTenantPredicate, validateTenantRuntime, } from './tenant-runt
 import { isQualifiedField, resolveQualifiedField, } from './relationship-fields.js';
 import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './relationship-validation.js';
 import { segmentSelectionErrors } from './segments.js';
+import { enforcedConstraintErrors } from './enforced-constraints.js';
 import { analyzeTimeMeasureAxis } from './time-measure-axis.js';
 import { datasetHavingErrors } from './dataset-having.js';
-export function validateDatasetQueryInput(ds, query, context) {
-    const errors = [...semanticQuerySyntaxErrors(query), ...queryTimezoneErrors(query.timezone)];
+import { datasetOnTimeKey, selectedTimeKeyError } from './dataset-time-keys.js';
+export function validateDatasetQueryInput(dataset, query, context) {
+    // Validate against the selected time axis, so grain and window checks see it.
+    const timeKeyError = selectedTimeKeyError(dataset, query.timeKey);
+    const ds = timeKeyError ? dataset : datasetOnTimeKey(dataset, query.timeKey);
+    const errors = [
+        ...semanticQuerySyntaxErrors(query),
+        ...queryTimezoneErrors(query.timezone),
+        ...(timeKeyError ? [timeKeyError] : []),
+    ];
     const dimensionNames = Object.keys(ds.dimensions);
     const measureNames = Object.keys(ds.measures);
     const selectedDimensions = query.dimensions ?? [];
@@ -35,6 +45,7 @@ export function validateDatasetQueryInput(ds, query, context) {
     if (relationshipTenantError) {
         errors.push(relationshipTenantError);
     }
+    errors.push(...enforcedConstraintErrors(ds, context, query.filters?.length ?? 0));
     if (selectedDimensions.length === 0 && selectedMeasures.length === 0) {
         errors.push(`Dataset "${ds.name}" query must select at least one dimension or measure.`);
     }
@@ -45,11 +56,17 @@ export function validateDatasetQueryInput(ds, query, context) {
                 if (resolution?.error) {
                     errors.push(resolution.error);
                 }
+                else if (resolution?.resolved?.targetDimension.groupable === false) {
+                    errors.push(notGroupableError(dimension));
+                }
                 continue;
             }
             if (!dimensionNames.includes(dimension)) {
                 errors.push(`Unknown dimensions: ${dimension}. Available: ${dimensionNames.join(', ')}`);
             }
+            else if (ds.dimensions[dimension]?.groupable === false) {
+                errors.push(notGroupableError(dimension));
+            }
         }
     }
     if (query.measures) {

package/dist/utils/dataset-source.d.ts

@@ -0,0 +1,42 @@
+import type { AnyDatasetInstance } from '../types.js';
+import type { QueryBuilderFactoryLike, QueryBuilderLike } from '../query-builder-protocol.js';
+import type { RelationshipBuilderContext } from './relationship-builder-plan.js';
+/**
+ * The dataset's source table as a builder, read with `FINAL` when the dataset
+ * declares `rowResolution`. Every builder-path read of a dataset source goes
+ * through here so no query can skip row-version resolution.
+ */
+export declare function datasetSourceBuilder(builderFactory: Pick<QueryBuilderFactoryLike, 'table'>, ds: Pick<AnyDatasetInstance, 'name' | 'source' | 'rowResolution'>): QueryBuilderLike;
+/**
+ * A filter moved to PREWHERE runs before `FINAL` and can match an older version
+ * of a row. The server default forbids that; pinning it also covers profiles
+ * that enable it. `readonly = 1` accepts a setting equal to the profile's and
+ * refuses it exactly where the profile is unsafe, so the query fails closed.
+ */
+export declare const FINAL_SAFETY_SETTINGS: {
+    readonly optimize_move_to_prewhere_if_final: 0;
+};
+/**
+ * Whether a query reads a source with `FINAL`: the dataset's own, or a
+ * relationship target it actually joins. Unused relationships don't count, so
+ * a plain query never carries the pin.
+ */
+export declare function queryReadsFinal(ds: Pick<AnyDatasetInstance, 'rowResolution'>, joinCtx: Pick<RelationshipBuilderContext, 'joins'> | undefined): boolean;
+/**
+ * The statement with `FINAL_SAFETY_SETTINGS` in its own SQL, for paths that run
+ * rendered SQL (`rawQuery`), where builder settings don't travel.
+ */
+export declare function withFinalSafety<T extends {
+    sql: string;
+}>(readsFinal: boolean, statement: T): T;
+/**
+ * After `FINAL`, the rows that are current state: not deleted in a
+ * ReplacingMergeTree, positive in a collapsing engine. `FINAL` alone removes
+ * engine-declared deletions on current ClickHouse; the filter covers deletion
+ * columns the engine doesn't declare, older servers and unmatched cancel rows.
+ */
+export declare function currentRowPredicate(ds: Pick<AnyDatasetInstance, 'rowResolution'>): {
+    column: string;
+    value: 0 | 1;
+} | undefined;
+//# sourceMappingURL=dataset-source.d.ts.map

package/dist/utils/dataset-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-source.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAC9F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAEjF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,IAAI,CAAC,uBAAuB,EAAE,OAAO,CAAC,EACtD,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,QAAQ,GAAG,eAAe,CAAC,GAChE,gBAAgB,CAgBlB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;CAAqD,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAC,EAC7C,OAAO,EAAE,IAAI,CAAC,0BAA0B,EAAE,OAAO,CAAC,GAAG,SAAS,GAC7D,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAI/F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAC,GAC5C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,GAAG,SAAS,CAM9C"}

package/dist/utils/dataset-source.js

@@ -0,0 +1,59 @@
+/**
+ * The dataset's source table as a builder, read with `FINAL` when the dataset
+ * declares `rowResolution`. Every builder-path read of a dataset source goes
+ * through here so no query can skip row-version resolution.
+ */
+export function datasetSourceBuilder(builderFactory, ds) {
+    const qb = builderFactory.table(ds.source);
+    if (!ds.rowResolution) {
+        return qb;
+    }
+    if (typeof qb.final !== 'function') {
+        throw new Error(`Dataset "${ds.name}" reads its source with FINAL, but the query builder does not implement final(). ` +
+            'Reading it without FINAL would count every unmerged row version, so the query is refused.');
+    }
+    const resolved = qb.final();
+    const safe = resolved.settings ? resolved.settings(FINAL_SAFETY_SETTINGS) : resolved;
+    const current = currentRowPredicate(ds);
+    // Qualified like every base column, so it stays unambiguous once joins are added.
+    return current ? safe.where(`${ds.source}.${current.column}`, 'eq', current.value) : safe;
+}
+/**
+ * A filter moved to PREWHERE runs before `FINAL` and can match an older version
+ * of a row. The server default forbids that; pinning it also covers profiles
+ * that enable it. `readonly = 1` accepts a setting equal to the profile's and
+ * refuses it exactly where the profile is unsafe, so the query fails closed.
+ */
+export const FINAL_SAFETY_SETTINGS = { optimize_move_to_prewhere_if_final: 0 };
+/**
+ * Whether a query reads a source with `FINAL`: the dataset's own, or a
+ * relationship target it actually joins. Unused relationships don't count, so
+ * a plain query never carries the pin.
+ */
+export function queryReadsFinal(ds, joinCtx) {
+    return Boolean(ds.rowResolution) || Boolean(joinCtx?.joins.some(join => join.final));
+}
+/**
+ * The statement with `FINAL_SAFETY_SETTINGS` in its own SQL, for paths that run
+ * rendered SQL (`rawQuery`), where builder settings don't travel.
+ */
+export function withFinalSafety(readsFinal, statement) {
+    if (!readsFinal)
+        return statement;
+    const pins = Object.entries(FINAL_SAFETY_SETTINGS).map(([name, value]) => `${name} = ${value}`);
+    return { ...statement, sql: `${statement.sql} SETTINGS ${pins.join(', ')}` };
+}
+/**
+ * After `FINAL`, the rows that are current state: not deleted in a
+ * ReplacingMergeTree, positive in a collapsing engine. `FINAL` alone removes
+ * engine-declared deletions on current ClickHouse; the filter covers deletion
+ * columns the engine doesn't declare, older servers and unmatched cancel rows.
+ */
+export function currentRowPredicate(ds) {
+    const policy = ds.rowResolution;
+    if (!policy || !('engine' in policy))
+        return undefined;
+    if (policy.engine === 'replacing')
+        return policy.deletedColumn === undefined ? undefined : { column: policy.deletedColumn, value: 0 };
+    return { column: policy.signColumn, value: 1 };
+}

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

@@ -1,5 +1,16 @@
-import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
+import type { DatasetSqlDialect, DatasetSqlDialectRules } from '../dataset-sql-dialect.js';
 import type { QueryBuilderFactoryInput } from '../query-builder-protocol.js';
+/**
+ * Register a complete engine rule set, so a factory can carry it as its
+ * `datasetSqlDialect` and have it used as-is rather than completed with the
+ * ClickHouse rules. Internal: for engine packages and tests.
+ */
+export declare function defineDatasetSqlDialectRules<TRules extends DatasetSqlDialectRules>(rules: TRules): Readonly<TRules>;
+/**
+ * Complete a public dialect hook with the ClickHouse rules it does not
+ * override. Memoized, so one hook always resolves to one rule set.
+ */
+export declare function completeDatasetSqlDialect(dialect: DatasetSqlDialect): DatasetSqlDialectRules;
 /** Resolve from the active factory, so a runtime builder override carries its dialect. */
-export declare function resolveDatasetSqlDialect(factory: QueryBuilderFactoryInput): DatasetSqlDialect;
+export declare function resolveDatasetSqlDialect(factory: QueryBuilderFactoryInput): DatasetSqlDialectRules;
 //# sourceMappingURL=dataset-sql-dialect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAG7E,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAE7F"}
+{"version":3,"file":"dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAM7E;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,SAAS,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAInH;AAsCD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,sBAAsB,CAgB5F;AAED,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,sBAAsB,CAIlG"}

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

@@ -1,5 +1,78 @@
 import { clickhouseDatasetSqlDialect } from './clickhouse-dataset-sql-dialect.js';
+const resolved = new WeakMap();
+const complete = new WeakSet();
+/**
+ * Register a complete engine rule set, so a factory can carry it as its
+ * `datasetSqlDialect` and have it used as-is rather than completed with the
+ * ClickHouse rules. Internal: for engine packages and tests.
+ */
+export function defineDatasetSqlDialectRules(rules) {
+    const frozen = Object.isFrozen(rules) ? rules : receiverBoundSnapshot(rules);
+    complete.add(frozen);
+    return frozen;
+}
+/**
+ * A frozen snapshot of a rule set that leaves the caller's object unfrozen.
+ *
+ * Own members are copied as they are, so a rule shared with another rule set
+ * (spread from the ClickHouse rules, say) keeps its identity. Members a class
+ * declares are read through the original instance, methods bound to it and
+ * getters evaluated on it: its `#private` fields exist only on the object its
+ * constructor ran on, so a copy must not become their receiver. Members
+ * inherited from a plain object stay inherited.
+ */
+function receiverBoundSnapshot(rules) {
+    const snapshot = Object.create(Object.getPrototypeOf(rules), Object.getOwnPropertyDescriptors(rules));
+    for (let owner = Object.getPrototypeOf(rules); owner && isClassPrototype(owner); owner = Object.getPrototypeOf(owner)) {
+        for (const key of Reflect.ownKeys(owner)) {
+            if (key === 'constructor' || Object.hasOwn(snapshot, key))
+                continue;
+            // Read through the original, so a getter sees its own private fields;
+            // a method is bound to it for the same reason.
+            const value = Reflect.get(rules, key);
+            // Define rather than assign: assignment cannot shadow a read-only
+            // member inherited from a frozen prototype such as the ClickHouse rules.
+            Object.defineProperty(snapshot, key, {
+                value: typeof value === 'function' ? value.bind(rules) : value,
+                enumerable: true,
+            });
+        }
+    }
+    return Object.freeze(snapshot);
+}
+/** A prototype a class declaration created: its constructor points back at it. */
+function isClassPrototype(owner) {
+    if (owner === Object.prototype || !Object.hasOwn(owner, 'constructor'))
+        return false;
+    const constructor = owner.constructor;
+    return typeof constructor === 'function' && constructor.prototype === owner;
+}
+/**
+ * Complete a public dialect hook with the ClickHouse rules it does not
+ * override. Memoized, so one hook always resolves to one rule set.
+ */
+export function completeDatasetSqlDialect(dialect) {
+    if (dialect === clickhouseDatasetSqlDialect)
+        return clickhouseDatasetSqlDialect;
+    if (complete.has(dialect))
+        return dialect;
+    let rules = resolved.get(dialect);
+    if (!rules) {
+        // Read the public members explicitly: a class-based hook keeps its methods
+        // on the prototype, which spreading would silently drop.
+        rules = Object.freeze({
+            ...clickhouseDatasetSqlDialect,
+            name: dialect.name,
+            quoteIdentifier: (identifier) => dialect.quoteIdentifier(identifier),
+            quoteQualifiedName: (name) => name.split('.').map(part => dialect.quoteIdentifier(part)).join('.'),
+        });
+        resolved.set(dialect, rules);
+    }
+    return rules;
+}
 /** Resolve from the active factory, so a runtime builder override carries its dialect. */
 export function resolveDatasetSqlDialect(factory) {
-    return factory.datasetSqlDialect ?? clickhouseDatasetSqlDialect;
+    return factory.datasetSqlDialect
+        ? completeDatasetSqlDialect(factory.datasetSqlDialect)
+        : clickhouseDatasetSqlDialect;
 }

package/dist/utils/dataset-time-keys.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Multiple time axes per dataset (HQ-80).
+ *
+ * `timeKey` is a dataset's default time axis; `timeKeys` names the other axes
+ * a query may select with `query.timeKey`, such as `shipped_at` beside
+ * `created_at`. A query on another axis compiles against a view of the dataset
+ * whose `timeKey` is that axis, so grains, windows, shifts and time-range
+ * checks follow the selection without each of them knowing about it.
+ */
+interface TimeAxes {
+    readonly name?: string;
+    readonly timeKey?: string;
+    readonly timeKeys?: readonly string[];
+}
+/** Every time axis a query may select, the default first; empty without a `timeKey`. */
+export declare function datasetTimeKeys(dataset: TimeAxes): string[];
+/** The validation message for a query's `timeKey` selection, or undefined. */
+export declare function selectedTimeKeyError(dataset: TimeAxes, timeKey: unknown): string | undefined;
+/**
+ * True when a query selects an axis other than the dataset's default. Naming
+ * the default explicitly is the same query as omitting it.
+ */
+export declare function selectsAlternateTimeKey(dataset: TimeAxes, timeKey: string | undefined): timeKey is string;
+/**
+ * The dataset as seen by a query on `timeKey`: the selected axis becomes
+ * `timeKey` and the rest stay declared, so the view is itself a valid dataset
+ * and rebasing it again is a no-op. Throws for an axis the dataset does not
+ * declare; validate first to report it as a query error.
+ */
+export declare function datasetOnTimeKey<TDataset extends TimeAxes>(dataset: TDataset, timeKey: string | undefined): TDataset;
+export {};
+//# sourceMappingURL=dataset-time-keys.d.ts.map

package/dist/utils/dataset-time-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-time-keys.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-time-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,UAAU,QAAQ;IAChB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,EAAE,CAG3D;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAW5F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,IAAI,MAAM,CAEzG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,SAAS,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CASpH"}