@hypequery/datasets 0.23.1 → 0.25.0

package/dist/query-planner.js

@@ -1,17 +1,17 @@
 import { semanticOrderDirection } from './utils/semantic-query-syntax.js';
 import { queryTimeSql } from './utils/query-timezone.js';
 import { assertNoRawSqlUnderJoins } from './utils/sql-under-joins.js';
-import { GRAIN_FUNCTIONS } from "./constants.js";
+import { isSupportedTimeGrain } from "./constants.js";
 import { applyFilteredAggregationExpression } from './utils/filtered-aggregation-sql.js';
 import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
-import { clickhouseDatasetSqlDialect } from './utils/clickhouse-dataset-sql-dialect.js';
 import { isQualifiedField } from './utils/relationship-fields.js';
-import { qualifyBaseColumn, resolveQualifiedColumn, } from './utils/relationship-builder-plan.js';
+import { qualifyBaseColumn, resolveQualifiedExpression, } from './utils/relationship-builder-plan.js';
 import { measureToAggregationSpec } from './utils/dataset-normalization.js';
 import { validatePercentileLevel } from './measure.js';
+import { assertAggregateStateFunction } from './utils/aggregate-state-functions.js';
 export function resolveDimensionExpression(ds, dimensionName, joinCtx) {
     if (joinCtx && isQualifiedField(dimensionName)) {
-        return resolveQualifiedColumn(ds, dimensionName);
+        return resolveQualifiedExpression(ds, dimensionName, joinCtx);
     }
     const definition = ds.dimensions[dimensionName];
     if (definition?.sql) {
@@ -22,50 +22,51 @@ export function resolveDimensionExpression(ds, dimensionName, joinCtx) {
 }
 export function resolveFilterField(ds, filterField, joinCtx) {
     if (joinCtx && isQualifiedField(filterField)) {
-        return resolveQualifiedColumn(ds, filterField);
+        return resolveQualifiedExpression(ds, filterField, joinCtx);
     }
     const resolvedField = ds.filters[filterField]?.field ?? filterField;
     return resolveDimensionExpression(ds, resolvedField, joinCtx);
 }
-export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx, timezone, dialect = clickhouseDatasetSqlDialect) {
+export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx, timezone, dialect) {
     const selectParts = [];
     const groupByParts = new Set();
     if (grain) {
-        const fn = GRAIN_FUNCTIONS[grain];
-        if (!fn) {
+        if (!isSupportedTimeGrain(grain)) {
             throw new Error(`Unsupported time grain "${grain}".`);
         }
         const time = resolveDimensionExpression(ds, String(ds.timeKey), joinCtx);
-        selectParts.push(`${fn}(${queryTimeSql(time, timezone)}) AS period`);
-        groupByParts.add("period");
+        const period = dialect.quoteIdentifier('period');
+        selectParts.push(`${dialect.truncateTime(queryTimeSql(dialect, time, timezone), grain)} AS ${period}`);
+        groupByParts.add(period);
     }
     for (const dimensionName of dimensions) {
         const expression = resolveDimensionExpression(ds, dimensionName, joinCtx);
-        if (joinCtx) {
-            // With joins in scope, every selection is table-qualified and aliased so
-            // grouping/ordering can reference the alias unambiguously.
-            const alias = isQualifiedField(dimensionName)
-                ? dialect.quoteIdentifier(dimensionName)
-                : dimensionName;
-            selectParts.push(`${expression} AS ${alias}`);
-            groupByParts.add(alias);
-        }
-        else if (expression === dimensionName) {
+        // Every generated alias is quoted: reserved words and engines that fold
+        // unquoted case (Postgres) must keep the semantic name. With joins in
+        // scope every selection is table-qualified, so it is always aliased.
+        if (!joinCtx && expression === dimensionName) {
             selectParts.push(dimensionName);
             groupByParts.add(dimensionName);
         }
         else {
-            selectParts.push(`${expression} AS ${dimensionName}`);
-            groupByParts.add(dimensionName);
+            const alias = dialect.quoteIdentifier(dimensionName);
+            selectParts.push(`${expression} AS ${alias}`);
+            // A qualified alias (`customer.tier`) can resolve to the physical joined
+            // column, so group on its guarded expression: the match marker stays
+            // part of the key whatever the engine's alias-resolution rules.
+            groupByParts.add(joinCtx && isQualifiedField(dimensionName) ? expression : alias);
         }
     }
     return { selectParts, groupByParts: Array.from(groupByParts) };
 }
-export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions) {
+export function applyAggregationSpec(qb, ds, spec, name, joinCtx, dialect, expressions) {
+    // The semantic name is the output alias, quoted so it survives reserved
+    // words and case folding; messages keep the unquoted name.
+    const alias = dialect.quoteIdentifier(name);
     if (spec.sql) {
-        assertNoRawSqlUnderJoins('measure', alias, spec.sql, joinCtx);
+        assertNoRawSqlUnderJoins('measure', name, spec.sql, joinCtx);
     }
-    const fieldOrExpr = expressions?.field ?? applyFilteredAggregationExpression(ds, spec, spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx), joinCtx);
+    const fieldOrExpr = expressions?.field ?? applyFilteredAggregationExpression(ds, spec, spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx), joinCtx, dialect);
     switch (spec.aggregation) {
         case "sum":
             return qb.sum(fieldOrExpr, alias);
@@ -82,7 +83,7 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
         case "argMax":
         case "argMin": {
             if (!spec.argField) {
-                throw new Error(`Aggregation "${spec.aggregation}" for "${alias}" requires an argField ("by" column).`);
+                throw new Error(`Aggregation "${spec.aggregation}" for "${name}" requires an argField ("by" column).`);
             }
             const argExpr = expressions?.arg ?? resolveDimensionExpression(ds, spec.argField, joinCtx);
             if (spec.aggregation === "argMax") {
@@ -98,7 +99,7 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
         }
         case "percentile": {
             if (spec.level == null) {
-                throw new Error(`Aggregation "percentile" for "${alias}" requires a level.`);
+                throw new Error(`Aggregation "percentile" for "${name}" requires a level.`);
             }
             validatePercentileLevel(spec.level);
             if (!qb.quantile) {
@@ -111,6 +112,16 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
                 throw new Error('Query builder does not support approxCountDistinct aggregations.');
             }
             return qb.approxCountDistinct(fieldOrExpr, alias);
+        case "merge": {
+            assertAggregateStateFunction(spec.stateFunction, `Measure "${name}"`);
+            if (spec.filters?.length) {
+                throw new Error(`Measure filters are not supported on merge aggregations ("${name}").`);
+            }
+            if (!qb.mergeState) {
+                throw new Error('Query builder does not support merge aggregations (mergeState).');
+            }
+            return qb.mergeState(spec.stateFunction, fieldOrExpr, alias);
+        }
         case "stddev":
             if (!qb.stddev) {
                 throw new Error('Query builder does not support stddev aggregations.');
@@ -125,20 +136,28 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
             throw new Error(`Unknown aggregation type: ${spec.aggregation}`);
     }
 }
-export function applyMeasureDefinition(qb, ds, name, definition, joinCtx) {
-    return applyAggregationSpec(qb, ds, measureToAggregationSpec(name, definition), name, joinCtx);
+export function applyMeasureDefinition(qb, ds, name, definition, joinCtx, dialect) {
+    return applyAggregationSpec(qb, ds, measureToAggregationSpec(name, definition), name, joinCtx, dialect);
 }
-export function appendOrderLimitOffset(qb, orderBy, grain, limit, offset, joinCtx, dialect = clickhouseDatasetSqlDialect) {
+/**
+ * Appends ORDER BY, LIMIT and OFFSET. Under joins, an order on a selected
+ * qualified dimension repeats its guarded expression (the GROUP BY key) rather
+ * than naming the alias, which the engine may resolve to the raw joined column;
+ * any other qualified order (a related measure) sorts by its quoted alias.
+ */
+export function appendOrderLimitOffset(qb, orderBy, grain, limit, offset, joinCtx, dialect, selection) {
     if (orderBy && orderBy.length > 0) {
         for (const order of orderBy) {
-            const column = joinCtx && isQualifiedField(order.field)
-                ? dialect.quoteIdentifier(order.field)
-                : order.field;
+            // A selected related dimension orders by its guarded expression, for the
+            // same alias-resolution reason it groups by it.
+            const column = joinCtx && isQualifiedField(order.field) && selection?.dimensions.includes(order.field)
+                ? resolveDimensionExpression(selection.ds, order.field, joinCtx)
+                : dialect.quoteIdentifier(order.field);
             qb = qb.orderBy(column, semanticOrderDirection(order.direction));
         }
     }
     else if (grain) {
-        qb = qb.orderBy("period", "ASC");
+        qb = qb.orderBy(dialect.quoteIdentifier("period"), "ASC");
     }
     if (limit != null) {
         qb = qb.limit(limit);

package/dist/relationship-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-check.d.ts","sourceRoot":"","sources":["../src/relationship-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAyB,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEnG,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,YAAY,EAAE,wBAAwB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAqCnC"}
+{"version":3,"file":"relationship-check.d.ts","sourceRoot":"","sources":["../src/relationship-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAyB,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAInG,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,YAAY,EAAE,wBAAwB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAkCnC"}

package/dist/relationship-check.js

@@ -16,8 +16,11 @@
  * }
  * ```
  */
+import { datasetSourceBuilder } from './utils/dataset-source.js';
 import { toQueryBuilderFactory } from './query-builder-protocol.js';
-import { getRuntimeTenantPredicate, validateTenantRuntime } from './utils/tenant-runtime.js';
+import { validateTenantRuntime } from './utils/tenant-runtime.js';
+import { applyRowScope, datasetRowScope } from './utils/row-scope.js';
+import { resolveDatasetSqlDialect } from './utils/dataset-sql-dialect.js';
 import { listToOneRelationships, readCount, relationshipKeyIssue, } from './utils/relationship-key-check.js';
 const ROWS_ALIAS = '__hq_rows';
 const KEYS_ALIAS = '__hq_keys';
@@ -29,7 +32,7 @@ const KEYS_ALIAS = '__hq_keys';
  */
 export async function checkRelationships(ds, options) {
     const factory = toQueryBuilderFactory(options.queryBuilder);
-    const tenantPredicate = getRuntimeTenantPredicate(options.context);
+    const dialect = resolveDatasetSqlDialect(factory);
     const entries = listToOneRelationships(ds, options.relationships);
     const issues = [];
     for (const entry of entries) {
@@ -37,17 +40,14 @@ export async function checkRelationships(ds, options) {
         if (tenantError) {
             throw new Error(`Cannot check relationship "${entry.relationship}": ${tenantError}`);
         }
-        let qb = factory
-            .table(entry.target.source)
+        let qb = datasetSourceBuilder(factory, entry.target)
             .count(entry.column, ROWS_ALIAS)
-            .countDistinct(entry.columns ? `tuple(${entry.columns.join(', ')})` : entry.column, KEYS_ALIAS);
+            .countDistinct(entry.columns ? dialect.packRow(entry.columns) : entry.column, KEYS_ALIAS);
         if (entry.columns) {
             for (const column of entry.columns)
                 qb = qb.where(column, 'isNotNull', undefined);
         }
-        if (entry.target.tenantKey && tenantPredicate) {
-            qb = qb.where(entry.target.tenantKey, tenantPredicate.operator, tenantPredicate.value);
-        }
+        qb = applyRowScope(qb, datasetRowScope(entry.target, options.context));
         const [row] = await qb.execute({
             abortSignal: options.context?.abortSignal,
         });

package/dist/schemas.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@hypequery/datasets/schemas`: Zod-backed query schemas and agent tools.
+ *
+ * Everything here builds or reads Zod schemas. It lives apart from the root
+ * entry so that defining and querying datasets never loads Zod. In 1.0 the
+ * root entry stops re-exporting these and Zod becomes an optional peer
+ * dependency needed only by this entry.
+ */
+export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
+export type { AISDKToolDefinition, DatasetToolAnalytics, DatasetToolMode, GenerateDatasetToolsOptions, JsonSchema, McpToolDefinition, OpenAIToolDefinition, SemanticToolDefinition, } from './tools.js';
+export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, buildDatasetInputProtocolSchema, buildMetricInputProtocolSchema, } from './semantic-query-schema.js';
+export type { CanonicalSemanticQuerySchemas, SemanticMetricQueryContract, SemanticQuerySchemaLimits, SemanticQuerySchemaOptions, SemanticQuerySchemaSource, } from './semantic-query-schema.js';
+export { ProtocolSchemaAdapterError, zodToProtocolSchema } from './protocol-schema-adapter.js';
+export type { AnyZodSchema } from './utils/zod-schema-version.js';
+export { buildClientContractQuerySchemas } from './client-contract/query-schema.js';
+export type { ClientContractQuerySchemas, ClientEndpointQuerySchema } from './client-contract/query-schema.js';
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,2BAA2B,EAC3B,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,kCAAkC,EAClC,oBAAoB,EACpB,oCAAoC,EACpC,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGlE,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,16 @@
+/**
+ * `@hypequery/datasets/schemas`: Zod-backed query schemas and agent tools.
+ *
+ * Everything here builds or reads Zod schemas. It lives apart from the root
+ * entry so that defining and querying datasets never loads Zod. In 1.0 the
+ * root entry stops re-exporting these and Zod becomes an optional peer
+ * dependency needed only by this entry.
+ */
+// Agent/tool metadata
+export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
+// Canonical semantic query schemas shared by Serve, MCP, and agent adapters.
+export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, buildDatasetInputProtocolSchema, buildMetricInputProtocolSchema, } from './semantic-query-schema.js';
+// Zod to RFC 0004 protocol schemas, for Zod 3 or Zod 4 input.
+export { ProtocolSchemaAdapterError, zodToProtocolSchema } from './protocol-schema-adapter.js';
+// Client-contract query schemas.
+export { buildClientContractQuerySchemas } from './client-contract/query-schema.js';

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

@@ -1 +1 @@
-{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AA8L5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAmBV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV"}
+{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAKT,MAAM,oBAAoB,CAAC;AAgO5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAsBV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAgBV"}

package/dist/semantic-planner.js

@@ -4,9 +4,10 @@ import { protocolMetricCapabilityErrors } from './utils/protocol-metric-capabili
 import { getMetricGrain, getMetricRef, } from './utils/metric-handle.js';
 import { validateDatasetQuery } from './dataset-query.js';
 import { isSupportedTimeGrain } from './constants.js';
-import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
+import { datasetRowScope, runtimeConstraints } from './utils/row-scope.js';
 import { isQualifiedField, resolveQualifiedField } from './utils/relationship-fields.js';
 import { segmentFilters } from './utils/segments.js';
+import { selectsAlternateTimeKey } from './utils/dataset-time-keys.js';
 function resolveField(ds, field) {
     const dimension = ds.dimensions[field];
     if (dimension?.sql) {
@@ -62,6 +63,38 @@ function normalizeFilters(ds, filters = []) {
  * query's dimensions, filters, or orderBy, scoping each joined target with the
  * runtime tenant predicate when the target declares a `tenantKey`.
  */
+/**
+ * Semantic backends receive a source name, not SQL, so they cannot apply
+ * `FINAL`. Running a final dataset there would count unmerged row versions.
+ */
+function rejectFinalOnBackend(ds) {
+    if (ds.rowResolution) {
+        throw new Error(`Dataset "${ds.name}" reads its source with FINAL, which requires the queryBuilder execution path.`);
+    }
+}
+/**
+ * The frozen plan protocol has no field for enforced constraints. Dropping
+ * them would run the call unrestricted, so it is refused instead.
+ */
+function rejectConstraintsOnBackend(context) {
+    if (runtimeConstraints(context).length > 0) {
+        throw new Error('Enforced constraints require the queryBuilder execution path.');
+    }
+}
+/**
+ * The dataset's row scope as the plan's single tenant predicate. The plan
+ * protocol carries at most one, so a wider scope is refused, never truncated.
+ */
+function planRowScope(ds, context) {
+    const scope = datasetRowScope(ds, context);
+    if (scope.length > 1) {
+        throw new Error(`Dataset "${ds.name}" has more than one row predicate, which requires the queryBuilder execution path.`);
+    }
+    if (scope.length === 0)
+        return undefined;
+    const { column, ...predicate } = scope[0];
+    return { field: column, ...predicate };
+}
 function collectJoins(ds, dimensions = [], filters = [], orderBy = [], context) {
     const referenced = [
         ...dimensions,
@@ -71,12 +104,12 @@ function collectJoins(ds, dimensions = [], filters = [], orderBy = [], context)
     if (referenced.length === 0) {
         return undefined;
     }
-    const tenantPredicate = getRuntimeTenantPredicate(context);
     const joins = new Map();
     for (const name of referenced) {
         const { relationshipName, relationship, target } = resolveQualifiedPlanField(ds, name);
         if (relationship.keys && relationship.keys.length > 1)
             throw new Error('Composite relationships require the queryBuilder execution path.');
+        rejectFinalOnBackend(target);
         if (joins.has(relationshipName)) {
             continue;
         }
@@ -86,9 +119,7 @@ function collectJoins(ds, dimensions = [], filters = [], orderBy = [], context)
             from: relationship.from,
             to: relationship.to,
             type: 'left',
-            tenant: tenantPredicate && target.tenantKey
-                ? { field: target.tenantKey, ...tenantPredicate }
-                : undefined,
+            tenant: planRowScope(target, context),
         });
     }
     return Array.from(joins.values());
@@ -98,6 +129,10 @@ function aggregationForMeasure(ds, name) {
     if (!measure) {
         throw new Error(`Unknown measure "${name}" on dataset "${ds.name}".`);
     }
+    if (measure.aggregation === 'merge') {
+        throw new Error(`Semantic backend plans do not support merge measure "${name}": it reads ClickHouse aggregate states. ` +
+            'Query it through createDatasetClient({ queryBuilder }).');
+    }
     if (measure.sql) {
         throw new Error(`Semantic backend plans do not support SQL-backed measure "${name}". ` +
             'Use a backend-specific query builder for raw SQL expressions.');
@@ -111,13 +146,6 @@ function aggregationForMeasure(ds, name) {
         filters: normalizeFilters(ds, measure.filters),
     };
 }
-function tenantForContext(ds, context) {
-    const tenantPredicate = getRuntimeTenantPredicate(context);
-    if (!tenantPredicate || !ds.tenantKey) {
-        return undefined;
-    }
-    return { field: ds.tenantKey, ...tenantPredicate };
-}
 function grainForQuery(ds, unit) {
     if (!unit) {
         return undefined;
@@ -148,15 +176,19 @@ function aggregatePlan(ds, query, aggregations, context) {
         orderBy: query.orderBy,
         limit: query.limit,
         offset: query.offset,
-        tenant: tenantForContext(ds, context),
+        tenant: planRowScope(ds, context),
         joins: collectJoins(ds, query.dimensions, query.filters, query.orderBy, context),
     };
 }
 export function buildDatasetPlan(ds, query = {}, context) {
+    rejectFinalOnBackend(ds);
+    rejectConstraintsOnBackend(context);
     if ((query.measures ?? []).some(name => name.includes('.')))
         throw new Error('Relationship measures require the queryBuilder execution path.');
     if (query.timezone !== undefined)
         throw new Error('Execution timezone requires the queryBuilder execution path.');
+    if (selectsAlternateTimeKey(ds, query.timeKey))
+        throw new Error('Alternate time keys require the queryBuilder execution path.');
     rejectTimeMeasuresOnBackend(ds, query);
     if ((query.measures ?? []).some(name => getDerivedMeasure(ds.measures, name) !== undefined)) {
         throw new Error('Derived dataset measures require the queryBuilder execution path.');
@@ -236,6 +268,10 @@ export function buildMetricPlan(metric, query = {}, context) {
     if (errors.length)
         throw new Error(`Invalid metric query: ${errors.join('; ')}`);
     const ref = getMetricRef(metric);
+    if (selectsAlternateTimeKey(ref.dataset, query.timeKey))
+        throw new Error('Alternate time keys require the queryBuilder execution path.');
+    rejectFinalOnBackend(ref.dataset);
+    rejectConstraintsOnBackend(context);
     const grain = getMetricGrain(metric, query);
     const plannedQuery = { ...query, by: grain };
     if (ref.spec.__type === 'derived_metric_spec') {

package/dist/semantic-query-schema.d.ts

@@ -2,6 +2,7 @@ import { type ZodTypeAny } from 'zod';
 import { type DatasetCatalog, type DatasetCatalogSource, type MetricCatalogEntry } from './catalog.js';
 import type { JsonSchema } from './tools.js';
 import type { ProtocolSchema } from '@hypequery/protocol';
+import type { AnyZodSchema } from './utils/zod-schema-version.js';
 export interface SemanticQuerySchemaLimits {
     defaultResultSize?: number;
     maxResultSize?: number;
@@ -20,6 +21,12 @@ export interface SemanticQuerySchemaOptions extends SemanticQuerySchemaLimits {
      * protocol does not carry post-aggregation conditions yet.
      */
     having?: boolean;
+    /**
+     * Accept a `timeKey` selection on datasets that declare alternate time axes.
+     * Off by default, like `having`: enable it only on surfaces that pass the
+     * field through to the dataset client.
+     */
+    timeKey?: boolean;
     /** Include Serve's opt-in result metadata flag. */
     includeMeta?: boolean;
     /** Require at least one dimension or measure for dataset queries. */
@@ -60,7 +67,7 @@ export interface CanonicalSemanticQuerySchemas {
 export type SemanticQuerySchemaSource = DatasetCatalogSource | DatasetCatalog;
 export declare function buildDatasetInputSchema(dataset: SemanticQuerySchemaSource, options?: SemanticQuerySchemaOptions): ZodTypeAny;
 export declare function buildMetricInputSchema(dataset: SemanticQuerySchemaSource, metricName: string, options?: SemanticQuerySchemaOptions, metricContract?: SemanticMetricQueryContract): ZodTypeAny;
-export declare function toSemanticJsonSchema(schema: ZodTypeAny, options?: {
+export declare function toSemanticJsonSchema(schema: AnyZodSchema, options?: {
     requireSelection?: boolean;
 }): JsonSchema;
 export declare function buildCanonicalSemanticQuerySchemas(datasets: Record<string, SemanticQuerySchemaSource>, options?: SemanticQuerySchemaOptions): CanonicalSemanticQuerySchemas;

package/dist/semantic-query-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-query-schema.d.ts","sourceRoot":"","sources":["../src/semantic-query-schema.ts"],"names":[],"mappings":"AAGA,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,iFAAiF;IACjF,UAAU,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,gGAAgG;AAChG,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,kBAAkB,EAClB,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAC9C,CAAC;AAEF,eAAO,MAAM,oCAAoC;;;;;;;EAO/C,CAAC;AAEH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,UAAU,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AA+M9E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,GACvC,UAAU,CASZ;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,GAC3C,UAAU,CAcZ;AAsBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,UAAU,CAMZ;AAyBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACnD,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CAgD/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,EACxC,IAAI,SAAkB,GACrB,cAAc,CAEhB;AAED,kEAAkE;AAClE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,EAC5C,IAAI,SAAiB,GACpB,cAAc,CAKhB"}
+{"version":3,"file":"semantic-query-schema.d.ts","sourceRoot":"","sources":["../src/semantic-query-schema.ts"],"names":[],"mappings":"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"}

package/dist/semantic-query-schema.js

@@ -1,12 +1,13 @@
 import { isQueryTimezone } from './utils/query-timezone.js';
-import { sha256 } from '@noble/hashes/sha2';
-import { bytesToHex } from '@noble/hashes/utils';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
 import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
 import { getDatasetCatalog, getGroupableRelationshipFields, getQueryableRelationshipFields, getQueryableRelationshipMeasures, } from './catalog.js';
 import { SEMANTIC_FILTER_OPERATORS, SEMANTIC_HAVING_OPERATORS } from './constants.js';
 import { zodToProtocolSchema } from './protocol-schema-adapter.js';
 import { compareStrings, stableStringify, uniqueSorted } from './utils/canonical-json.js';
+import { zodToDraft7JsonSchema } from './utils/zod-json-schema.js';
+import { datasetTimeKeys } from './utils/dataset-time-keys.js';
 export const DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS = Object.freeze({
     maxResultSize: 10_000,
     maxOffset: 10_000,
@@ -182,6 +183,11 @@ function queryShape(catalog, metricName, options, relationshipOperators, metric,
             ? z.number().int().nonnegative()
             : z.number().int().nonnegative().max(limits.maxOffset)).optional(),
         [grainField]: fieldEnum(grains).optional(),
+        // Only datasets with more than one axis accept the field, so every other
+        // schema and manifest hash is unchanged.
+        ...(options.timeKey && grains.length > 0 && datasetTimeKeys(catalog).length > 1 ? {
+            timeKey: fieldEnum(datasetTimeKeys(catalog)).optional().describe(`Time axis for the grain and time-based measures. Defaults to ${catalog.timeKey}.`),
+        } : {}),
         timezone: z.string().max(100).refine(isQueryTimezone, 'Use an IANA timezone such as UTC or America/New_York.').optional(),
         ...(options.includeMeta ? { includeMeta: z.boolean().optional() } : {}),
     };
@@ -190,7 +196,7 @@ export function buildDatasetInputSchema(dataset, options = {}) {
     const schema = z.object(queryShape(resolveCatalog(dataset), undefined, options, relationshipFilterPolicy(dataset))).strict();
     if (options.requireSelection === false)
         return schema;
-    return schema.refine(input => (input.dimensions?.length ?? 0) > 0 || (input.measures?.length ?? 0) > 0, { message: 'At least one dimension or measure must be specified' });
+    return requireSelection(schema);
 }
 export function buildMetricInputSchema(dataset, metricName, options = {}, metricContract) {
     const catalog = resolveCatalog(dataset);
@@ -207,16 +213,16 @@ function unionSchemas(schemas, emptyShape) {
         return schemas[0];
     return z.union(schemas);
 }
-function withSelectors(schema, selectors, requireSelection) {
-    const shape = (schema instanceof z.ZodEffects ? schema.innerType() : schema).shape;
-    const selected = z.object({ ...selectors, ...shape }).strict();
-    if (!requireSelection)
-        return selected;
-    return selected.refine(input => (input.dimensions?.length ?? 0) > 0 || (input.measures?.length ?? 0) > 0, { message: 'At least one dimension or measure must be specified' });
+function requireSelection(schema) {
+    return schema.refine((input) => (input.dimensions?.length ?? 0) > 0 || (input.measures?.length ?? 0) > 0, { message: 'At least one dimension or measure must be specified' });
+}
+function withSelectors(schema, selectors, selectionRequired) {
+    // Zod 4 keeps refinements on the object itself, so its shape is readable.
+    const selected = z.object({ ...selectors, ...schema.shape }).strict();
+    return selectionRequired ? requireSelection(selected) : selected;
 }
 export function toSemanticJsonSchema(schema, options = {}) {
-    const converted = zodToJsonSchema(schema, { target: 'jsonSchema7', $refStrategy: 'none' });
-    const { $schema: _schema, ...jsonSchema } = converted;
+    const { $schema: _schema, ...jsonSchema } = zodToDraft7JsonSchema(schema);
     const result = jsonSchema;
     const objectSchema = result.anyOf && !result.type ? { ...result, type: 'object' } : result;
     return options.requireSelection ? addSelectionRequirement(objectSchema) : objectSchema;

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -2,7 +2,8 @@ import { getDatasetCatalog, } from './catalog.js';
 import { buildCanonicalSemanticQuerySchemas, buildDatasetInputSchema, buildMetricInputSchema, toSemanticJsonSchema, } from './semantic-query-schema.js';
 import { parseCanonicalToolInput, redactSemanticToolSql, semanticToolNamePart, } from './utils/semantic-tool.js';
 function buildCatalogTool(datasets, analytics, includeSql) {
-    const schemas = buildCanonicalSemanticQuerySchemas(datasets);
+    // Parsed input reaches the client whole, so it can carry a selected time axis.
+    const schemas = buildCanonicalSemanticQuerySchemas(datasets, { timeKey: true });
     return {
         name: 'query_dataset',
         description: 'Query governed analytics datasets by selecting dimensions, measures, filters, and time grains.',
@@ -17,7 +18,7 @@ function buildCatalogTool(datasets, analytics, includeSql) {
 }
 function buildDatasetTools(datasets, analytics, includeSql) {
     return Object.entries(datasets).map(([datasetName, dataset]) => {
-        const schema = buildDatasetInputSchema(dataset);
+        const schema = buildDatasetInputSchema(dataset, { timeKey: true });
         return {
             name: `query_${semanticToolNamePart(datasetName)}`,
             description: `Query the ${datasetName} analytics dataset.`,
@@ -34,7 +35,7 @@ function buildMetricTools(datasets, analytics, includeSql) {
     const tools = [];
     for (const [datasetName, dataset] of Object.entries(datasets)) {
         for (const [metricName, metric] of Object.entries(dataset.metrics ?? {})) {
-            const schema = buildMetricInputSchema(dataset, metricName, {}, metric.contract());
+            const schema = buildMetricInputSchema(dataset, metricName, { timeKey: true }, metric.contract());
             tools.push({
                 name: `query_${semanticToolNamePart(metricName)}`,
                 description: `Query the ${metricName} metric from the ${datasetName} dataset.`,