@hypequery/datasets 0.23.1 → 0.25.0

package/dist/utils/filtered-aggregation-sql.js

@@ -1,69 +1,49 @@
 import { resolveFilterField } from '../query-planner.js';
-function renderMeasureFilterLiteral(value) {
-    if (value === null) {
-        return 'NULL';
-    }
-    if (typeof value === 'string') {
-        // 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.
-        return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
-    }
-    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}`);
-}
-function renderMeasureFilterCondition(ds, filter, joinCtx) {
+function renderMeasureFilterCondition(ds, filter, joinCtx, dialect) {
     const field = resolveFilterField(ds, filter.field, joinCtx);
+    const literal = (value) => dialect.measureFilterLiteral(value);
     switch (filter.operator) {
         case 'eq':
-            return `${field} = ${renderMeasureFilterLiteral(filter.value)}`;
+            return `${field} = ${literal(filter.value)}`;
         case 'neq':
-            return `${field} != ${renderMeasureFilterLiteral(filter.value)}`;
+            return `${field} != ${literal(filter.value)}`;
         case 'gt':
-            return `${field} > ${renderMeasureFilterLiteral(filter.value)}`;
+            return `${field} > ${literal(filter.value)}`;
         case 'gte':
-            return `${field} >= ${renderMeasureFilterLiteral(filter.value)}`;
+            return `${field} >= ${literal(filter.value)}`;
         case 'lt':
-            return `${field} < ${renderMeasureFilterLiteral(filter.value)}`;
+            return `${field} < ${literal(filter.value)}`;
         case 'lte':
-            return `${field} <= ${renderMeasureFilterLiteral(filter.value)}`;
+            return `${field} <= ${literal(filter.value)}`;
         case 'like':
-            return `${field} LIKE ${renderMeasureFilterLiteral(filter.value)}`;
+            return `${field} LIKE ${literal(filter.value)}`;
         case 'in':
         case 'notIn': {
             if (!Array.isArray(filter.value) || filter.value.length === 0) {
                 throw new Error(`"${filter.operator}" measure filters require a non-empty array.`);
             }
-            const values = filter.value.map(renderMeasureFilterLiteral).join(', ');
+            const values = filter.value.map(literal).join(', ');
             return `${field} ${filter.operator === 'in' ? 'IN' : 'NOT IN'} (${values})`;
         }
         case 'between': {
             if (!Array.isArray(filter.value) || filter.value.length !== 2) {
                 throw new Error('"between" measure filters require a two-item array.');
             }
-            return `${field} BETWEEN ${renderMeasureFilterLiteral(filter.value[0])} AND ${renderMeasureFilterLiteral(filter.value[1])}`;
+            return `${field} BETWEEN ${literal(filter.value[0])} AND ${literal(filter.value[1])}`;
         }
     }
 }
-export function applyFilteredAggregationExpression(ds, spec, fieldOrExpr, joinCtx) {
+export function applyFilteredAggregationExpression(ds, spec, fieldOrExpr, joinCtx, dialect) {
     if (!spec.filters?.length) {
         return fieldOrExpr;
     }
     const combinedCondition = spec.filters
-        .map(filter => renderMeasureFilterCondition(ds, filter, joinCtx))
+        .map(filter => renderMeasureFilterCondition(ds, filter, joinCtx, dialect))
         .map(condition => `(${condition})`)
         .join(' AND ');
     switch (spec.aggregation) {
         case 'sum':
-            return `if(${combinedCondition}, ${fieldOrExpr}, 0)`;
+            return dialect.filteredAggregateInput(combinedCondition, fieldOrExpr, '0');
         // Aggregate functions skip NULLs, so the NULL fallback excludes
         // non-matching rows from percentile/stddev/variance too.
         case 'count':
@@ -75,7 +55,10 @@ export function applyFilteredAggregationExpression(ds, spec, fieldOrExpr, joinCt
         case 'stddev':
         case 'variance':
         case 'approxCountDistinct':
-            return `if(${combinedCondition}, ${fieldOrExpr}, NULL)`;
+            return dialect.filteredAggregateInput(combinedCondition, fieldOrExpr, 'NULL');
+        case 'merge':
+            // A filtered merge needs -MergeIf; wrapping a state column in if() is a type error.
+            throw new Error('Measure filters are not supported on merge aggregations.');
         case 'argMax':
         case 'argMin':
             // NULL handling under argMax/argMin varies across ClickHouse versions.

package/dist/utils/groupable.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `groupable: false` declares a dimension that backs filters or measures but
+ * must not become a grouping key. The query schemas leave it out; the client
+ * refuses it too, as the Python planner does.
+ */
+export declare function notGroupableError(name: string): string;
+//# sourceMappingURL=groupable.d.ts.map

package/dist/utils/groupable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groupable.d.ts","sourceRoot":"","sources":["../../src/utils/groupable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/utils/groupable.js

@@ -0,0 +1,8 @@
+/**
+ * `groupable: false` declares a dimension that backs filters or measures but
+ * must not become a grouping key. The query schemas leave it out; the client
+ * refuses it too, as the Python planner does.
+ */
+export function notGroupableError(name) {
+    return `Dimension "${name}" is not groupable.`;
+}

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

@@ -1,8 +1,6 @@
 import type { MetricRef, MetricQuery, ExecutionContext, TimeGrain } from '../types.js';
 import type { QueryBuilderFactoryLike } from '../query-builder-protocol.js';
+import { type PlannedStatement } from './statement-parameters.js';
 import type { DerivedMetricSpec } from '../types.js';
-export declare function buildDerivedMetricSql(ref: MetricRef, spec: DerivedMetricSpec, query: MetricQuery, grain: TimeGrain | undefined, builderFactory: QueryBuilderFactoryLike, context?: ExecutionContext): {
-    sql: string;
-    params: unknown[];
-};
+export declare function buildDerivedMetricSql(ref: MetricRef, spec: DerivedMetricSpec, query: MetricQuery, grain: TimeGrain | undefined, builderFactory: QueryBuilderFactoryLike, context?: ExecutionContext): PlannedStatement;
 //# sourceMappingURL=metric-derived-query.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"metric-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/metric-derived-query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAoB,MAAM,8BAA8B,CAAC;AAiB9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKrD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,cAAc,EAAE,uBAAuB,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAiHpC"}
+{"version":3,"file":"metric-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/metric-derived-query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAoB,MAAM,8BAA8B,CAAC;AAQ9F,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAMrD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,cAAc,EAAE,uBAAuB,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAmHlB"}

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

@@ -1,62 +1,73 @@
+import { scopedDatasetSource } from './scoped-dataset-source.js';
 import { semanticQuerySyntaxErrors, semanticOrderDirection } from './semantic-query-syntax.js';
 /** Metric SQL compilation; factory selection and execution belong to the client. */
 import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
-import { applyAggregationSpec, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from '../query-planner.js';
-import { queryTimeFilterSql } from './query-timezone.js';
+import { assertRawSqlForDialect } from './raw-sql-dialect-check.js';
+import { applyAggregationSpec, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, } from '../query-planner.js';
+import { queryTimeFilter } from './query-timezone.js';
+import { StatementParameters } from './statement-parameters.js';
+import { formulaExpressionSql } from './derived-measure-sql.js';
 import { isTenantScopedFilter } from './metric-handle.js';
-import { getRuntimeTenantPredicate } from './tenant-runtime.js';
-import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './relationship-builder-plan.js';
+import { buildRelationshipBuilderContext } from './relationship-builder-plan.js';
 import { segmentFilters } from './segments.js';
 import { validateSQLIdentifier } from '../sql-utils.js';
 import { isQualifiedField } from './relationship-fields.js';
 import { validateDerivedCteGrouping } from './derived-cte-validation.js';
+import { datasetOnTimeKey } from './dataset-time-keys.js';
 export function buildDerivedMetricSql(ref, spec, query, grain, builderFactory, context) {
     const syntaxErrors = semanticQuerySyntaxErrors(query);
     if (syntaxErrors.length)
         throw new Error(syntaxErrors.join('; '));
     const dialect = resolveDatasetSqlDialect(builderFactory);
-    const ds = ref.dataset;
-    const joinCtx = buildRelationshipBuilderContext(ds, query, context);
+    assertRawSqlForDialect(ref.dataset, dialect);
+    const ds = datasetOnTimeKey(ref.dataset, query.timeKey);
+    const joinCtx = buildRelationshipBuilderContext(ds, query, context, dialect);
     // Build the CTE inner query using the builder
-    let cteBuilder = builderFactory.table(ds.source);
-    cteBuilder = applyRelationshipJoins(cteBuilder, joinCtx);
+    let cteBuilder = scopedDatasetSource({ builderFactory, ds, context, joinCtx, dialect, timezone: query.timezone });
     const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain, joinCtx, query.timezone, dialect);
     if (selectParts.length > 0) {
         cteBuilder = cteBuilder.select(selectParts);
     }
+    // Group before aggregating: the builder only infers GROUP BY when none is
+    // set, and cannot infer it from quoted aliases.
+    if (groupByParts.length > 0) {
+        cteBuilder = cteBuilder.groupBy(groupByParts);
+    }
     // Base aggregations
     const refAliases = {};
+    const inputNames = {};
     const aggregateAliases = [];
     for (const [alias, baseMetric] of Object.entries(spec.uses)) {
         const baseSpec = baseMetric.spec;
         if (baseSpec.__type !== 'aggregation_spec') {
             throw new Error(`Derived metric "${ref.name}" references non-base metric "${alias}".`);
         }
-        cteBuilder = applyAggregationSpec(cteBuilder, ds, baseSpec, alias, joinCtx);
-        refAliases[alias] = alias;
-        aggregateAliases.push(alias);
-    }
-    if (groupByParts.length > 0) {
-        cteBuilder = cteBuilder.groupBy(groupByParts);
+        const quoted = dialect.quoteIdentifier(alias);
+        cteBuilder = applyAggregationSpec(cteBuilder, ds, baseSpec, alias, joinCtx, dialect);
+        refAliases[alias] = quoted;
+        inputNames[alias] = alias;
+        aggregateAliases.push(quoted);
     }
     // Filters on CTE
-    const tenantColumn = resolveTenantFilterColumn(ds, context);
-    const tenantPredicate = getRuntimeTenantPredicate(context);
-    if (tenantPredicate && tenantColumn) {
-        cteBuilder = cteBuilder.where(qualifyBaseColumn(joinCtx, tenantColumn), tenantPredicate.operator, tenantPredicate.value);
-    }
     for (const filter of query.filters ?? []) {
         if (isTenantScopedFilter(ds, filter, context)) {
             throw new Error(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
         }
         const resolvedField = resolveFilterField(ds, filter.field, joinCtx);
-        cteBuilder = cteBuilder.where(queryTimeFilterSql(ds, filter.field, resolvedField, query.timezone), filter.operator, filter.value);
+        for (const predicate of queryTimeFilter(dialect, ds, filter, resolvedField, query.timezone)) {
+            cteBuilder = cteBuilder.where(predicate.expression, predicate.operator, predicate.value);
+        }
     }
     for (const filter of segmentFilters(ds, query.segments)) {
-        cteBuilder = cteBuilder.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) {
+            cteBuilder = cteBuilder.where(predicate.expression, predicate.operator, predicate.value);
+        }
     }
-    const { sql: cteSql, parameters: cteParams } = cteBuilder.toSQLWithParams();
-    const groupingErrors = validateDerivedCteGrouping(cteSql, aggregateAliases, groupByParts);
+    // Check the builder's own SQL: embedded text may be an opaque block marker.
+    // Replaced by a plan-level check in HQ-197.
+    const cteStatement = cteBuilder.toSQLWithParams();
+    const groupingErrors = validateDerivedCteGrouping(cteStatement.sql, aggregateAliases, groupByParts);
     if (groupingErrors.length > 0) {
         throw new Error(groupingErrors.join('; '));
     }
@@ -64,43 +75,39 @@ export function buildDerivedMetricSql(ref, spec, query, grain, builderFactory, c
     // because table('base') would fail schema typing
     const outerSelectParts = [];
     if (grain)
-        outerSelectParts.push('period');
+        outerSelectParts.push(dialect.quoteIdentifier('period'));
     for (const dim of query.dimensions ?? []) {
         // Joined dimensions surface from the CTE under their quoted qualified alias.
-        if (joinCtx && isQualifiedField(dim)) {
-            outerSelectParts.push(dialect.quoteIdentifier(dim));
-            continue;
-        }
-        validateSQLIdentifier(dim, 'dimension name');
-        outerSelectParts.push(dim);
+        if (!(joinCtx && isQualifiedField(dim)))
+            validateSQLIdentifier(dim, 'dimension name');
+        outerSelectParts.push(dialect.quoteIdentifier(dim));
     }
-    const formulaExpr = spec.formula(refAliases);
+    // Render through the dialect, like derived measures. FormulaExpr.toSQL()
+    // is kept for definition identity, not for planning.
     validateSQLIdentifier(ref.name, 'metric name');
-    outerSelectParts.push(`${formulaExpr.toSQL()} AS ${ref.name}`);
-    let sql = `WITH base AS (${cteSql}) SELECT ${outerSelectParts.join(', ')} FROM base`;
+    const formulaSql = formulaExpressionSql(dialect, spec.formula(inputNames).expression, name => {
+        const quoted = refAliases[name];
+        if (quoted === undefined || !Object.hasOwn(refAliases, name)) {
+            throw new Error(`Derived metric "${ref.name}" formula references undeclared input "${name}".`);
+        }
+        return quoted;
+    });
+    outerSelectParts.push(`${formulaSql} AS ${dialect.quoteIdentifier(ref.name)}`);
+    const parameters = new StatementParameters(dialect);
+    let text = `WITH base AS (${parameters.embedBuilder(cteBuilder, cteStatement)}) SELECT ${outerSelectParts.join(', ')} FROM base`;
     // ORDER BY
     if (query.orderBy && query.orderBy.length > 0) {
         const orderParts = query.orderBy.map(o => {
-            if (joinCtx && isQualifiedField(o.field)) {
-                return `${dialect.quoteIdentifier(o.field)} ${semanticOrderDirection(o.direction)}`;
-            }
-            validateSQLIdentifier(o.field, 'order by field');
-            return `${o.field} ${semanticOrderDirection(o.direction)}`;
+            if (!(joinCtx && isQualifiedField(o.field)))
+                validateSQLIdentifier(o.field, 'order by field');
+            return dialect.orderTerm(dialect.quoteIdentifier(o.field), semanticOrderDirection(o.direction));
         });
-        sql += ` ORDER BY ${orderParts.join(', ')}`;
+        text += ` ORDER BY ${orderParts.join(', ')}`;
     }
     else if (grain) {
-        sql += ' ORDER BY period';
-    }
-    if (query.limit != null) {
-        // Ensure limit is a safe integer
-        const limit = Math.floor(Math.abs(query.limit));
-        sql += ` LIMIT ${limit}`;
-    }
-    if (query.offset != null) {
-        // Ensure offset is a safe integer
-        const offset = Math.floor(Math.abs(query.offset));
-        sql += ` OFFSET ${offset}`;
+        text += ` ORDER BY ${dialect.orderTerm(dialect.quoteIdentifier('period'))}`;
     }
-    return { sql, params: cteParams };
+    // Ensure limit and offset are safe integers.
+    text += dialect.paginate(query.limit != null ? Math.floor(Math.abs(query.limit)) : undefined, query.offset != null ? Math.floor(Math.abs(query.offset)) : undefined);
+    return { text, parameters };
 }

package/dist/utils/metric-query-builder.d.ts

@@ -1,5 +1,5 @@
 import type { MetricRef, MetricQuery, ExecutionContext, TimeGrain } from '../types.js';
 import type { QueryBuilderFactoryLike, QueryBuilderLike } from '../query-builder-protocol.js';
 import type { AggregationSpec, AnyDatasetInstance } from '../types.js';
-export declare function buildMetricQueryBuilder(ref: MetricRef, spec: AggregationSpec, ds: AnyDatasetInstance, query: MetricQuery, grain: TimeGrain | undefined, builderFactory: QueryBuilderFactoryLike, context?: ExecutionContext): QueryBuilderLike;
+export declare function buildMetricQueryBuilder(ref: MetricRef, spec: AggregationSpec, dataset: AnyDatasetInstance, query: MetricQuery, grain: TimeGrain | undefined, builderFactory: QueryBuilderFactoryLike, context?: ExecutionContext): QueryBuilderLike;
 //# sourceMappingURL=metric-query-builder.d.ts.map

package/dist/utils/metric-query-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metric-query-builder.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-builder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAkB9F,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvE,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,eAAe,EACrB,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,cAAc,EAAE,uBAAuB,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAwDlB"}
+{"version":3,"file":"metric-query-builder.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-builder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAa9F,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvE,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,cAAc,EAAE,uBAAuB,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAsDlB"}

package/dist/utils/metric-query-builder.js

@@ -1,50 +1,52 @@
+import { scopedDatasetSource } from './scoped-dataset-source.js';
 import { semanticQuerySyntaxErrors } from './semantic-query-syntax.js';
 /** Metric SQL compilation; factory selection and execution belong to the client. */
 import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
-import { applyAggregationSpec, appendOrderLimitOffset, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from '../query-planner.js';
-import { queryTimeFilterSql } from './query-timezone.js';
+import { assertRawSqlForDialect } from './raw-sql-dialect-check.js';
+import { applyAggregationSpec, appendOrderLimitOffset, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, } from '../query-planner.js';
+import { queryTimeFilter } from './query-timezone.js';
 import { isTenantScopedFilter } from './metric-handle.js';
-import { getRuntimeTenantPredicate } from './tenant-runtime.js';
-import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './relationship-builder-plan.js';
+import { buildRelationshipBuilderContext } from './relationship-builder-plan.js';
 import { segmentFilters } from './segments.js';
-export function buildMetricQueryBuilder(ref, spec, ds, query, grain, builderFactory, context) {
+import { datasetOnTimeKey } from './dataset-time-keys.js';
+export function buildMetricQueryBuilder(ref, spec, dataset, query, grain, builderFactory, context) {
     const syntaxErrors = semanticQuerySyntaxErrors(query);
     if (syntaxErrors.length)
         throw new Error(syntaxErrors.join('; '));
+    const ds = datasetOnTimeKey(dataset, query.timeKey);
     const dialect = resolveDatasetSqlDialect(builderFactory);
-    const joinCtx = buildRelationshipBuilderContext(ds, query, context);
-    let qb = builderFactory.table(ds.source);
-    qb = applyRelationshipJoins(qb, joinCtx);
+    assertRawSqlForDialect(ds, dialect);
+    const joinCtx = buildRelationshipBuilderContext(ds, query, context, dialect);
+    let qb = scopedDatasetSource({ builderFactory, ds, context, joinCtx, dialect, timezone: query.timezone });
     const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain, joinCtx, query.timezone, dialect);
     if (selectParts.length > 0) {
         qb = qb.select(selectParts);
     }
-    // Aggregation (appends to select, auto-sets groupBy on non-agg columns)
-    qb = applyAggregationSpec(qb, ds, spec, ref.name, joinCtx);
-    // Explicit groupBy (ensures period + dims are grouped even if aggregation auto-groupBy misses them)
+    // Group before aggregating: the builder only infers GROUP BY when none is
+    // set, and cannot infer it from quoted aliases.
     if (groupByParts.length > 0) {
         qb = qb.groupBy(groupByParts);
     }
-    // Tenant auto-injection
-    const tenantColumn = resolveTenantFilterColumn(ds, context);
-    const tenantPredicate = getRuntimeTenantPredicate(context);
-    if (tenantPredicate && tenantColumn) {
-        qb = qb.where(qualifyBaseColumn(joinCtx, tenantColumn), tenantPredicate.operator, tenantPredicate.value);
-    }
+    qb = applyAggregationSpec(qb, ds, spec, ref.name, joinCtx, dialect);
     // User filters
     for (const filter of query.filters ?? []) {
         if (isTenantScopedFilter(ds, filter, context)) {
             throw new Error(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
         }
         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: author-defined, so they resolve dimensions directly rather
     // than through the caller-facing 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);
+        }
     }
     // Order, limit, offset
-    qb = appendOrderLimitOffset(qb, query.orderBy, grain, query.limit, query.offset, joinCtx, dialect);
+    qb = appendOrderLimitOffset(qb, query.orderBy, grain, query.limit, query.offset, joinCtx, dialect, { ds, dimensions: query.dimensions ?? [] });
     return qb;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"metric-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-validation.ts"],"names":[],"mappings":"AACA,gFAAgF;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAI9E,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAM3G,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAgIlB"}
+{"version":3,"file":"metric-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-validation.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAI9E,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQ3G,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAuIlB"}

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

@@ -1,3 +1,4 @@
+import { notGroupableError } from './groupable.js';
 import { semanticQuerySyntaxErrors } from './semantic-query-syntax.js';
 import { validateFilterValue } from '../validation.js';
 import { queryTimezoneErrors } from './query-timezone.js';
@@ -8,10 +9,15 @@ import { validateTenantRuntime } from './tenant-runtime.js';
 import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
 import { validateQualifiedFilter, validateRelationshipTenantRuntime } from './relationship-validation.js';
 import { segmentSelectionErrors } from './segments.js';
+import { datasetOnTimeKey, selectedTimeKeyError } from './dataset-time-keys.js';
+import { enforcedConstraintErrors } from './enforced-constraints.js';
 export function validateMetricQueryInput(metric, query, context) {
     const errors = [...semanticQuerySyntaxErrors(query), ...protocolMetricCapabilityErrors(metric, query), ...queryTimezoneErrors(query.timezone)];
     const ref = getMetricRef(metric);
-    const ds = ref.dataset;
+    const timeKeyError = selectedTimeKeyError(ref.dataset, query.timeKey);
+    if (timeKeyError)
+        errors.push(timeKeyError);
+    const ds = timeKeyError ? ref.dataset : datasetOnTimeKey(ref.dataset, query.timeKey);
     const dimensionNames = Object.keys(ds.dimensions);
     const filterNames = Object.keys(ds.filters);
     const grain = getMetricGrain(metric, query);
@@ -28,6 +34,7 @@ export function validateMetricQueryInput(metric, query, context) {
     if (relationshipTenantError) {
         errors.push(relationshipTenantError);
     }
+    errors.push(...enforcedConstraintErrors(ds, context, query.filters?.length ?? 0));
     if (metric.__type === 'grained_metric_ref' && query.by && query.by !== metric.grain) {
         errors.push(`Metric "${ref.name}" is already grained by "${metric.grain}" and cannot be queried with by="${query.by}".`);
     }
@@ -38,11 +45,17 @@ export function validateMetricQueryInput(metric, query, context) {
             if (resolution?.error) {
                 errors.push(resolution.error);
             }
+            else if (resolution?.resolved?.targetDimension.groupable === false) {
+                errors.push(notGroupableError(dim));
+            }
             continue;
         }
         if (!dimensionNames.includes(dim)) {
             errors.push(`Unknown dimension "${dim}". Available: ${dimensionNames.join(', ')}`);
         }
+        else if (ds.dimensions[dim]?.groupable === false) {
+            errors.push(notGroupableError(dim));
+        }
     }
     // Validate filters
     for (const filter of query.filters ?? []) {

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

@@ -4,6 +4,7 @@
  * `approxCountDistinct` runs locally, but it is an expression extension 2 and
  * deployment contract 3 feature (RFC 0015). Publishing emits contract 2 until
  * it can emit contract 3, so it refuses the measure with an error naming it.
+ * `merge` reads ClickHouse aggregate-state columns and has no contract form.
  */
 import type { ProtocolAggregation } from '@hypequery/protocol';
 import type { AggregationType } from '../types.js';

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

@@ -1 +1 @@
-{"version":3,"file":"portable-aggregations.d.ts","sourceRoot":"","sources":["../../src/utils/portable-aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;AAE/E,2FAA2F;AAC3F,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAQrB"}
+{"version":3,"file":"portable-aggregations.d.ts","sourceRoot":"","sources":["../../src/utils/portable-aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;AAE/E,2FAA2F;AAC3F,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAcrB"}

package/dist/utils/portable-aggregations.js

@@ -4,9 +4,14 @@
  * `approxCountDistinct` runs locally, but it is an expression extension 2 and
  * deployment contract 3 feature (RFC 0015). Publishing emits contract 2 until
  * it can emit contract 3, so it refuses the measure with an error naming it.
+ * `merge` reads ClickHouse aggregate-state columns and has no contract form.
  */
 /** Returns `aggregation` when publishing can carry it; otherwise throws naming `owner`. */
 export function requirePortableAggregation(aggregation, owner) {
+    if (aggregation === 'merge') {
+        throw new Error(`${owner} uses merge, which cannot be published: the deployment contract has no aggregate-state ` +
+            'measures. Use it for local queries only.');
+    }
     if (aggregation === 'approxCountDistinct') {
         throw new Error(`${owner} uses approxCountDistinct, which cannot be published yet: approximate aggregations ` +
             'need deployment contract 3 (RFC 0015). Use it for local queries, or publish countDistinct instead.');

package/dist/utils/protocol-schema-conversion.d.ts

@@ -0,0 +1,12 @@
+import { type CanonicalValue } from '@hypequery/protocol';
+export declare class ProtocolSchemaAdapterError extends TypeError {
+    readonly path: string;
+    constructor(message: string, path?: string);
+}
+export type ProtocolSchemaDraft = Record<string, unknown>;
+export declare function canonicalValue(input: unknown, path: string): CanonicalValue;
+/** Values of a TypeScript enum object, without the reverse mappings of numeric members. */
+export declare function nativeEnumValues(input: Record<string, string | number>): readonly (string | number)[];
+export declare function annotate(description: unknown, result: ProtocolSchemaDraft): ProtocolSchemaDraft;
+export declare function withDefault(inner: ProtocolSchemaDraft, value: unknown, path: string): ProtocolSchemaDraft;
+//# sourceMappingURL=protocol-schema-conversion.d.ts.map

package/dist/utils/protocol-schema-conversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-schema-conversion.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-schema-conversion.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAElF,qBAAa,0BAA2B,SAAQ,SAAS;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,SAAM;CAKxC;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAgC3E;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAKrG;AAED,wBAAgB,QAAQ,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAE/F;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,GACX,mBAAmB,CAKrB"}

package/dist/utils/protocol-schema-conversion.js

@@ -0,0 +1,61 @@
+import { validateCanonicalValue } from '@hypequery/protocol';
+export class ProtocolSchemaAdapterError extends TypeError {
+    path;
+    constructor(message, path = '$') {
+        super(`${message} at ${path}`);
+        this.name = 'ProtocolSchemaAdapterError';
+        this.path = path;
+    }
+}
+export function canonicalValue(input, path) {
+    try {
+        if (Array.isArray(input)) {
+            return validateCanonicalValue({
+                $hypequery: {
+                    type: 'array',
+                    version: 1,
+                    values: input.map((item, index) => canonicalValue(item, `${path}[${index}]`)),
+                },
+            });
+        }
+        if (typeof input === 'object' && input !== null) {
+            if ('$hypequery' in input)
+                return validateCanonicalValue(input);
+            const prototype = Object.getPrototypeOf(input);
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw new ProtocolSchemaAdapterError('Default is not portable plain data', path);
+            }
+            return validateCanonicalValue({
+                $hypequery: {
+                    type: 'map',
+                    version: 1,
+                    entries: Object.entries(input)
+                        .sort(([left], [right]) => left.localeCompare(right))
+                        .map(([key, value]) => [key, canonicalValue(value, `${path}.${key}`)]),
+                },
+            });
+        }
+        return validateCanonicalValue(input);
+    }
+    catch (error) {
+        if (error instanceof ProtocolSchemaAdapterError)
+            throw error;
+        throw new ProtocolSchemaAdapterError('Default is not a canonical protocol value', path);
+    }
+}
+/** Values of a TypeScript enum object, without the reverse mappings of numeric members. */
+export function nativeEnumValues(input) {
+    const values = Object.keys(input)
+        .filter(key => typeof input[String(input[key])] !== 'number')
+        .map(key => input[key]);
+    return [...new Set(values)];
+}
+export function annotate(description, result) {
+    return typeof description === 'string' ? { ...result, description } : result;
+}
+export function withDefault(inner, value, path) {
+    if (inner.kind === 'void') {
+        throw new ProtocolSchemaAdapterError('Void schemas cannot carry defaults', path);
+    }
+    return { ...inner, default: canonicalValue(value, `${path}.default`) };
+}

package/dist/utils/query-field-references.d.ts

@@ -0,0 +1,10 @@
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
+/**
+ * Every field a query reads, as the planner will: requested names, the fields
+ * named filters and segments stand for, and, for each selected measure (every
+ * base measure when `measures` is omitted), its dependencies and the fields
+ * its fixed filters read. A measure filter can name `<relationship>.<field>`,
+ * so selecting a measure can join a relationship the request never names.
+ */
+export declare function queryFieldReferences(dataset: AnyDatasetInstance, query: DatasetQuery): string[];
+//# sourceMappingURL=query-field-references.d.ts.map

package/dist/utils/query-field-references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-field-references.d.ts","sourceRoot":"","sources":["../../src/utils/query-field-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAgB,MAAM,aAAa,CAAC;AASlF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAsB/F"}

package/dist/utils/query-field-references.js

@@ -0,0 +1,38 @@
+import { baseMeasureNames, isBaseMeasure } from './dataset-measures.js';
+import { measureDependencies } from './measure-dependencies.js';
+import { segmentFilters } from './segments.js';
+function filterField(dataset, filter) {
+    return dataset.filters?.[filter.field]?.field ?? filter.field;
+}
+/**
+ * Every field a query reads, as the planner will: requested names, the fields
+ * named filters and segments stand for, and, for each selected measure (every
+ * base measure when `measures` is omitted), its dependencies and the fields
+ * its fixed filters read. A measure filter can name `<relationship>.<field>`,
+ * so selecting a measure can join a relationship the request never names.
+ */
+export function queryFieldReferences(dataset, query) {
+    const names = [
+        ...(query.dimensions ?? []),
+        ...(query.filters ?? []).map(filter => filterField(dataset, filter)),
+        ...segmentFilters(dataset, query.segments).map(filter => filterField(dataset, filter)),
+        ...(query.orderBy ?? []).map(order => order.field),
+        ...(query.having ?? []).map(condition => condition.measure),
+    ];
+    const visited = new Set();
+    const visit = (name) => {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        names.push(name);
+        if (!Object.hasOwn(dataset.measures, name))
+            return;
+        const definition = dataset.measures[name];
+        measureDependencies(definition).forEach(visit);
+        if (isBaseMeasure(definition)) {
+            names.push(...(definition.filters ?? []).map(filter => filterField(dataset, filter)));
+        }
+    };
+    (query.measures ?? baseMeasureNames(dataset.measures)).forEach(visit);
+    return names;
+}