@hypequery/datasets 0.18.0 → 0.20.0

package/dist/protocol-adapter.js

@@ -1,7 +1,11 @@
+import { splitDatasetMeasures } from './utils/dataset-measures.js';
 import { filterExpression, metricExpression, metricDerivation } from './utils/protocol-metric-expressions.js';
 import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateProtocolDatasetContract, } from '@hypequery/protocol';
 import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
 import { toProtocolSemanticMetadata } from './utils/protocol-semantic-metadata.js';
+import { assertPublishableTimeGrains, isPortableTimeGrain, requirePortableTimeGrain } from './utils/portable-grains.js';
+import { requirePortableAggregation } from './utils/portable-aggregations.js';
+import { assertNoPublishedSegments } from './utils/segments.js';
 function byName(left, right) {
     return left.name.localeCompare(right.name);
 }
@@ -18,13 +22,13 @@ function fieldSchema(type) {
             return { kind: 'any' };
     }
 }
-function unwrapMetric(metric) {
+function unwrapMetric(metric, exposedName) {
     return metric.__type === 'grained_metric_ref'
-        ? { ref: metric.metric, grain: metric.grain }
+        ? { ref: metric.metric, grain: requirePortableTimeGrain(metric.grain, `Metric "${exposedName}"`) }
         : { ref: metric };
 }
 function metricContract(exposedName, metric, endpoint) {
-    const { ref, grain } = unwrapMetric(metric);
+    const { ref, grain } = unwrapMetric(metric, exposedName);
     const contract = metric.contract();
     const result = {
         name: parseProtocolIdentifier(exposedName),
@@ -39,7 +43,8 @@ function metricContract(exposedName, metric, endpoint) {
             : {}),
         dimensions: [...contract.dimensions].sort().map(parseProtocolQualifiedIdentifier),
         filters: [...contract.filters].sort().map(parseProtocolIdentifier),
-        grains: [...contract.grains].sort(),
+        // Only grains the published contract can carry are advertised there.
+        grains: contract.grains.filter(isPortableTimeGrain).sort(),
         ...(grain !== undefined ? { grain } : {}),
         ...(ref.label !== undefined ? { label: ref.label } : {}),
         ...(ref.description !== undefined ? { description: ref.description } : {}),
@@ -68,8 +73,18 @@ function requiredSqlDependencies(kind, name, dependencies) {
  * Deployment assembly selects the fields supported by the deployment contract.
  */
 export function buildProtocolDatasetContract(dataset, options = {}) {
+    const { base: baseMeasures, windows, shifts } = splitDatasetMeasures(dataset.measures);
+    const shiftMeasureNames = Object.keys(shifts);
+    if (shiftMeasureNames.length)
+        throw new Error(`Dataset "${dataset.name}" shift measures (${shiftMeasureNames.join(', ')}) need deployment contract 3 (RFC 0015).`);
+    const windowMeasureNames = Object.keys(windows);
+    if (windowMeasureNames.length > 0) {
+        throw new Error(`Dataset "${dataset.name}" window measures (${windowMeasureNames.join(', ')}) need deployment contract 3 (RFC 0015).`);
+    }
+    assertNoPublishedSegments(dataset);
+    assertPublishableTimeGrains(dataset);
     const metrics = Object.entries(options.metrics ?? {})
-        .filter(([, metric]) => unwrapMetric(metric).ref.datasetName === dataset.name)
+        .filter(([, metric]) => (metric.__type === 'grained_metric_ref' ? metric.metric : metric).datasetName === dataset.name)
         .map(([name, metric]) => {
         const endpoint = options.metricEndpoints?.[name];
         if (!endpoint) {
@@ -92,7 +107,9 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
                         ? { dimensions: [...dataset.defaults.dimensions].map(parseProtocolIdentifier) }
                         : {}),
                     ...(dataset.defaults.timeGrain !== undefined
-                        ? { timeGrain: dataset.defaults.timeGrain }
+                        ? {
+                            timeGrain: requirePortableTimeGrain(dataset.defaults.timeGrain, `Dataset "${dataset.name}" defaults.timeGrain`),
+                        }
                         : {}),
                 },
             }
@@ -113,9 +130,9 @@ export function buildProtocolDatasetContract(dataset, options = {}) {
             ...(dimension.description !== undefined ? { description: dimension.description } : {}),
             ...toProtocolSemanticMetadata(dimension),
         })).sort(byName),
-        measures: Object.entries(dataset.measures).map(([name, measure]) => ({
+        measures: Object.entries(baseMeasures).map(([name, measure]) => ({
             name,
-            aggregation: measure.aggregation,
+            aggregation: requirePortableAggregation(measure.aggregation, `Measure "${dataset.name}.${name}"`),
             field: measure.field,
             ...(measure.argField !== undefined ? { argField: measure.argField } : {}),
             ...(measure.level !== undefined ? { level: measure.level } : {}),

package/dist/protocol-deployment-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-deployment-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-deployment-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,0BAA0B,EAE/B,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CACvE;AAED,oEAAoE;AACpE,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,OAAO,GAAE,sCAA2C,GACnD,0BAA0B,CAyB5B"}
+{"version":3,"file":"protocol-deployment-adapter.d.ts","sourceRoot":"","sources":["../src/protocol-deployment-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,0BAA0B,EAE/B,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CACvE;AAED,oEAAoE;AACpE,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,OAAO,GAAE,sCAA2C,GACnD,0BAA0B,CAyB5B"}

package/dist/protocol-deployment-adapter.js

@@ -1,3 +1,4 @@
+import { splitDatasetMeasures } from './utils/dataset-measures.js';
 import { parseProtocolIdentifier, validateProtocolDeploymentContract, } from '@hypequery/protocol';
 import { buildProtocolDatasetContract } from './protocol-adapter.js';
 import { derivedMeasureExpression } from './utils/protocol-metric-expressions.js';
@@ -9,7 +10,7 @@ export function buildProtocolDeploymentContract(datasets, options = {}) {
             endpoint: options.endpoints?.[dataset.name],
         });
         const { metrics: _metrics, ...base } = contract;
-        const derived = Object.entries(dataset.derivedMeasures ?? {}).map(([name, definition]) => ({
+        const derived = Object.entries(splitDatasetMeasures(dataset.measures).derived).map(([name, definition]) => ({
             kind: 'derived',
             name: parseProtocolIdentifier(name),
             uses: Object.entries(definition.uses).map(([alias, measure]) => ({

package/dist/protocol-rehydrate.d.ts

@@ -13,6 +13,8 @@
  */
 import type { ProtocolDatasetContract, ProtocolDeploymentDataset } from '@hypequery/protocol';
 import type { AnyDatasetInstance, DatasetCachePolicy, MetricHandle } from './types.js';
+import { type UnsupportedContractReason } from './utils/unsupported-contract-reasons.js';
+export { UNSUPPORTED_CONTRACT_REASONS, type UnsupportedContractReason, } from './utils/unsupported-contract-reasons.js';
 /** A rebuilt dataset in the registry shape Serve, MCP, and the planner accept. */
 export type RehydratedDataset = AnyDatasetInstance & {
     readonly metrics: Readonly<Record<string, MetricHandle>>;
@@ -43,7 +45,9 @@ export interface RehydrateProtocolDatasetsOptions {
 export declare class UnsupportedContractFeatureError extends Error {
     readonly dataset: string;
     readonly feature: string;
-    constructor(datasetName: string, feature: string, detail: string);
+    /** Which excluded surface this is; see `UNSUPPORTED_CONTRACT_REASONS`. */
+    readonly reason: UnsupportedContractReason | undefined;
+    constructor(datasetName: string, feature: string, detail: string, reason?: UnsupportedContractReason);
 }
 /**
  * Rebuild every dataset in a validated deployment contract.

package/dist/protocol-rehydrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAEvB,yBAAyB,EAM1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAMlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAMpB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMjE;AAyPD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,CAAC,uBAAuB,GAAG,yBAAyB,CAAC,EAAE,EAC3E,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAmF7C;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAG7C"}
+{"version":3,"file":"protocol-rehydrate.d.ts","sourceRoot":"","sources":["../src/protocol-rehydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAEvB,yBAAyB,EAM1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAMlB,YAAY,EAIb,MAAM,YAAY,CAAC;AAMpB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,4BAA4B,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,yCAAyC,CAAC;AAEjD,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC;gBAGrD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,yBAAyB;CAQrC;AAoQD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,CAAC,uBAAuB,GAAG,yBAAyB,CAAC,EAAE,EAC3E,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAwF7C;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gCAAqC,GAC7C,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAG7C"}

package/dist/protocol-rehydrate.js

@@ -17,6 +17,9 @@ import { snapshotSemanticMetadata } from './utils/semantic-metadata.js';
 import { withContractCapabilities } from './utils/protocol-metric-capabilities.js';
 import { rehydrateDerivedFormula } from './utils/protocol-rehydrate-derivation.js';
 import { rehydrateMeasureFilter } from './utils/protocol-rehydrate-filters.js';
+import { PORTABLE_TIME_GRAINS } from './utils/portable-grains.js';
+import { UNSUPPORTED_CONTRACT_REASONS, } from './utils/unsupported-contract-reasons.js';
+export { UNSUPPORTED_CONTRACT_REASONS, } from './utils/unsupported-contract-reasons.js';
 /**
  * Thrown when a contract describes something portable execution cannot rebuild.
  *
@@ -26,11 +29,14 @@ import { rehydrateMeasureFilter } from './utils/protocol-rehydrate-filters.js';
 export class UnsupportedContractFeatureError extends Error {
     dataset;
     feature;
-    constructor(datasetName, feature, detail) {
+    /** Which excluded surface this is; see `UNSUPPORTED_CONTRACT_REASONS`. */
+    reason;
+    constructor(datasetName, feature, detail, reason) {
         super(`Cannot rebuild ${feature} on dataset "${datasetName}": ${detail}`);
         this.name = 'UnsupportedContractFeatureError';
         this.dataset = datasetName;
         this.feature = feature;
+        this.reason = reason;
     }
 }
 function rehydrateDimensions(contract) {
@@ -57,7 +63,7 @@ function rehydrateDimensions(contract) {
     return dimensions;
 }
 function rehydrateMeasure(datasetName, measure) {
-    const filters = measure.filters.map((expression, index) => rehydrateMeasureFilter(expression, () => new UnsupportedContractFeatureError(datasetName, `measure "${String(measure.name)}"`, `fixed filter ${index} is not a field/operator/value comparison`)));
+    const filters = measure.filters.map((expression, index) => rehydrateMeasureFilter(expression, () => new UnsupportedContractFeatureError(datasetName, `measure "${String(measure.name)}"`, `fixed filter ${index} is not a field/operator/value comparison`, UNSUPPORTED_CONTRACT_REASONS.measureFilterNotComparison)));
     return {
         __type: 'measure_definition',
         ...snapshotSemanticMetadata(measure),
@@ -78,7 +84,7 @@ function rehydrateDerivedMeasure(datasetName, measure) {
         __type: 'derived_measure_definition',
         ...snapshotSemanticMetadata(measure),
         uses: Object.fromEntries(measure.uses.map(input => [String(input.alias), String(input.measure)])),
-        formula: rehydrateDerivedFormula({ inputs: [], expression: measure.expression }, reason => new UnsupportedContractFeatureError(datasetName, `measure "${measure.name}"`, reason)),
+        formula: rehydrateDerivedFormula({ inputs: [], expression: measure.expression }, reason => new UnsupportedContractFeatureError(datasetName, `measure "${measure.name}"`, reason, UNSUPPORTED_CONTRACT_REASONS.unsupportedFormula)),
         ...(measure.label !== undefined ? { label: measure.label } : {}),
         ...(measure.description !== undefined ? { description: measure.description } : {}),
     };
@@ -139,12 +145,12 @@ function aggregationKey(value) {
  */
 function measureForAggregate(instance, contract, subject, expression) {
     if (expression.kind !== 'aggregate') {
-        throw new UnsupportedContractFeatureError(instance.name, subject, `expected an aggregate expression, received "${expression.kind}"`);
+        throw new UnsupportedContractFeatureError(instance.name, subject, `expected an aggregate expression, received "${expression.kind}"`, UNSUPPORTED_CONTRACT_REASONS.expressionNotAggregate);
     }
     const field = String(expression.field);
     const candidates = contract.measures.filter(measure => (aggregationKey(measure) === aggregationKey(expression)));
     if (candidates.length === 0) {
-        throw new UnsupportedContractFeatureError(instance.name, subject, `no declared measure matches ${expression.aggregation}(${field})`);
+        throw new UnsupportedContractFeatureError(instance.name, subject, `no declared measure matches ${expression.aggregation}(${field})`, UNSUPPORTED_CONTRACT_REASONS.noMatchingMeasure);
     }
     // A metric expression carries no raw SQL, so two measures that share an
     // aggregation identity but override SQL differently are indistinguishable in
@@ -153,7 +159,7 @@ function measureForAggregate(instance, contract, subject, expression) {
     if (distinctSql.size > 1) {
         throw new UnsupportedContractFeatureError(instance.name, subject, `${candidates.map(measure => `"${String(measure.name)}"`).join(' and ')} share `
             + `${expression.aggregation}(${field}) but emit different SQL, so the contract cannot `
-            + 'say which one this metric was built from');
+            + 'say which one this metric was built from', UNSUPPORTED_CONTRACT_REASONS.ambiguousMeasureSql);
     }
     return String(candidates[0].name);
 }
@@ -164,7 +170,7 @@ function measureForAggregate(instance, contract, subject, expression) {
  * what both plan builders emit as the column of the intermediate aggregate.
  */
 function derivedMetricConfig(instance, contract, subject, derivation) {
-    const unsupported = (reason) => new UnsupportedContractFeatureError(instance.name, subject, reason);
+    const unsupported = (reason) => new UnsupportedContractFeatureError(instance.name, subject, reason, UNSUPPORTED_CONTRACT_REASONS.unsupportedFormula);
     const uses = Object.fromEntries(derivation.inputs.map(input => {
         const alias = String(input.alias);
         return [
@@ -184,7 +190,7 @@ function rehydrateMetric(instance, contract, metric) {
         // The inlined expression states what a derived metric means but drops the
         // aliases its SQL is written in terms of. Without them a rebuild computes
         // the same number through different SQL, which decision 0005 excludes.
-        throw new UnsupportedContractFeatureError(instance.name, subject, 'a derived metric requires its authored formula, which this contract does not carry');
+        throw new UnsupportedContractFeatureError(instance.name, subject, 'a derived metric requires its authored formula, which this contract does not carry', UNSUPPORTED_CONTRACT_REASONS.derivedMetricWithoutFormula);
     }
     const metadata = {
         ...snapshotSemanticMetadata(metric),
@@ -234,7 +240,7 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
         if (!instance) {
             // The deployment validator already rejects a dangling relationship, so
             // reaching this means the caller passed a partial contract.
-            throw new UnsupportedContractFeatureError(target, 'relationship target', `dataset "${target}" is not part of the supplied contract`);
+            throw new UnsupportedContractFeatureError(target, 'relationship target', `dataset "${target}" is not part of the supplied contract`, UNSUPPORTED_CONTRACT_REASONS.relationshipTargetMissing);
         }
         return instance;
     };
@@ -251,7 +257,11 @@ export function rehydrateProtocolDatasets(contracts, options = {}) {
                     ...(contract.defaults.dimensions !== undefined ? { dimensions: [...contract.defaults.dimensions] } : {}),
                 } } : {}),
             ...(contract.tenant.kind === 'required' ? { tenantKey: contract.tenant.field } : {}),
-            ...(contract.timeField !== undefined ? { timeKey: String(contract.timeField) } : {}),
+            // A published dataset supports only the grains its contract can carry,
+            // so its catalog never advertises a grain the portable path would refuse.
+            ...(contract.timeField !== undefined
+                ? { timeKey: String(contract.timeField), timeGrains: PORTABLE_TIME_GRAINS }
+                : {}),
             dimensions: rehydrateDimensions(contract),
             measures: Object.fromEntries([
                 ...contract.measures.map(measure => [

package/dist/query-builder-protocol.d.ts

@@ -27,12 +27,16 @@ export interface QueryBuilderLike {
     stddev?(column: string, alias?: string): QueryBuilderLike;
     /** Sample variance of `column`. */
     variance?(column: string, alias?: string): QueryBuilderLike;
+    /** Estimated number of distinct non-NULL values of `column`. */
+    approxCountDistinct?(column: string, alias?: string): QueryBuilderLike;
     where(column: string, operator: string, value: unknown): QueryBuilderLike;
     leftJoin(table: string, leftColumn: string, rightColumn: string, alias?: string, on?: QueryBuilderJoinCondition | QueryBuilderJoinCondition[]): QueryBuilderLike;
     /**
-     * Optional single-match LEFT JOIN (ClickHouse `LEFT ANY JOIN`). When a
-     * builder provides it, relationship joins use it so duplicate target join
-     * keys cannot fan out aggregates; otherwise `leftJoin` is used.
+     * Single-match LEFT JOIN (ClickHouse `LEFT ANY JOIN`). Required to query
+     * relationship-qualified fields: duplicate target join keys cannot fan out
+     * aggregates. A builder without it can still run every query that does not
+     * traverse a relationship; one that does is rejected with a clear error
+     * instead of falling back to `leftJoin`.
      */
     leftAnyJoin?(table: string, leftColumn: string, rightColumn: string, alias?: string, on?: QueryBuilderJoinCondition | QueryBuilderJoinCondition[]): QueryBuilderLike;
     groupBy(columns: string | string[]): QueryBuilderLike;

package/dist/query-builder-protocol.d.ts.map

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

package/dist/query-planner.d.ts

@@ -4,7 +4,7 @@ import { type RelationshipBuilderContext } from './utils/relationship-builder-pl
 type DatasetShape = AnyDatasetInstance;
 export declare function resolveDimensionExpression(ds: DatasetShape, dimensionName: string, joinCtx?: RelationshipBuilderContext): string;
 export declare function resolveFilterField(ds: DatasetShape, filterField: string, joinCtx?: RelationshipBuilderContext): string;
-export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined, joinCtx?: RelationshipBuilderContext): {
+export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined, joinCtx?: RelationshipBuilderContext, timezone?: string): {
     selectParts: string[];
     groupByParts: string[];
 };

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

@@ -1 +1 @@
-{"version":3,"file":"query-planner.d.ts","sourceRoot":"","sources":["../src/query-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAMpE,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAI9C,KAAK,YAAY,GAAG,kBAAkB,CAAC;AA6BvC,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAMR;AAED,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,OAAO,CAAC,EAAE,0BAA0B,GACnC;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAkCnD;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAgElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,EAC7B,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAoBlB;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB"}
+{"version":3,"file":"query-planner.d.ts","sourceRoot":"","sources":["../src/query-planner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAMpE,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAI9C,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAMvC,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAMR;AAED,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,OAAO,CAAC,EAAE,0BAA0B,EACpC,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAmCnD;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAqElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,EAC7B,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAoBlB;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB"}

package/dist/query-planner.js

@@ -1,3 +1,5 @@
+import { queryTimeSql } from './utils/query-timezone.js';
+import { assertNoRawSqlUnderJoins } from './utils/sql-under-joins.js';
 import { GRAIN_FUNCTIONS } from "./constants.js";
 import { applyFilteredAggregationExpression } from './utils/filtered-aggregation-sql.js';
 import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
@@ -9,21 +11,6 @@ import { validatePercentileLevel } from './measure.js';
 function toOrderDirection(direction) {
     return direction === 'asc' ? 'ASC' : 'DESC';
 }
-/**
- * Raw SQL expressions on the base dataset are emitted verbatim, so their column
- * references are not table-qualified. When relationship joins are active a bare
- * `price` in such an expression is ambiguous if the joined table also has a
- * `price` column. Until the builder rewrites identifiers inside expressions,
- * reject the combination rather than emit ambiguous SQL.
- */
-function assertNoRawSqlUnderJoins(kind, name, sql, joinCtx) {
-    if (!joinCtx) {
-        return;
-    }
-    throw new Error(`SQL-backed ${kind} "${name}" cannot be combined with relationship joins: its expression ` +
-        `("${sql}") is not table-qualified and may collide with joined columns. Query it without ` +
-        `relationship-qualified fields, or redeclare it as a plain column.`);
-}
 export function resolveDimensionExpression(ds, dimensionName, joinCtx) {
     if (joinCtx && isQualifiedField(dimensionName)) {
         return resolveQualifiedColumn(ds, dimensionName);
@@ -42,7 +29,7 @@ export function resolveFilterField(ds, filterField, joinCtx) {
     const resolvedField = ds.filters[filterField]?.field ?? filterField;
     return resolveDimensionExpression(ds, resolvedField, joinCtx);
 }
-export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx) {
+export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx, timezone) {
     const selectParts = [];
     const groupByParts = new Set();
     if (grain) {
@@ -50,7 +37,8 @@ export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx) {
         if (!fn) {
             throw new Error(`Unsupported time grain "${grain}".`);
         }
-        selectParts.push(`${fn}(${qualifyBaseColumn(joinCtx, String(ds.timeKey))}) AS period`);
+        const time = resolveDimensionExpression(ds, String(ds.timeKey), joinCtx);
+        selectParts.push(`${fn}(${queryTimeSql(time, timezone)}) AS period`);
         groupByParts.add("period");
     }
     for (const dimensionName of dimensions) {
@@ -120,6 +108,11 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx) {
             }
             return qb.quantile(fieldOrExpr, spec.level, alias);
         }
+        case "approxCountDistinct":
+            if (!qb.approxCountDistinct) {
+                throw new Error('Query builder does not support approxCountDistinct aggregations.');
+            }
+            return qb.approxCountDistinct(fieldOrExpr, alias);
         case "stddev":
             if (!qb.stddev) {
                 throw new Error('Query builder does not support stddev aggregations.');

package/dist/relationship-check.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Verifies declared to-one relationships against the data.
+ *
+ * `belongsTo` and `hasOne` are declarations: nothing at query time proves the
+ * target join column is unique. Relationship joins are single-match, so a
+ * duplicate key cannot inflate an aggregate, but the join then takes an
+ * arbitrary one of the matching rows and grouped values drift without any
+ * error. `checkRelationships` counts rows and distinct keys on each target so a
+ * mis-declaration is caught in CI or at deploy time rather than in a report.
+ *
+ * @example
+ * ```ts
+ * const result = await checkRelationships(Orders, { queryBuilder: db });
+ * if (!result.ok) {
+ *   throw new Error(result.issues.map((issue) => issue.message).join('\n'));
+ * }
+ * ```
+ */
+import type { AnyDatasetInstance, ExecutionContext } from './types.js';
+import { type QueryBuilderFactoryInput } from './query-builder-protocol.js';
+import { type RelationshipKeyIssue } from './utils/relationship-key-check.js';
+export type { RelationshipKeyIssue } from './utils/relationship-key-check.js';
+export interface CheckRelationshipsOptions {
+    /** Query builder factory used to count target keys. */
+    queryBuilder: QueryBuilderFactoryInput;
+    /**
+     * Runtime context. A tenant-scoped target is checked within the runtime
+     * tenant, the same scope its join uses, so it requires tenant runtime.
+     */
+    context?: ExecutionContext;
+    /** Restrict the check to these to-one relationship names. */
+    relationships?: readonly string[];
+}
+export interface CheckRelationshipsResult {
+    /** True when every checked relationship has a unique target key. */
+    ok: boolean;
+    /** Relationship names that were checked. */
+    checked: string[];
+    issues: RelationshipKeyIssue[];
+}
+/**
+ * Checks that the target join column of each `belongsTo` and `hasOne`
+ * relationship on `ds` is unique. NULL keys are ignored because they never
+ * match a join. `hasMany` relationships are skipped.
+ */
+export declare function checkRelationships(ds: AnyDatasetInstance, options: CheckRelationshipsOptions): Promise<CheckRelationshipsResult>;
+//# sourceMappingURL=relationship-check.d.ts.map

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

@@ -0,0 +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;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAkCnC"}

package/dist/relationship-check.js

@@ -0,0 +1,59 @@
+/**
+ * Verifies declared to-one relationships against the data.
+ *
+ * `belongsTo` and `hasOne` are declarations: nothing at query time proves the
+ * target join column is unique. Relationship joins are single-match, so a
+ * duplicate key cannot inflate an aggregate, but the join then takes an
+ * arbitrary one of the matching rows and grouped values drift without any
+ * error. `checkRelationships` counts rows and distinct keys on each target so a
+ * mis-declaration is caught in CI or at deploy time rather than in a report.
+ *
+ * @example
+ * ```ts
+ * const result = await checkRelationships(Orders, { queryBuilder: db });
+ * if (!result.ok) {
+ *   throw new Error(result.issues.map((issue) => issue.message).join('\n'));
+ * }
+ * ```
+ */
+import { toQueryBuilderFactory } from './query-builder-protocol.js';
+import { getRuntimeTenantPredicate, validateTenantRuntime } from './utils/tenant-runtime.js';
+import { listToOneRelationships, readCount, relationshipKeyIssue, } from './utils/relationship-key-check.js';
+const ROWS_ALIAS = '__hq_rows';
+const KEYS_ALIAS = '__hq_keys';
+/**
+ * Checks that the target join column of each `belongsTo` and `hasOne`
+ * relationship on `ds` is unique. NULL keys are ignored because they never
+ * match a join. `hasMany` relationships are skipped.
+ */
+export async function checkRelationships(ds, options) {
+    const factory = toQueryBuilderFactory(options.queryBuilder);
+    const tenantPredicate = getRuntimeTenantPredicate(options.context);
+    const entries = listToOneRelationships(ds, options.relationships);
+    const issues = [];
+    for (const entry of entries) {
+        const tenantError = validateTenantRuntime(entry.target, options.context);
+        if (tenantError) {
+            throw new Error(`Cannot check relationship "${entry.relationship}": ${tenantError}`);
+        }
+        let qb = factory
+            .table(entry.target.source)
+            .count(entry.column, ROWS_ALIAS)
+            .countDistinct(entry.column, KEYS_ALIAS);
+        if (entry.target.tenantKey && tenantPredicate) {
+            qb = qb.where(entry.target.tenantKey, tenantPredicate.operator, tenantPredicate.value);
+        }
+        const [row] = await qb.execute({
+            abortSignal: options.context?.abortSignal,
+        });
+        const issue = relationshipKeyIssue(entry, readCount(row?.[ROWS_ALIAS]), readCount(row?.[KEYS_ALIAS]));
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        checked: entries.map((entry) => entry.relationship),
+        issues,
+    };
+}

package/dist/relationships.d.ts

@@ -10,15 +10,14 @@
  * is not addressable through a relationship, so there are no cross-dataset
  * metrics.
  *
- * Note that the `kind` passed here is a declaration, not something checked
- * against the data — there is no uniqueness concept in the model, so nothing
- * verifies that a `belongsTo` target column really is unique. What a
- * mis-declaration costs depends on the builder. One that implements the
- * optional `leftAnyJoin` (ClickHouse `LEFT ANY JOIN`) takes at most one target
- * row per base row, so the aggregate cannot inflate — it just silently picks an
- * arbitrary one of the matches. A builder without it falls back to `leftJoin`,
- * where duplicate target keys fan out and do inflate the aggregate. Either way
- * the declaration has to be right.
+ * Note that the `kind` passed here is a declaration, not something checked at
+ * query time. Joins are single-match (`leftAnyJoin`, ClickHouse
+ * `LEFT ANY JOIN`), so a mis-declared to-one relationship cannot inflate an
+ * aggregate, but it does make the join pick an arbitrary one of the matching
+ * target rows. Builders without `leftAnyJoin` are refused rather than
+ * downgraded to a fan-out `leftJoin`. The in-memory backend refuses duplicate
+ * target keys outright, and `checkRelationships()` reports them against a live
+ * database, so a wrong declaration can be caught before it skews results.
  *
  * @example
  * ```ts
@@ -29,7 +28,8 @@
  *     customerId: dimension.string({ column: "customer_id" }),
  *   },
  *   relationships: {
- *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
+ *     // Join keys are source columns, not dimension names.
+ *     customer: belongsTo(() => Customers, { from: "customer_id", to: "id" }),
  *   },
  * });
  *

package/dist/relationships.js

@@ -10,15 +10,14 @@
  * is not addressable through a relationship, so there are no cross-dataset
  * metrics.
  *
- * Note that the `kind` passed here is a declaration, not something checked
- * against the data — there is no uniqueness concept in the model, so nothing
- * verifies that a `belongsTo` target column really is unique. What a
- * mis-declaration costs depends on the builder. One that implements the
- * optional `leftAnyJoin` (ClickHouse `LEFT ANY JOIN`) takes at most one target
- * row per base row, so the aggregate cannot inflate — it just silently picks an
- * arbitrary one of the matches. A builder without it falls back to `leftJoin`,
- * where duplicate target keys fan out and do inflate the aggregate. Either way
- * the declaration has to be right.
+ * Note that the `kind` passed here is a declaration, not something checked at
+ * query time. Joins are single-match (`leftAnyJoin`, ClickHouse
+ * `LEFT ANY JOIN`), so a mis-declared to-one relationship cannot inflate an
+ * aggregate, but it does make the join pick an arbitrary one of the matching
+ * target rows. Builders without `leftAnyJoin` are refused rather than
+ * downgraded to a fan-out `leftJoin`. The in-memory backend refuses duplicate
+ * target keys outright, and `checkRelationships()` reports them against a live
+ * database, so a wrong declaration can be caught before it skews results.
  *
  * @example
  * ```ts
@@ -29,7 +28,8 @@
  *     customerId: dimension.string({ column: "customer_id" }),
  *   },
  *   relationships: {
- *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
+ *     // Join keys are source columns, not dimension names.
+ *     customer: belongsTo(() => Customers, { from: "customer_id", to: "id" }),
  *   },
  * });
  *

package/dist/semantic-plan.d.ts

@@ -72,7 +72,6 @@ export interface SemanticGrainPlan {
     field: string;
     unit: TimeGrain;
     output: 'period';
-    timezone?: string;
     weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
 }
 /** @deprecated Part of the frozen plan/backend protocol; use `createDatasetClient({ queryBuilder })` instead. */

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AACA,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;AAyL5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAgBV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAYV"}
+{"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;AA6L5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAkBV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV"}