@hypequery/datasets 0.23.1 → 0.25.0

package/dist/utils/build-dataset-query-builder.js

@@ -1,34 +1,39 @@
+import { scopedDatasetSource } from './scoped-dataset-source.js';
 import { relationshipMeasureExpressions } from './relationship-measure-sql.js';
 import { measureToAggregationSpec } from './dataset-normalization.js';
 import { applyAggregationSpec } from '../query-planner.js';
 import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
-import { queryTimeFilterSql } from './query-timezone.js';
+import { assertRawSqlForDialect } from './raw-sql-dialect-check.js';
+import { queryTimeFilter } from './query-timezone.js';
 import { selectedTimeMeasures } from './time-query-measures.js';
 import { baseMeasureNames, getBaseMeasure } from './dataset-measures.js';
-import { appendOrderLimitOffset, applyMeasureDefinition, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from '../query-planner.js';
+import { appendOrderLimitOffset, applyMeasureDefinition, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, } from '../query-planner.js';
 import { validateDatasetQueryInput } from './dataset-query-validation.js';
-import { getRuntimeTenantPredicate } from './tenant-runtime.js';
-import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './relationship-builder-plan.js';
+import { buildRelationshipBuilderContext } from './relationship-builder-plan.js';
 import { hasSelectedDerivedMeasure, } from './dataset-derived-query.js';
 import { segmentFilters } from './segments.js';
-export function buildDatasetQueryBuilder(ds, query, options) {
-    if (selectedTimeMeasures(ds, query).size) {
+import { datasetOnTimeKey } from './dataset-time-keys.js';
+export function buildDatasetQueryBuilder(dataset, query, options) {
+    if (selectedTimeMeasures(dataset, query).size) {
         throw new Error('A time-based dataset query needs the time-measure SQL planner; use createDatasetClient().toSQL().');
     }
-    if (hasSelectedDerivedMeasure(ds, query)) {
+    if (hasSelectedDerivedMeasure(dataset, query)) {
         throw new Error('A derived dataset query needs the outer SQL projection; use createDatasetClient().toSQL().');
     }
     if (query.having?.length) {
         throw new Error('A dataset query with having needs the outer SQL projection; use createDatasetClient().toSQL().');
     }
-    const validation = validateDatasetQueryInput(ds, query, options.context);
+    const validation = validateDatasetQueryInput(dataset, query, options.context);
     if (!validation.valid) {
         throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
     }
+    const ds = datasetOnTimeKey(dataset, query.timeKey);
     const dialect = resolveDatasetSqlDialect(options.builderFactory);
+    assertRawSqlForDialect(ds, dialect);
     const joinCtx = buildRelationshipBuilderContext(ds, query, options.context, dialect);
-    let qb = options.builderFactory.table(ds.source);
-    qb = applyRelationshipJoins(qb, joinCtx);
+    let qb = scopedDatasetSource({
+        builderFactory: options.builderFactory, ds, context: options.context, joinCtx, dialect, timezone: query.timezone,
+    });
     const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], query.by, joinCtx, query.timezone, dialect);
     const measureNames = query.measures ?? baseMeasureNames(ds.measures);
     if (selectParts.length > 0) {
@@ -39,27 +44,27 @@ export function buildDatasetQueryBuilder(ds, query, options) {
         qb = qb.groupBy(groupByParts);
     for (const measureName of measureNames) {
         if (measureName.includes('.')) {
-            const expressions = relationshipMeasureExpressions(ds, measureName, joinCtx);
-            qb = applyAggregationSpec(qb, ds, measureToAggregationSpec(measureName, expressions.definition), dialect.quoteIdentifier(measureName), joinCtx, expressions);
+            const expressions = relationshipMeasureExpressions(ds, measureName, joinCtx, dialect);
+            qb = applyAggregationSpec(qb, ds, measureToAggregationSpec(measureName, expressions.definition), measureName, joinCtx, dialect, expressions);
             continue;
         }
         const definition = getBaseMeasure(ds.measures, measureName);
         if (!definition)
             throw new Error(`Measure "${measureName}" is not a base measure.`);
-        qb = applyMeasureDefinition(qb, ds, measureName, definition, joinCtx);
-    }
-    const tenantColumn = resolveTenantFilterColumn(ds, options.context);
-    const tenantPredicate = getRuntimeTenantPredicate(options.context);
-    if (tenantPredicate && tenantColumn) {
-        qb = qb.where(qualifyBaseColumn(joinCtx, tenantColumn), tenantPredicate.operator, tenantPredicate.value);
+        qb = applyMeasureDefinition(qb, ds, measureName, definition, joinCtx, dialect);
     }
     for (const filter of query.filters ?? []) {
         const resolvedField = resolveFilterField(ds, filter.field, joinCtx);
-        qb = qb.where(queryTimeFilterSql(ds, filter.field, resolvedField, query.timezone), filter.operator, filter.value);
+        for (const predicate of queryTimeFilter(dialect, ds, filter, resolvedField, query.timezone)) {
+            qb = qb.where(predicate.expression, predicate.operator, predicate.value);
+        }
     }
     // Segments are author-defined, so they bypass the caller filter allow-list.
     for (const filter of segmentFilters(ds, query.segments)) {
-        qb = qb.where(resolveDimensionExpression(ds, filter.field, joinCtx), filter.operator, filter.value);
+        const predicates = queryTimeFilter(dialect, ds, filter, resolveDimensionExpression(ds, filter.field, joinCtx), query.timezone, { field: 'dimension' });
+        for (const predicate of predicates) {
+            qb = qb.where(predicate.expression, predicate.operator, predicate.value);
+        }
     }
-    return appendOrderLimitOffset(qb, query.orderBy, options.skipDefaultOrderBy ? undefined : query.by, options.executionLimit ?? query.limit, query.offset, joinCtx, dialect);
+    return appendOrderLimitOffset(qb, query.orderBy, options.skipDefaultOrderBy ? undefined : query.by, options.executionLimit ?? query.limit, query.offset, joinCtx, dialect, { ds, dimensions: query.dimensions ?? [] });
 }

package/dist/utils/by-name.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function byName<T extends {
+    readonly name: string;
+}>(left: T, right: T): number;
+//# sourceMappingURL=by-name.d.ts.map

package/dist/utils/by-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"by-name.d.ts","sourceRoot":"","sources":["../../src/utils/by-name.ts"],"names":[],"mappings":"AAkCA;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAIrF"}

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,sBAiHP,CAAC"}

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

@@ -1,6 +1,148 @@
-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})`,
+    // Calendar truncation returns a zone-less Date; later day arithmetic on it
+    // would run in the server zone, not the query zone.
+    truncateTimeInZone: (time, grain, timezone) => `toDateTime64(${TRUNCATE_FUNCTIONS[grain]}(${time}), 9, ${timezone})`,
+    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

@@ -6,5 +6,5 @@ export interface PreparedDatasetQuery {
     execute(): Promise<Record<string, unknown>[]>;
 }
 /** The one dispatch point for dataset preview and query-builder execution. */
-export declare function prepareDatasetQuery(dataset: AnyDatasetInstance, input: DatasetQuery, options: DatasetQueryExecutionOptions, mode?: 'execution' | 'logical'): PreparedDatasetQuery;
+export declare function prepareDatasetQuery(source: AnyDatasetInstance, input: DatasetQuery, options: DatasetQueryExecutionOptions, mode?: 'execution' | 'logical'): PreparedDatasetQuery;
 //# sourceMappingURL=compile-dataset-query.d.ts.map

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":"AAIA,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;AAWpE,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,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,IAAI,GAAE,WAAW,GAAG,SAAuB,GAC1C,oBAAoB,CAyEtB"}

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

@@ -1,3 +1,6 @@
+import { queryReadsFinal, withFinalSafety } from './dataset-source.js';
+import { buildRelationshipBuilderContext } from './relationship-builder-plan.js';
+import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
 import { queryMeasureDefinitions } from './relationship-measures.js';
 import { buildDatasetQueryBuilder } from './build-dataset-query-builder.js';
 import { baseMeasureNames } from './dataset-measures.js';
@@ -7,8 +10,13 @@ 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';
+import { datasetOnTimeKey, selectedTimeKeyError } from './dataset-time-keys.js';
 /** The one dispatch point for dataset preview and query-builder execution. */
-export function prepareDatasetQuery(dataset, input, options, mode = 'execution') {
+export function prepareDatasetQuery(source, input, options, mode = 'execution') {
+    // Every planner below compiles against the selected time axis. An unknown
+    // axis is left for each planner's validation to report as a query error.
+    const dataset = selectedTimeKeyError(source, input.timeKey) ? source : datasetOnTimeKey(source, input.timeKey);
     const query = structuredClone({
         ...input,
         limit: mode === 'execution' ? resolveResultLimit(input.limit, dataset.limits).limit : input.limit,
@@ -23,19 +31,25 @@ export function prepareDatasetQuery(dataset, input, options, mode = 'execution')
     let execute;
     let plan;
     const abortSignal = options.context?.abortSignal;
+    // Raw-SQL plans lose builder settings, so they carry the FINAL pin in their SQL.
+    // Called after planning, which validates the query and its enforced constraints.
+    const readsFinal = () => queryReadsFinal(dataset, buildRelationshipBuilderContext(dataset, query, options.context, resolveDatasetSqlDialect(options.builderFactory)));
     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 = withFinalSafety(readsFinal(), renderStatement(planned.statement));
+        const preflight = withFinalSafety(readsFinal(), 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);
+        const derived = renderStatement(buildDerivedDatasetSql(dataset, query, executionOptions, buildDatasetQueryBuilder));
+        statement = withFinalSafety(readsFinal(), derived);
         execute = () => options.builderFactory.rawQuery(statement.sql, statement.parameters, { abortSignal });
     }
     else {
@@ -53,7 +67,7 @@ export function prepareDatasetQuery(dataset, input, options, mode = 'execution')
         filters: Object.freeze((query.filters ?? []).map(({ field, operator }) => Object.freeze({ field, operator }))),
         having: Object.freeze((query.having ?? []).map(({ measure, operator }) => Object.freeze({ measure, operator }))),
         segments: Object.freeze([...(query.segments ?? [])]),
-        by: query.by, timezone: query.timezone,
+        by: query.by, timeKey: query.timeKey, timezone: query.timezone,
         effectiveLimit: query.limit, executionLimit, offset: query.offset ?? 0,
         parameterCount: statement.parameters.length,
         preflightStatementCount: preflightStatements.length,

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

@@ -11,7 +11,7 @@
  *
  * Two categories of check live here:
  *
- * - **Identifier safety.** `source`, `tenantKey`, `timeKey`, dimension columns
+ * - **Identifier safety.** `source`, `tenantKey`, `timeKey`, `timeKeys`, dimension columns
  *   and measure fields are all interpolated into SQL as identifiers. They are
  *   validated once here rather than trusted at every call site that builds a
  *   predicate from them.

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,CAmFN"}