@hypequery/datasets 0.22.0 → 0.23.1

package/dist/utils/dataset-having.js

@@ -0,0 +1,106 @@
+import { SEMANTIC_HAVING_OPERATORS } from '../constants.js';
+import { selectedTimeMeasures } from './time-query-measures.js';
+const HAVING_OPERATORS = new Set(SEMANTIC_HAVING_OPERATORS);
+const COMPARISONS = {
+    eq: '=',
+    neq: '!=',
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function conditionValueError(condition) {
+    const { measure, operator, value } = condition;
+    if (operator === 'between') {
+        return Array.isArray(value) && value.length === 2 && value.every(isFiniteNumber)
+            ? undefined
+            : `Having "between" on "${measure}" expects a two-item array of finite numbers.`;
+    }
+    if (operator === 'in' || operator === 'notIn') {
+        return Array.isArray(value) && value.length > 0 && value.every(isFiniteNumber)
+            ? undefined
+            : `Having "${operator}" on "${measure}" expects a non-empty array of finite numbers.`;
+    }
+    return isFiniteNumber(value)
+        ? undefined
+        : `Having "${operator}" on "${measure}" expects a finite number.`;
+}
+/**
+ * Validates `having` conditions against the query they belong to.
+ *
+ * A condition may only reference a measure the query selects: that is the
+ * value the condition reads, and it keeps every rendered reference an output
+ * alias rather than an expression taken from input.
+ */
+export function datasetHavingErrors(ds, query, selectedMeasures) {
+    if (query.having === undefined)
+        return [];
+    if (!Array.isArray(query.having))
+        return ['Having must be an array of conditions.'];
+    if (query.having.length === 0)
+        return [];
+    const errors = [];
+    if (selectedTimeMeasures(ds, query).size > 0) {
+        errors.push('Having is not supported on queries that select window or shift measures.');
+    }
+    // `maxFilters` bounds every predicate the query adds, before and after
+    // aggregation alike. Filters alone over the limit are reported separately.
+    const maxFilters = ds.limits?.maxFilters;
+    const filterCount = Array.isArray(query.filters) ? query.filters.length : 0;
+    const conditionCount = filterCount + query.having.length;
+    if (maxFilters && conditionCount > maxFilters && filterCount <= maxFilters) {
+        errors.push(`Too many filters and having conditions: ${conditionCount} (max ${maxFilters})`);
+    }
+    const selected = new Set(selectedMeasures);
+    for (const condition of query.having) {
+        if (typeof condition !== 'object' || condition === null) {
+            errors.push('Each having condition must be an object with measure, operator and value.');
+            continue;
+        }
+        const { measure, operator } = condition;
+        if (typeof measure !== 'string' || !selected.has(measure)) {
+            errors.push(`Having measure "${String(measure)}" must be one of the selected measures: ${[...selected].join(', ')}`);
+            continue;
+        }
+        if (typeof operator !== 'string' || !HAVING_OPERATORS.has(operator)) {
+            errors.push(`Unsupported having operator "${String(operator)}" on "${measure}". ` +
+                `Supported: ${SEMANTIC_HAVING_OPERATORS.join(', ')}`);
+            continue;
+        }
+        const valueError = conditionValueError(condition);
+        if (valueError)
+            errors.push(valueError);
+    }
+    return errors;
+}
+/**
+ * Renders validated `having` conditions as one parameterized predicate.
+ *
+ * `measureSql` maps a selected measure to the expression that reads its
+ * aggregated value in the outer query. Values are only ever bound as `?`
+ * parameters, appended in placeholder order.
+ */
+export function datasetHavingSql(conditions, measureSql) {
+    const parameters = [];
+    const predicates = conditions.map((condition) => {
+        const column = measureSql(condition.measure);
+        if (condition.operator === 'between') {
+            parameters.push(condition.value[0], condition.value[1]);
+            return `${column} BETWEEN ? AND ?`;
+        }
+        if (condition.operator === 'in' || condition.operator === 'notIn') {
+            parameters.push(...condition.value);
+            const placeholders = condition.value.map(() => '?').join(', ');
+            return `${column} ${condition.operator === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`;
+        }
+        const comparison = COMPARISONS[condition.operator];
+        if (!comparison)
+            throw new Error(`Unsupported having operator "${String(condition.operator)}".`);
+        parameters.push(condition.value);
+        return `${column} ${comparison} ?`;
+    });
+    return { sql: predicates.join(' AND '), parameters };
+}

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

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

package/dist/utils/dataset-normalization.js

@@ -1,3 +1,4 @@
+import { relationshipKeys } from './relationship-keys.js';
 export function normalizeDimensions(config) {
     return config.dimensions;
 }
@@ -19,7 +20,10 @@ export function normalizeMeasures(measures) {
     return (measures ?? {});
 }
 export function normalizeRelationships(relationships, source) {
-    for (const name of Object.keys(relationships ?? {})) {
+    for (const [name, relationship] of Object.entries(relationships ?? {})) {
+        // Hand-built definitions skip the helpers, so check composite keys here.
+        if (relationship.keys)
+            relationshipKeys(relationship);
         if (name === source) {
             throw new Error(`Invalid relationship "${name}": the name matches the dataset source table, so the join ` +
                 'alias would shadow the base table and produce ambiguous SQL. Rename the relationship.');

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

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

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

@@ -9,6 +9,7 @@ import { isQualifiedField, resolveQualifiedField, } from './relationship-fields.
 import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './relationship-validation.js';
 import { segmentSelectionErrors } from './segments.js';
 import { analyzeTimeMeasureAxis } from './time-measure-axis.js';
+import { datasetHavingErrors } from './dataset-having.js';
 export function validateDatasetQueryInput(ds, query, context) {
     const errors = [...semanticQuerySyntaxErrors(query), ...queryTimezoneErrors(query.timezone)];
     const dimensionNames = Object.keys(ds.dimensions);
@@ -147,6 +148,7 @@ export function validateDatasetQueryInput(ds, query, context) {
     if (ds.limits?.maxMeasures && query.measures && query.measures.length > ds.limits.maxMeasures) {
         errors.push(`Too many measures: ${query.measures.length} (max ${ds.limits.maxMeasures})`);
     }
+    errors.push(...datasetHavingErrors(ds, query, selectedMeasures));
     if (ds.limits?.maxFilters && query.filters && query.filters.length > ds.limits.maxFilters) {
         errors.push(`Too many filters: ${query.filters.length} (max ${ds.limits.maxFilters})`);
     }

package/dist/utils/protocol-metric-expressions.d.ts

@@ -1,7 +1,15 @@
 import { type ProtocolExpression, type ProtocolMetricDerivation } from '@hypequery/protocol';
 import type { AggregationSpec, DerivedMeasureDefinition, DerivedMetricSpec, MetricFilter } from '../types.js';
 export declare function filterExpression(filter: MetricFilter): ProtocolExpression;
+/** The published form; aliases must satisfy the protocol identifier grammar. */
 export declare function derivedMeasureExpression(definition: DerivedMeasureDefinition): ProtocolExpression;
+/**
+ * The catalog form. Catalogs describe local datasets that may never be published,
+ * so aliases keep their locally valid names (for example `__hypequery_value`, or
+ * names past the protocol's length limit) instead of failing catalog creation.
+ * Publishing still validates them through `derivedMeasureExpression`.
+ */
+export declare function derivedMeasureCatalogExpression(definition: DerivedMeasureDefinition): ProtocolExpression;
 export declare function metricExpression(spec: AggregationSpec | DerivedMetricSpec): ProtocolExpression;
 /**
  * The formula in the shape it was authored in, beside the inlined form.

package/dist/utils/protocol-metric-expressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAGjG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}
+{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AAsDD,gFAAgF;AAChF,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAEjG;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAExG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}

package/dist/utils/protocol-metric-expressions.js

@@ -61,34 +61,46 @@ function aggregationExpression(spec) {
     };
     return result;
 }
-function semanticExpression(expression, references = {}) {
+function semanticExpression(expression, references = {}, referenceName = parseProtocolQualifiedIdentifier) {
     switch (expression.kind) {
         case 'ref':
-            return references[expression.name]
-                ?? {
-                    kind: 'reference',
-                    name: parseProtocolQualifiedIdentifier(expression.name),
-                };
+            // Own properties only: an alias such as `constructor` must stay a reference.
+            return Object.hasOwn(references, expression.name)
+                ? references[expression.name]
+                : { kind: 'reference', name: referenceName(expression.name) };
         case 'literal':
             return { kind: 'literal', value: canonicalValue(expression.value) };
         case 'binary':
             return {
                 kind: 'binary',
                 operator: expression.operator,
-                left: semanticExpression(expression.left, references),
-                right: semanticExpression(expression.right, references),
+                left: semanticExpression(expression.left, references, referenceName),
+                right: semanticExpression(expression.right, references, referenceName),
             };
         case 'function':
             return {
                 kind: 'call',
                 function: expression.name,
-                args: expression.args.map(argument => semanticExpression(argument, references)),
+                args: expression.args.map(argument => semanticExpression(argument, references, referenceName)),
             };
     }
 }
-export function derivedMeasureExpression(definition) {
+function derivedFormula(definition) {
     const aliases = Object.fromEntries(Object.keys(definition.uses).map(alias => [alias, alias]));
-    return semanticExpression(definition.formula(aliases).expression);
+    return definition.formula(aliases).expression;
+}
+/** The published form; aliases must satisfy the protocol identifier grammar. */
+export function derivedMeasureExpression(definition) {
+    return semanticExpression(derivedFormula(definition));
+}
+/**
+ * The catalog form. Catalogs describe local datasets that may never be published,
+ * so aliases keep their locally valid names (for example `__hypequery_value`, or
+ * names past the protocol's length limit) instead of failing catalog creation.
+ * Publishing still validates them through `derivedMeasureExpression`.
+ */
+export function derivedMeasureCatalogExpression(definition) {
+    return semanticExpression(derivedFormula(definition), {}, name => name);
 }
 export function metricExpression(spec) {
     if (spec.__type === 'aggregation_spec')

package/dist/utils/relationship-builder-plan.d.ts

@@ -1,3 +1,4 @@
+import type { RelationshipKey } from '../types.js';
 import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
 /**
  * Query-builder-path planning for to-one relationship joins.
@@ -18,6 +19,7 @@ export interface ResolvedBuilderJoin {
     /** Physical target source table. */
     source: string;
     matchMarker?: string;
+    keys?: readonly RelationshipKey[];
     /** Base join column (unqualified). */
     from: string;
     /** Target join column (unqualified). */

package/dist/utils/relationship-builder-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-builder-plan.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-builder-plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACtD;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEzH;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,GAAE,iBAA+C,GACvD,0BAA0B,GAAG,SAAS,CA2CxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CA4BlB"}
+{"version":3,"file":"relationship-builder-plan.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-builder-plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtF,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACtD;AAED,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,GAAG,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEzH;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,GAAE,iBAA+C,GACvD,0BAA0B,GAAG,SAAS,CA+CxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAoClB"}

package/dist/utils/relationship-builder-plan.js

@@ -1,3 +1,4 @@
+import { relationshipKeys } from './relationship-keys.js';
 import { relationshipMeasureSource } from './relationship-measure-sql.js';
 import { clickhouseDatasetSqlDialect } from './clickhouse-dataset-sql-dialect.js';
 import { resolveRelationshipReference } from './relationship-measures.js';
@@ -29,14 +30,18 @@ export function buildRelationshipBuilderContext(ds, query, context, dialect = cl
         if (joinByRelationship.has(relationshipName)) {
             continue;
         }
-        const measureNames = (query.measures ?? []).filter(name => name.startsWith(`${relationshipName}.`)).map(name => name.slice(relationshipName.length + 1));
-        const projected = measureNames.length ? relationshipMeasureSource(target, relationship.to, measureNames, dialect) : undefined;
+        const measureNames = (query.measures ?? [])
+            .filter(name => name.startsWith(`${relationshipName}.`))
+            .map(name => name.slice(relationshipName.length + 1));
+        const keys = relationshipKeys(relationship);
+        const projected = measureNames.length ? relationshipMeasureSource(target, keys.map(key => key.to), measureNames, dialect) : undefined;
         joinByRelationship.set(relationshipName, {
             relationship: relationshipName,
             source: projected?.source ?? target.source,
             matchMarker: projected?.marker,
             from: relationship.from,
             to: relationship.to,
+            keys,
             tenant: tenantPredicate && target.tenantKey
                 ? { field: target.tenantKey, ...tenantPredicate }
                 : undefined,
@@ -85,13 +90,20 @@ export function applyRelationshipJoins(qb, ctx) {
                 'would fan out duplicate target keys and inflate aggregates, so relationship-qualified fields ' +
                 'are unavailable with this builder.');
         }
-        qb = qb.leftAnyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, join.tenant
+        const tenant = join.tenant
             ? {
                 column: `${join.relationship}.${join.tenant.field}`,
                 operator: join.tenant.operator,
                 value: join.tenant.value,
             }
-            : undefined);
+            : undefined;
+        if (join.keys && join.keys.length > 1) {
+            // Key-pair form; @hypequery/clickhouse >= 2.13.0.
+            const pairs = join.keys.map(key => [`${ctx.baseSource}.${key.from}`, `${join.relationship}.${key.to}`]);
+            qb = qb.leftAnyJoin(join.source, [pairs[0], ...pairs.slice(1)], join.relationship, tenant);
+            continue;
+        }
+        qb = qb.leftAnyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, tenant);
     }
     return qb;
 }

package/dist/utils/relationship-definition.d.ts

@@ -0,0 +1,6 @@
+import type { RelationshipDefinition, RelationshipKind, RelationshipJoin } from '../types.js';
+export declare function createRelationship<TTarget extends {
+    __type: 'dataset';
+    name: string;
+}, TKind extends RelationshipKind>(kind: TKind, target: () => TTarget, join: RelationshipJoin): RelationshipDefinition<TTarget, TKind>;
+//# sourceMappingURL=relationship-definition.d.ts.map

package/dist/utils/relationship-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-definition.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG9F,wBAAgB,kBAAkB,CAChC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACnD,KAAK,SAAS,gBAAgB,EAE9B,IAAI,EAAE,KAAK,EACX,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE,gBAAgB,GACrB,sBAAsB,CAAC,OAAO,EAAE,KAAK,CAAC,CAOxC"}

package/dist/utils/relationship-definition.js

@@ -0,0 +1,9 @@
+import { normalizeRelationshipJoin } from './relationship-keys.js';
+export function createRelationship(kind, target, join) {
+    return {
+        __type: 'relationship',
+        kind,
+        target,
+        ...normalizeRelationshipJoin(join),
+    };
+}

package/dist/utils/relationship-key-check.d.ts

@@ -11,6 +11,8 @@ export interface ToOneRelationshipTarget {
     target: AnyDatasetInstance;
     /** Target join column, which a to-one declaration requires to be unique. */
     column: string;
+    /** Full target key; absent on legacy single-key findings. */
+    columns?: readonly string[];
 }
 /**
  * Lists the to-one relationships to check. `hasMany` is excluded because it
@@ -27,6 +29,8 @@ export interface RelationshipKeyIssue {
     source: string;
     /** Target join column. */
     column: string;
+    /** Full target key; absent on legacy single-key findings. */
+    columns?: readonly string[];
     /** Target rows with a non-NULL key, within the checked tenant scope. Large counts are decimal strings. */
     rows: number | string;
     /** Distinct non-NULL keys, within the checked tenant scope. Large counts are decimal strings. */

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

@@ -1 +1 @@
-{"version":3,"file":"relationship-key-check.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-key-check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAA0B,MAAM,aAAa,CAAC;AAE9E,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,sBAAsB;IACtB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GACvB,uBAAuB,EAAE,CAuB3B;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,0GAA0G;IAC1G,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,iGAAiG;IACjG,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAchD;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,uBAAuB,EAC9B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,oBAAoB,GAAG,SAAS,CAkBlC"}
+{"version":3,"file":"relationship-key-check.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-key-check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAA0B,MAAM,aAAa,CAAC;AAG9E,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,sBAAsB;IACtB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GACvB,uBAAuB,EAAE,CA2B3B;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,0GAA0G;IAC1G,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,iGAAiG;IACjG,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAchD;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,uBAAuB,EAC9B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,oBAAoB,GAAG,SAAS,CAmBlC"}

package/dist/utils/relationship-key-check.js

@@ -2,6 +2,7 @@
  * Pure helpers for `checkRelationships`: which relationships a check covers,
  * and how a key-count row becomes a finding.
  */
+import { relationshipKeys } from './relationship-keys.js';
 /**
  * Lists the to-one relationships to check. `hasMany` is excluded because it
  * never joins, so its key has no uniqueness requirement. An explicit
@@ -22,12 +23,16 @@ export function listToOneRelationships(ds, only) {
     }
     return declared
         .filter(([name, relationship]) => relationship.kind !== 'hasMany' && (!only || only.includes(name)))
-        .map(([name, relationship]) => ({
-        relationship: name,
-        kind: relationship.kind,
-        target: relationship.target(),
-        column: relationship.to,
-    }));
+        .map(([name, relationship]) => {
+        const columns = relationshipKeys(relationship).map(key => key.to);
+        return {
+            relationship: name,
+            kind: relationship.kind,
+            target: relationship.target(),
+            column: relationship.to,
+            ...(columns.length > 1 ? { columns } : {}),
+        };
+    });
 }
 /** Reads a count without losing precision when a driver returns UInt64 as a string. */
 export function readCount(value) {
@@ -63,10 +68,17 @@ export function relationshipKeyIssue(entry, rows, distinctKeys) {
         target: entry.target.name,
         source,
         column: entry.column,
+        ...(entry.columns ? { columns: [...entry.columns] } : {}),
         rows: displayCount(rows),
         distinctKeys: displayCount(distinctKeys),
-        message: `Relationship "${entry.relationship}" is declared ${entry.kind}, but "${source}.${entry.column}" ` +
+        message: `Relationship "${entry.relationship}" is declared ${entry.kind}, but ${describeKey(source, entry)} ` +
             `has ${rows} rows for ${distinctKeys} distinct keys. Joins pick an arbitrary matching row; ` +
             'make the key unique or declare the relationship as hasMany.',
     };
 }
+/** `"customers.id"`, or `("customers.id", "customers.region")` for a composite key. */
+function describeKey(source, entry) {
+    if (!entry.columns)
+        return `"${source}.${entry.column}"`;
+    return `(${entry.columns.map(column => `"${source}.${column}"`).join(', ')})`;
+}

package/dist/utils/relationship-keys.d.ts

@@ -0,0 +1,17 @@
+import type { RelationshipDefinition, RelationshipJoin, RelationshipKey } from '../types.js';
+type NormalizedRelationshipJoin = Pick<RelationshipDefinition, 'from' | 'to' | 'keys'>;
+/**
+ * Snapshot an authored join. `{ from, to }` passes through unchanged, as it
+ * always has; `keys` pairs are validated before they are interpolated into SQL.
+ */
+export declare function normalizeRelationshipJoin(join: RelationshipJoin): NormalizedRelationshipJoin;
+/**
+ * Rebuild a serialized composite key. Portable records carry `keys` only for
+ * composite relationships, and `from`/`to` must mirror the first pair.
+ */
+export declare function rehydrateCompositeRelationshipJoin(from: string, to: string, keys: readonly RelationshipKey[]): NormalizedRelationshipJoin;
+export declare function validateRelationshipKeys(keys: readonly RelationshipKey[]): asserts keys is readonly [RelationshipKey, ...RelationshipKey[]];
+/** Return the whole equality key; legacy relationships remain single-key. */
+export declare function relationshipKeys(relationship: Pick<RelationshipDefinition, 'from' | 'to' | 'keys'>): readonly RelationshipKey[];
+export {};
+//# sourceMappingURL=relationship-keys.d.ts.map

package/dist/utils/relationship-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-keys.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI7F,KAAK,0BAA0B,GAAG,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,CAAC;AAEvF;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,gBAAgB,GAAG,0BAA0B,CAgB5F;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,0BAA0B,CAU5B;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,OAAO,CAAC,IAAI,IAAI,SAAS,CAAC,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC,CAYlE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,GAAG,SAAS,eAAe,EAAE,CAQ/H"}

package/dist/utils/relationship-keys.js

@@ -0,0 +1,63 @@
+const COLUMN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Snapshot an authored join. `{ from, to }` passes through unchanged, as it
+ * always has; `keys` pairs are validated before they are interpolated into SQL.
+ */
+export function normalizeRelationshipJoin(join) {
+    if (join.keys === undefined) {
+        return { from: join.from, to: join.to };
+    }
+    if (join.from !== undefined || join.to !== undefined) {
+        throw new Error('Relationship keys cannot be combined with from/to.');
+    }
+    const keys = join.keys;
+    validateRelationshipKeys(keys);
+    const copy = [
+        Object.freeze({ from: keys[0].from, to: keys[0].to }),
+        ...keys.slice(1).map(key => Object.freeze({ from: key.from, to: key.to })),
+    ];
+    // A single pair is the legacy relationship: contracts and catalogs carry
+    // `keys` only for composite relationships, however the pair was authored.
+    return { from: copy[0].from, to: copy[0].to, ...(copy.length > 1 ? { keys: Object.freeze(copy) } : {}) };
+}
+/**
+ * Rebuild a serialized composite key. Portable records carry `keys` only for
+ * composite relationships, and `from`/`to` must mirror the first pair.
+ */
+export function rehydrateCompositeRelationshipJoin(from, to, keys) {
+    validateRelationshipKeys(keys);
+    if (keys.length < 2) {
+        throw new Error('Serialized relationship keys must contain at least two pairs; single-key relationships use from/to.');
+    }
+    const join = normalizeRelationshipJoin({ keys });
+    if (join.from !== from || join.to !== to) {
+        throw new Error('Relationship from/to must match the first keys pair.');
+    }
+    return join;
+}
+export function validateRelationshipKeys(keys) {
+    if (!Array.isArray(keys) || keys.length === 0)
+        throw new Error('Relationship keys must be a non-empty array.');
+    const from = new Set();
+    const to = new Set();
+    for (const key of keys) {
+        if (!key || typeof key.from !== 'string' || typeof key.to !== 'string' || !COLUMN.test(key.from) || !COLUMN.test(key.to)) {
+            throw new Error('Relationship keys must contain safe physical from/to column identifiers.');
+        }
+        if (from.has(key.from) || to.has(key.to))
+            throw new Error('Relationship keys must not repeat a source or target column.');
+        from.add(key.from);
+        to.add(key.to);
+    }
+}
+/** Return the whole equality key; legacy relationships remain single-key. */
+export function relationshipKeys(relationship) {
+    const keys = relationship.keys ?? [{ from: relationship.from, to: relationship.to }];
+    if (!relationship.keys)
+        return keys;
+    validateRelationshipKeys(keys);
+    if (keys[0].from !== relationship.from || keys[0].to !== relationship.to) {
+        throw new Error('Relationship from/to must match the first keys pair.');
+    }
+    return keys;
+}

package/dist/utils/relationship-measure-sql.d.ts

@@ -2,7 +2,7 @@ import type { AnyDatasetInstance } from '../types.js';
 import type { RelationshipBuilderContext } from './relationship-builder-plan.js';
 import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
 /** Explicit projection avoids marker collisions and makes absent targets detectable under join_use_nulls=0. */
-export declare function relationshipMeasureSource(target: AnyDatasetInstance, to: string, names: readonly string[], dialect: DatasetSqlDialect): {
+export declare function relationshipMeasureSource(target: AnyDatasetInstance, to: readonly string[], names: readonly string[], dialect: DatasetSqlDialect): {
     source: string;
     marker: string;
 };

package/dist/utils/relationship-measure-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,aAAa,CAAC;AAEvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAIjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,+GAA+G;AAC/G,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,iBAAiB;;;EAgBrI;AAED,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B;;;;EAevH"}
+{"version":3,"file":"relationship-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,aAAa,CAAC;AAEvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAIjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,+GAA+G;AAC/G,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,iBAAiB;;;EAgBhJ;AAED,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B;;;;EAevH"}

package/dist/utils/relationship-measure-sql.js

@@ -4,7 +4,7 @@ import { measureToAggregationSpec } from './dataset-normalization.js';
 import { applyFilteredAggregationExpression } from './filtered-aggregation-sql.js';
 /** Explicit projection avoids marker collisions and makes absent targets detectable under join_use_nulls=0. */
 export function relationshipMeasureSource(target, to, names, dialect) {
-    const columns = new Set([to, ...(target.tenantKey ? [target.tenantKey] : [])]);
+    const columns = new Set([...to, ...(target.tenantKey ? [target.tenantKey] : [])]);
     for (const [name, dimension] of Object.entries(target.dimensions))
         if (!dimension.sql)
             columns.add(dimension.column ?? name);

package/dist/utils/semantic-query-syntax.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-query-syntax.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-query-syntax.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI7D,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,MAAM,EAAE,CAarF;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAIzE"}
+{"version":3,"file":"semantic-query-syntax.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-query-syntax.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,MAAM,EAAE,CAarF;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAIzE"}

package/dist/utils/semantic-query-syntax.js

@@ -1,10 +1,9 @@
-import { SEMANTIC_FILTER_OPERATORS } from '../constants.js';
-const FILTER_OPERATORS = new Set(SEMANTIC_FILTER_OPERATORS);
+import { isSemanticFilterOperator } from '../constants.js';
 /** Reject SQL structure outside the semantic contract before reaching a builder. */
 export function semanticQuerySyntaxErrors(query) {
     const errors = [];
     for (const filter of query.filters ?? []) {
-        if (!FILTER_OPERATORS.has(filter.operator)) {
+        if (!isSemanticFilterOperator(filter.operator)) {
             errors.push(`Unsupported semantic filter operator "${String(filter.operator)}".`);
         }
     }

package/dist/utils/shift-measure-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shift-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;EAclG;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG,MAAM,CAGpG;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOrH;AAED,+FAA+F;AAC/F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,MAAM,CAMlH;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAsBhK"}
+{"version":3,"file":"shift-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/shift-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;EAoBlG;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG,MAAM,CAGpG;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAOrH;AAED,+FAA+F;AAC/F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,MAAM,CAMlH;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAsBhK"}

package/dist/utils/shift-measure-sql.js

@@ -3,18 +3,25 @@ import { addTimeSql, subtractTimeSql } from './time-arithmetic-sql.js';
 import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
 import { calendarShiftAtFineGrain } from './shift-measure-grains.js';
 import { shiftWallTimeGuardSql } from './shift-wall-time-sql.js';
+import { anchoredCalendarShiftSql } from './calendar-shift-sql.js';
 /** Preserve the selected portion of a bucket and both authored endpoint operators. */
 export function shiftRangeSql(shift, axis, period) {
     const first = period ?? '_hq_first';
     const last = period ?? '_hq_last';
     const end = addTimeSql(last, 1, axis.grain);
-    const upper = subtractTimeSql(`least(${end}, _hq_upper)`, shift.interval.amount, shift.interval.unit);
+    const calendar = calendarShiftAtFineGrain(shift.interval, axis.grain);
     // Clamp the bucket anchor, then retain its width. Independently clamping both
     // dates would turn March 30–31 into February 28–28, dropping an entire day.
+    // A partial bucket keeps the matching slice of that shifted range, so both
+    // bounds are placed relative to the anchor rather than shifted on their own.
+    const shiftBound = (point, anchor) => calendar
+        ? anchoredCalendarShiftSql(point, anchor, shift.interval)
+        : subtractTimeSql(point, shift.interval.amount, shift.interval.unit);
+    const upper = shiftBound(`least(${end}, _hq_upper)`, last);
     const shiftedEnd = addTimeSql(subtractTimeSql(last, shift.interval.amount, shift.interval.unit), 1, axis.grain);
     return {
-        lower: subtractTimeSql(`greatest(${first}, _hq_lower)`, shift.interval.amount, shift.interval.unit),
-        upper: calendarShiftAtFineGrain(shift.interval, axis.grain) ? `if(_hq_upper >= ${end}, ${shiftedEnd}, ${upper})` : upper,
+        lower: shiftBound(`greatest(${first}, _hq_lower)`, first),
+        upper: calendar ? `if(_hq_upper >= ${end}, ${shiftedEnd}, ${upper})` : upper,
         lowerInclusive: period ? `(${period} > _hq_lower OR ${Number(axis.lowerInclusive)})` : String(Number(axis.lowerInclusive)),
         upperInclusive: `(_hq_upper < ${end} AND ${Number(axis.upperInclusive)})`,
     };

package/dist/utils/time-measure-context-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-measure-context-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-context-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM9D,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAUrH;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAOxG"}
+{"version":3,"file":"time-measure-context-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-context-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAO9D,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAerH;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAOxG"}

package/dist/utils/time-measure-context-sql.js

@@ -2,16 +2,22 @@ import { addTimeSql as add, subtractTimeSql as subtract } from './time-arithmeti
 import { calendarShiftAtFineGrain } from './shift-measure-grains.js';
 import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
 import { shiftWallTimeGuardSql } from './shift-wall-time-sql.js';
+import { anchoredCalendarShiftSql } from './calendar-shift-sql.js';
 /** Keep output coordinates separate from each shifted evaluation interval. */
 export function timeMeasureContextCtes(contexts, axis) {
     const end = add('_hq_period', 1, axis.grain);
     const root = `_hq_context0 AS (SELECT _hq_period, _hq_period AS _hq_eval_period, ${end} AS _hq_eval_end, greatest(_hq_period, _hq_lower) AS _hq_eval_lower, least(${end}, _hq_upper) AS _hq_eval_upper, (_hq_period > _hq_lower OR ${Number(axis.lowerInclusive)}) AS _hq_lower_inclusive, (_hq_upper < ${end} AND ${Number(axis.upperInclusive)}) AS _hq_upper_inclusive FROM _hq_series CROSS JOIN _hq_bounds)`;
     return [root, ...contexts.slice(1).map(context => {
             const interval = context.interval;
+            const calendar = calendarShiftAtFineGrain(interval, axis.grain);
             const shift = (value) => subtract(`p.${value}`, interval.amount, interval.unit);
+            // Partial bounds stay inside the shifted bucket; see anchoredCalendarShiftSql.
+            const shiftBound = (value) => calendar
+                ? anchoredCalendarShiftSql(`p.${value}`, 'p._hq_eval_period', interval)
+                : shift(value);
             const period = shift('_hq_eval_period');
-            const shiftedEnd = calendarShiftAtFineGrain(interval, axis.grain) ? add(period, 1, axis.grain) : shift('_hq_eval_end');
-            return `_hq_context${context.id} AS (SELECT p._hq_period, ${period} AS _hq_eval_period, ${shiftedEnd} AS _hq_eval_end, ${shift('_hq_eval_lower')} AS _hq_eval_lower, if(p._hq_eval_upper = p._hq_eval_end, ${shiftedEnd}, ${shift('_hq_eval_upper')}) AS _hq_eval_upper, p._hq_lower_inclusive, p._hq_upper_inclusive FROM _hq_context${context.parent} AS p)`;
+            const shiftedEnd = calendar ? add(period, 1, axis.grain) : shift('_hq_eval_end');
+            return `_hq_context${context.id} AS (SELECT p._hq_period, ${period} AS _hq_eval_period, ${shiftedEnd} AS _hq_eval_end, ${shiftBound('_hq_eval_lower')} AS _hq_eval_lower, if(p._hq_eval_upper = p._hq_eval_end, ${shiftedEnd}, ${shiftBound('_hq_eval_upper')}) AS _hq_eval_upper, p._hq_lower_inclusive, p._hq_upper_inclusive FROM _hq_context${context.parent} AS p)`;
         })];
 }
 export function timeMeasureContextGuard(context, axis) {