@hypequery/datasets 0.21.0 → 0.23.0

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

@@ -0,0 +1,106 @@
+import { semanticQuerySyntaxErrors, semanticOrderDirection } from './semantic-query-syntax.js';
+/** Metric SQL compilation; factory selection and execution belong to the client. */
+import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
+import { applyAggregationSpec, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from '../query-planner.js';
+import { queryTimeFilterSql } from './query-timezone.js';
+import { isTenantScopedFilter } from './metric-handle.js';
+import { getRuntimeTenantPredicate } from './tenant-runtime.js';
+import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './relationship-builder-plan.js';
+import { segmentFilters } from './segments.js';
+import { validateSQLIdentifier } from '../sql-utils.js';
+import { isQualifiedField } from './relationship-fields.js';
+import { validateDerivedCteGrouping } from './derived-cte-validation.js';
+export function buildDerivedMetricSql(ref, spec, query, grain, builderFactory, context) {
+    const syntaxErrors = semanticQuerySyntaxErrors(query);
+    if (syntaxErrors.length)
+        throw new Error(syntaxErrors.join('; '));
+    const dialect = resolveDatasetSqlDialect(builderFactory);
+    const ds = ref.dataset;
+    const joinCtx = buildRelationshipBuilderContext(ds, query, context);
+    // Build the CTE inner query using the builder
+    let cteBuilder = builderFactory.table(ds.source);
+    cteBuilder = applyRelationshipJoins(cteBuilder, joinCtx);
+    const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain, joinCtx, query.timezone, dialect);
+    if (selectParts.length > 0) {
+        cteBuilder = cteBuilder.select(selectParts);
+    }
+    // Base aggregations
+    const refAliases = {};
+    const aggregateAliases = [];
+    for (const [alias, baseMetric] of Object.entries(spec.uses)) {
+        const baseSpec = baseMetric.spec;
+        if (baseSpec.__type !== 'aggregation_spec') {
+            throw new Error(`Derived metric "${ref.name}" references non-base metric "${alias}".`);
+        }
+        cteBuilder = applyAggregationSpec(cteBuilder, ds, baseSpec, alias, joinCtx);
+        refAliases[alias] = alias;
+        aggregateAliases.push(alias);
+    }
+    if (groupByParts.length > 0) {
+        cteBuilder = cteBuilder.groupBy(groupByParts);
+    }
+    // Filters on CTE
+    const tenantColumn = resolveTenantFilterColumn(ds, context);
+    const tenantPredicate = getRuntimeTenantPredicate(context);
+    if (tenantPredicate && tenantColumn) {
+        cteBuilder = cteBuilder.where(qualifyBaseColumn(joinCtx, tenantColumn), tenantPredicate.operator, tenantPredicate.value);
+    }
+    for (const filter of query.filters ?? []) {
+        if (isTenantScopedFilter(ds, filter, context)) {
+            throw new Error(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
+        }
+        const resolvedField = resolveFilterField(ds, filter.field, joinCtx);
+        cteBuilder = cteBuilder.where(queryTimeFilterSql(ds, filter.field, resolvedField, query.timezone), filter.operator, filter.value);
+    }
+    for (const filter of segmentFilters(ds, query.segments)) {
+        cteBuilder = cteBuilder.where(resolveDimensionExpression(ds, filter.field, joinCtx), filter.operator, filter.value);
+    }
+    const { sql: cteSql, parameters: cteParams } = cteBuilder.toSQLWithParams();
+    const groupingErrors = validateDerivedCteGrouping(cteSql, aggregateAliases, groupByParts);
+    if (groupingErrors.length > 0) {
+        throw new Error(groupingErrors.join('; '));
+    }
+    // Outer query: trivial SELECT from the CTE — stays as string concat
+    // because table('base') would fail schema typing
+    const outerSelectParts = [];
+    if (grain)
+        outerSelectParts.push('period');
+    for (const dim of query.dimensions ?? []) {
+        // Joined dimensions surface from the CTE under their quoted qualified alias.
+        if (joinCtx && isQualifiedField(dim)) {
+            outerSelectParts.push(dialect.quoteIdentifier(dim));
+            continue;
+        }
+        validateSQLIdentifier(dim, 'dimension name');
+        outerSelectParts.push(dim);
+    }
+    const formulaExpr = spec.formula(refAliases);
+    validateSQLIdentifier(ref.name, 'metric name');
+    outerSelectParts.push(`${formulaExpr.toSQL()} AS ${ref.name}`);
+    let sql = `WITH base AS (${cteSql}) SELECT ${outerSelectParts.join(', ')} FROM base`;
+    // ORDER BY
+    if (query.orderBy && query.orderBy.length > 0) {
+        const orderParts = query.orderBy.map(o => {
+            if (joinCtx && isQualifiedField(o.field)) {
+                return `${dialect.quoteIdentifier(o.field)} ${semanticOrderDirection(o.direction)}`;
+            }
+            validateSQLIdentifier(o.field, 'order by field');
+            return `${o.field} ${semanticOrderDirection(o.direction)}`;
+        });
+        sql += ` ORDER BY ${orderParts.join(', ')}`;
+    }
+    else if (grain) {
+        sql += ' ORDER BY period';
+    }
+    if (query.limit != null) {
+        // Ensure limit is a safe integer
+        const limit = Math.floor(Math.abs(query.limit));
+        sql += ` LIMIT ${limit}`;
+    }
+    if (query.offset != null) {
+        // Ensure offset is a safe integer
+        const offset = Math.floor(Math.abs(query.offset));
+        sql += ` OFFSET ${offset}`;
+    }
+    return { sql, params: cteParams };
+}

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

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

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

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

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

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

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

@@ -0,0 +1,10 @@
+import type { ExecutionContext, MetricQuery, MetricResult } from '../types.js';
+/** Keep base and derived metric execution on the same result contract. */
+export declare function toMetricQueryResult<T>(rows: T[], options: {
+    metric: string;
+    query: MetricQuery;
+    sql: string;
+    timingMs: number;
+    context?: ExecutionContext;
+}): MetricResult<T>;
+//# sourceMappingURL=metric-query-result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metric-query-result.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK/E,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,EAAE;IACP,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B,GACA,YAAY,CAAC,CAAC,CAAC,CAajB"}

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

@@ -0,0 +1,18 @@
+import { applyPagination } from './pagination.js';
+import { serializeSemanticMeasureValues } from './semantic-result-serialization.js';
+import { getRuntimeTenantId } from './tenant-runtime.js';
+/** Keep base and derived metric execution on the same result contract. */
+export function toMetricQueryResult(rows, options) {
+    const { data, pagination } = applyPagination(rows, options.query.limit, options.query.offset);
+    const serializedData = serializeSemanticMeasureValues(data, [options.metric]);
+    return {
+        data: serializedData,
+        meta: {
+            sql: options.sql,
+            timingMs: options.timingMs,
+            tenant: getRuntimeTenantId(options.context),
+            rowCount: serializedData.length,
+            pagination,
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+/** Semantic metric validation; independent of SQL compilation and execution. */
+import type { MetricQuery, ExecutionContext } from '../types.js';
+import { type ValidationResult } from '../validation.js';
+import { type MetricHandle } from './metric-handle.js';
+export declare function validateMetricQueryInput(metric: MetricHandle, query: MetricQuery, context?: ExecutionContext): ValidationResult;
+//# sourceMappingURL=metric-query-validation.d.ts.map

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

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

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

@@ -0,0 +1,116 @@
+import { semanticQuerySyntaxErrors } from './semantic-query-syntax.js';
+import { validateFilterValue } from '../validation.js';
+import { queryTimezoneErrors } from './query-timezone.js';
+import { protocolMetricCapabilityErrors } from './protocol-metric-capabilities.js';
+import { unsupportedTimeGrainError } from './dataset-time-grains.js';
+import { getMetricGrain, getMetricRef, isTenantScopedFilter } from './metric-handle.js';
+import { validateTenantRuntime } from './tenant-runtime.js';
+import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
+import { validateQualifiedFilter, validateRelationshipTenantRuntime } from './relationship-validation.js';
+import { segmentSelectionErrors } from './segments.js';
+export function validateMetricQueryInput(metric, query, context) {
+    const errors = [...semanticQuerySyntaxErrors(query), ...protocolMetricCapabilityErrors(metric, query), ...queryTimezoneErrors(query.timezone)];
+    const ref = getMetricRef(metric);
+    const ds = ref.dataset;
+    const dimensionNames = Object.keys(ds.dimensions);
+    const filterNames = Object.keys(ds.filters);
+    const grain = getMetricGrain(metric, query);
+    const orderableFields = new Set([
+        ...(query.dimensions ?? []),
+        ref.name,
+        ...(grain ? ['period'] : []),
+    ]);
+    const tenantRuntimeError = validateTenantRuntime(ds, context);
+    if (tenantRuntimeError) {
+        errors.push(tenantRuntimeError);
+    }
+    const relationshipTenantError = validateRelationshipTenantRuntime(ds, query, context);
+    if (relationshipTenantError) {
+        errors.push(relationshipTenantError);
+    }
+    if (metric.__type === 'grained_metric_ref' && query.by && query.by !== metric.grain) {
+        errors.push(`Metric "${ref.name}" is already grained by "${metric.grain}" and cannot be queried with by="${query.by}".`);
+    }
+    // Validate dimensions
+    for (const dim of query.dimensions ?? []) {
+        if (isQualifiedField(dim)) {
+            const resolution = resolveQualifiedField(ds, dim);
+            if (resolution?.error) {
+                errors.push(resolution.error);
+            }
+            continue;
+        }
+        if (!dimensionNames.includes(dim)) {
+            errors.push(`Unknown dimension "${dim}". Available: ${dimensionNames.join(', ')}`);
+        }
+    }
+    // Validate filters
+    for (const filter of query.filters ?? []) {
+        if (isQualifiedField(filter.field)) {
+            const filterError = validateQualifiedFilter(ds, filter, context);
+            if (filterError) {
+                errors.push(filterError);
+            }
+            continue;
+        }
+        if (!filterNames.includes(filter.field)) {
+            errors.push(`Unknown filter field "${filter.field}". Available: ${filterNames.join(', ')}`);
+            continue;
+        }
+        const filterDefinition = ds.filters[filter.field];
+        if (filterDefinition?.operators && !filterDefinition.operators.includes(filter.operator)) {
+            errors.push(`Filter "${filter.field}" does not allow operator "${filter.operator}". Allowed: ${filterDefinition.operators.join(', ')}`);
+            continue;
+        }
+        const resolvedField = ds.filters[filter.field]?.field ?? filter.field;
+        if (isTenantScopedFilter(ds, filter, context)) {
+            errors.push(`Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`);
+            continue;
+        }
+        const fieldType = ds.dimensions[resolvedField]?.fieldType;
+        if (fieldType) {
+            const filterError = validateFilterValue(filter, fieldType);
+            if (filterError) {
+                errors.push(filterError);
+            }
+        }
+    }
+    // Validate order by fields against the metric output shape
+    for (const order of query.orderBy ?? []) {
+        if (!orderableFields.has(order.field)) {
+            errors.push(`Unknown orderBy field "${order.field}". Available: ${Array.from(orderableFields).join(', ')}`);
+        }
+    }
+    // Validate grain requires timeKey
+    if (query.by && !ds.timeKey) {
+        errors.push(`Cannot use "by" grain — dataset "${ds.name}" has no timeKey.`);
+    }
+    // Validate grain is one the planner can bucket on
+    errors.push(...segmentSelectionErrors(ds, query.segments));
+    const grainError = query.by && ds.timeKey ? unsupportedTimeGrainError(ds, query.by) : undefined;
+    if (grainError) {
+        errors.push(grainError);
+    }
+    if (query.limit != null && (!Number.isInteger(query.limit) || query.limit < 0)) {
+        errors.push(`Invalid limit: expected a non-negative integer.`);
+    }
+    if (query.offset != null && (!Number.isInteger(query.offset) || query.offset < 0)) {
+        errors.push(`Invalid offset: expected a non-negative integer.`);
+    }
+    // Validate limits
+    if (ds.limits) {
+        if (ds.limits.maxDimensions && (query.dimensions?.length ?? 0) > ds.limits.maxDimensions) {
+            errors.push(`Too many dimensions (${query.dimensions?.length}). Max: ${ds.limits.maxDimensions}`);
+        }
+        if (ds.limits.maxMeasures && 1 > ds.limits.maxMeasures) {
+            errors.push(`Too many measures (1). Max: ${ds.limits.maxMeasures}`);
+        }
+        if (ds.limits.maxFilters && (query.filters?.length ?? 0) > ds.limits.maxFilters) {
+            errors.push(`Too many filters (${query.filters?.length}). Max: ${ds.limits.maxFilters}`);
+        }
+        if (ds.limits.maxResultSize && query.limit != null && query.limit > ds.limits.maxResultSize) {
+            errors.push(`Too many results requested (${query.limit}). Max: ${ds.limits.maxResultSize}`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

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,5 @@
+import type { RelationshipKey } from '../types.js';
+import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
 /**
  * Query-builder-path planning for to-one relationship joins.
  *
@@ -16,6 +18,8 @@ export interface ResolvedBuilderJoin {
     relationship: string;
     /** Physical target source table. */
     source: string;
+    matchMarker?: string;
+    keys?: readonly RelationshipKey[];
     /** Base join column (unqualified). */
     from: string;
     /** Target join column (unqualified). */
@@ -30,13 +34,13 @@ export interface RelationshipBuilderContext {
     joins: ResolvedBuilderJoin[];
     joinByRelationship: Map<string, ResolvedBuilderJoin>;
 }
-type QueryLike = Pick<DatasetQuery & MetricQuery, 'dimensions' | 'filters' | 'orderBy'>;
+type QueryLike = Pick<DatasetQuery & MetricQuery, 'dimensions' | 'filters' | 'orderBy'> & Pick<DatasetQuery, 'measures'>;
 /**
  * Builds the join context for a query, or returns undefined when the query
  * references no relationship-qualified fields. Validation runs first, so any
  * qualified name that fails to resolve here is skipped defensively.
  */
-export declare function buildRelationshipBuilderContext(ds: AnyDatasetInstance, query: QueryLike, context?: ExecutionContext): RelationshipBuilderContext | undefined;
+export declare function buildRelationshipBuilderContext(ds: AnyDatasetInstance, query: QueryLike, context?: ExecutionContext, dialect?: DatasetSqlDialect): RelationshipBuilderContext | undefined;
 /** Qualifies a base physical column with the base source when joins are active. */
 export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | undefined, column: string): string;
 /**

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":"AAAA;;;;;;;;;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,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,CAAC;AAExF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,0BAA0B,GAAG,SAAS,CAuCxC;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,13 +1,7 @@
-/**
- * Query-builder-path planning for to-one relationship joins.
- *
- * When a dataset/metric query references relationship-qualified fields
- * (`<relationship>.<field>`), the builder path aliases the joined target with
- * the relationship name, table-qualifies base columns with the base source
- * name, and aliases joined selections back to their quoted qualified name. When
- * no qualified field is referenced, no context is produced and the builder path
- * behaves exactly as before.
- */
+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';
 import { getRuntimeTenantPredicate } from './tenant-runtime.js';
 import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
 /**
@@ -15,9 +9,10 @@ import { isQualifiedField, resolveQualifiedField } from './relationship-fields.j
  * references no relationship-qualified fields. Validation runs first, so any
  * qualified name that fails to resolve here is skipped defensively.
  */
-export function buildRelationshipBuilderContext(ds, query, context) {
+export function buildRelationshipBuilderContext(ds, query, context, dialect = clickhouseDatasetSqlDialect) {
     const referenced = [
         ...(query.dimensions ?? []),
+        ...(query.measures ?? []),
         ...(query.filters ?? []).map((filter) => filter.field),
         ...(query.orderBy ?? []).map((order) => order.field),
     ].filter(isQualifiedField);
@@ -27,7 +22,7 @@ export function buildRelationshipBuilderContext(ds, query, context) {
     const tenantPredicate = getRuntimeTenantPredicate(context);
     const joinByRelationship = new Map();
     for (const name of referenced) {
-        const resolution = resolveQualifiedField(ds, name);
+        const resolution = resolveRelationshipReference(ds, name, query.measures);
         if (!resolution || !resolution.resolved) {
             continue;
         }
@@ -35,11 +30,18 @@ export function buildRelationshipBuilderContext(ds, query, context) {
         if (joinByRelationship.has(relationshipName)) {
             continue;
         }
+        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: target.source,
+            source: projected?.source ?? target.source,
+            matchMarker: projected?.marker,
             from: relationship.from,
             to: relationship.to,
+            keys,
             tenant: tenantPredicate && target.tenantKey
                 ? { field: target.tenantKey, ...tenantPredicate }
                 : undefined,
@@ -88,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(', ')})`;
+}