@hypequery/datasets 0.8.0 → 0.10.0

package/dist/utils/dataset-normalization.js

@@ -18,7 +18,17 @@ export function normalizeFilters(dimensions, filters) {
 export function normalizeMeasures(measures) {
     return (measures ?? {});
 }
-export function normalizeRelationships(relationships) {
+export function normalizeRelationships(relationships, source) {
+    for (const name of Object.keys(relationships ?? {})) {
+        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.');
+        }
+        if (name.includes('.')) {
+            throw new Error(`Invalid relationship "${name}": relationship names cannot contain "." because qualified ` +
+                'fields are addressed as "<relationship>.<dimension>".');
+        }
+    }
     return (relationships ?? {});
 }
 export function measureToAggregationSpec(measureName, definition) {
@@ -29,6 +39,8 @@ export function measureToAggregationSpec(measureName, definition) {
         __type: 'aggregation_spec',
         aggregation: definition.aggregation,
         field: definition.field,
+        argField: definition.argField,
+        level: definition.level,
         sql: definition.sql,
         filters: definition.filters,
     };

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":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAO9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAmHlB"}
+{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAY9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CA0JlB"}

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

@@ -1,6 +1,8 @@
 import { validateFilterValue } from '../validation.js';
 import { SUPPORTED_TIME_GRAINS, isSupportedTimeGrain } from '../constants.js';
 import { getRuntimeTenantPredicate, validateTenantRuntime, } from './tenant-runtime.js';
+import { isQualifiedField, resolveQualifiedField, } from './relationship-fields.js';
+import { validateQualifiedFilter } from './relationship-validation.js';
 export function validateDatasetQueryInput(ds, query, context) {
     const errors = [];
     const dimensionNames = Object.keys(ds.dimensions);
@@ -21,23 +23,43 @@ export function validateDatasetQueryInput(ds, query, context) {
         errors.push(`Dataset "${ds.name}" query must select at least one dimension or measure.`);
     }
     if (query.dimensions) {
-        const invalid = query.dimensions.filter(dimension => !dimensionNames.includes(dimension));
-        if (invalid.length > 0) {
-            errors.push(`Unknown dimensions: ${invalid.join(', ')}. Available: ${dimensionNames.join(', ')}`);
+        for (const dimension of query.dimensions) {
+            if (isQualifiedField(dimension)) {
+                const resolution = resolveQualifiedField(ds, dimension);
+                if (resolution?.error) {
+                    errors.push(resolution.error);
+                }
+                continue;
+            }
+            if (!dimensionNames.includes(dimension)) {
+                errors.push(`Unknown dimensions: ${dimension}. Available: ${dimensionNames.join(', ')}`);
+            }
         }
     }
     if (query.measures) {
-        const invalid = query.measures.filter(measure => !measureNames.includes(measure));
-        if (invalid.length > 0) {
-            errors.push(`Unknown measures: ${invalid.join(', ')}. Available: ${measureNames.join(', ')}`);
+        for (const measure of query.measures) {
+            if (isQualifiedField(measure)) {
+                errors.push(`Measure "${measure}" is relationship-qualified. Measures can only be defined on the base dataset "${ds.name}", not traversed through relationships.`);
+                continue;
+            }
+            if (!measureNames.includes(measure)) {
+                errors.push(`Unknown measures: ${measure}. Available: ${measureNames.join(', ')}`);
+            }
         }
     }
     if (query.filters) {
-        const invalid = query.filters.filter(filter => !filterNames.includes(filter.field));
-        if (invalid.length > 0) {
-            errors.push(`Unknown filter fields: ${invalid.map(filter => filter.field).join(', ')}. Available: ${filterNames.join(', ')}`);
-        }
         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 fields: ${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(', ')}`);
@@ -63,9 +85,25 @@ export function validateDatasetQueryInput(ds, query, context) {
         }
     }
     if (query.orderBy) {
-        const invalid = query.orderBy.filter(order => !orderableFields.has(order.field));
+        const invalid = [];
+        for (const order of query.orderBy) {
+            if (isQualifiedField(order.field)) {
+                const resolution = resolveQualifiedField(ds, order.field);
+                if (resolution?.error) {
+                    errors.push(resolution.error);
+                    continue;
+                }
+                // A resolvable qualified field is only orderable when it is also
+                // selected as a dimension (same rule as unqualified fields). Otherwise
+                // the sort silently no-ops in-memory and breaks the SQL alias, so fall
+                // through to the orderableFields check rather than accepting it.
+            }
+            if (!orderableFields.has(order.field)) {
+                invalid.push(order.field);
+            }
+        }
         if (invalid.length > 0) {
-            errors.push(`Unknown orderBy fields: ${invalid.map(order => order.field).join(', ')}. Available: ${Array.from(orderableFields).join(', ')}`);
+            errors.push(`Unknown orderBy fields: ${invalid.join(', ')}. Available: ${Array.from(orderableFields).join(', ')}`);
         }
     }
     if (query.by && !ds.timeKey) {

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAKrB,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,IAAI,CAwCN;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,IAAI,CAmBN"}
+{"version":3,"file":"dataset-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAYrB,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,EACrB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,IAAI,CA0DN;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,IAAI,CAmBN"}

package/dist/utils/dataset-validation.js

@@ -1,12 +1,32 @@
 import { validateFilterValue } from '../validation.js';
+import { validatePercentileLevel } from '../measure.js';
 const NUMERIC_FIELD_TYPES = new Set(['number']);
+// Aggregations whose output tracks the input field's type, so a metric
+// (contract valueType: 'number') needs a numeric input dimension.
+const NUMERIC_INPUT_AGGREGATIONS = new Set([
+    'sum', 'avg', 'percentile', 'stddev', 'variance', 'argMax', 'argMin',
+]);
 export function validateBaseMetric(ds, metricName, spec, options) {
+    if (spec.aggregation === 'argMax' || spec.aggregation === 'argMin') {
+        if (typeof spec.argField !== 'string' || spec.argField.trim().length === 0) {
+            throw new Error(`Invalid metric "${metricName}": ${spec.aggregation}() requires a non-empty argField ("by" column).`);
+        }
+        if (spec.filters?.length) {
+            throw new Error(`Invalid metric "${metricName}": measure filters are not supported on ${spec.aggregation} aggregations.`);
+        }
+    }
+    if (spec.aggregation === 'percentile') {
+        if (spec.level == null) {
+            throw new Error(`Invalid metric "${metricName}": percentile() requires a level.`);
+        }
+        validatePercentileLevel(spec.level);
+    }
     const dimension = ds.dimensions[spec.field];
     if (!dimension && !options?.allowHiddenField) {
         throw new Error(`Invalid metric "${metricName}": dimension "${spec.field}" does not exist on dataset "${ds.name}".`);
     }
     if (dimension &&
-        (spec.aggregation === 'sum' || spec.aggregation === 'avg') &&
+        NUMERIC_INPUT_AGGREGATIONS.has(spec.aggregation) &&
         !NUMERIC_FIELD_TYPES.has(dimension.fieldType)) {
         throw new Error(`Invalid metric "${metricName}": ${spec.aggregation}() requires a numeric dimension, but "${spec.field}" is ${dimension.fieldType}.`);
     }

package/dist/utils/filtered-aggregation-sql.d.ts

@@ -1,5 +1,6 @@
 import type { AggregationSpec, AnyDatasetInstance } from '../types.js';
+import type { RelationshipBuilderContext } from './relationship-builder-plan.js';
 type DatasetShape = AnyDatasetInstance;
-export declare function applyFilteredAggregationExpression(ds: DatasetShape, spec: AggregationSpec, fieldOrExpr: string): string;
+export declare function applyFilteredAggregationExpression(ds: DatasetShape, spec: AggregationSpec, fieldOrExpr: string, joinCtx?: RelationshipBuilderContext): string;
 export {};
 //# sourceMappingURL=filtered-aggregation-sql.d.ts.map

package/dist/utils/filtered-aggregation-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filtered-aggregation-sql.d.ts","sourceRoot":"","sources":["../../src/utils/filtered-aggregation-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAgB,MAAM,aAAa,CAAC;AAGrF,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAiEvC,wBAAgB,kCAAkC,CAChD,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAsBR"}
+{"version":3,"file":"filtered-aggregation-sql.d.ts","sourceRoot":"","sources":["../../src/utils/filtered-aggregation-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAgB,MAAM,aAAa,CAAC;AAErF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAEjF,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAkEvC,wBAAgB,kCAAkC,CAChD,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CA+BR"}

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

@@ -17,8 +17,8 @@ function renderMeasureFilterLiteral(value) {
     }
     throw new Error(`Unsupported literal type in measure filter: ${typeof value}`);
 }
-function renderMeasureFilterCondition(ds, filter) {
-    const field = resolveFilterField(ds, filter.field);
+function renderMeasureFilterCondition(ds, filter, joinCtx) {
+    const field = resolveFilterField(ds, filter.field, joinCtx);
     switch (filter.operator) {
         case 'eq':
             return `${field} = ${renderMeasureFilterLiteral(filter.value)}`;
@@ -50,23 +50,32 @@ function renderMeasureFilterCondition(ds, filter) {
         }
     }
 }
-export function applyFilteredAggregationExpression(ds, spec, fieldOrExpr) {
+export function applyFilteredAggregationExpression(ds, spec, fieldOrExpr, joinCtx) {
     if (!spec.filters?.length) {
         return fieldOrExpr;
     }
     const combinedCondition = spec.filters
-        .map(filter => renderMeasureFilterCondition(ds, filter))
+        .map(filter => renderMeasureFilterCondition(ds, filter, joinCtx))
         .map(condition => `(${condition})`)
         .join(' AND ');
     switch (spec.aggregation) {
         case 'sum':
             return `if(${combinedCondition}, ${fieldOrExpr}, 0)`;
+        // Aggregate functions skip NULLs, so the NULL fallback excludes
+        // non-matching rows from percentile/stddev/variance too.
         case 'count':
         case 'countDistinct':
         case 'avg':
         case 'min':
         case 'max':
+        case 'percentile':
+        case 'stddev':
+        case 'variance':
             return `if(${combinedCondition}, ${fieldOrExpr}, NULL)`;
+        case 'argMax':
+        case 'argMin':
+            // NULL handling under argMax/argMin varies across ClickHouse versions.
+            throw new Error(`Measure filters are not supported on ${spec.aggregation} aggregations.`);
         default:
             return fieldOrExpr;
     }

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

@@ -0,0 +1,56 @@
+/**
+ * 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 type { AnyDatasetInstance, DatasetQuery, ExecutionContext, MetricQuery } from '../types.js';
+import type { QueryBuilderLike } from '../query-builder-protocol.js';
+import { type TenantPredicate } from './tenant-runtime.js';
+export interface ResolvedBuilderJoin {
+    /** Relationship name, used as the joined table's SQL alias. */
+    relationship: string;
+    /** Physical target source table. */
+    source: string;
+    /** Base join column (unqualified). */
+    from: string;
+    /** Target join column (unqualified). */
+    to: string;
+    /** Tenant predicate applied to the joined target, when active. */
+    tenant?: TenantPredicate & {
+        field: string;
+    };
+}
+export interface RelationshipBuilderContext {
+    baseSource: string;
+    joins: ResolvedBuilderJoin[];
+    joinByRelationship: Map<string, ResolvedBuilderJoin>;
+}
+type QueryLike = Pick<DatasetQuery & MetricQuery, 'dimensions' | 'filters' | 'orderBy'>;
+/**
+ * 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;
+/** Qualifies a base physical column with the base source when joins are active. */
+export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | undefined, column: string): string;
+/**
+ * Resolves a relationship-qualified field to its SQL column reference
+ * (`<relationship>.<targetColumn>`). Throws if the name cannot be resolved,
+ * which should be unreachable after validation.
+ */
+export declare function resolveQualifiedColumn(ds: AnyDatasetInstance, name: string): string;
+/**
+ * Applies each relationship LEFT JOIN to the builder and, when runtime tenancy
+ * is active on a target, scopes the joined rows with the tenant predicate.
+ * Builders that support single-match joins (`leftAnyJoin`, e.g. ClickHouse
+ * `LEFT ANY JOIN`) get them so duplicate target keys cannot fan out aggregates.
+ */
+export declare function applyRelationshipJoins(qb: QueryBuilderLike, ctx: RelationshipBuilderContext | undefined): QueryBuilderLike;
+export {};
+//# sourceMappingURL=relationship-builder-plan.d.ts.map

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

@@ -0,0 +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;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAqBlB"}

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

@@ -0,0 +1,92 @@
+/**
+ * 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 { getRuntimeTenantPredicate } from './tenant-runtime.js';
+import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
+/**
+ * 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 function buildRelationshipBuilderContext(ds, query, context) {
+    const referenced = [
+        ...(query.dimensions ?? []),
+        ...(query.filters ?? []).map((filter) => filter.field),
+        ...(query.orderBy ?? []).map((order) => order.field),
+    ].filter(isQualifiedField);
+    if (referenced.length === 0) {
+        return undefined;
+    }
+    const tenantPredicate = getRuntimeTenantPredicate(context);
+    const joinByRelationship = new Map();
+    for (const name of referenced) {
+        const resolution = resolveQualifiedField(ds, name);
+        if (!resolution || !resolution.resolved) {
+            continue;
+        }
+        const { relationshipName, relationship, target } = resolution.resolved;
+        if (joinByRelationship.has(relationshipName)) {
+            continue;
+        }
+        joinByRelationship.set(relationshipName, {
+            relationship: relationshipName,
+            source: target.source,
+            from: relationship.from,
+            to: relationship.to,
+            tenant: tenantPredicate && target.tenantKey
+                ? { field: target.tenantKey, ...tenantPredicate }
+                : undefined,
+        });
+    }
+    return {
+        baseSource: ds.source,
+        joins: Array.from(joinByRelationship.values()),
+        joinByRelationship,
+    };
+}
+/** Qualifies a base physical column with the base source when joins are active. */
+export function qualifyBaseColumn(ctx, column) {
+    return ctx ? `${ctx.baseSource}.${column}` : column;
+}
+/**
+ * Resolves a relationship-qualified field to its SQL column reference
+ * (`<relationship>.<targetColumn>`). Throws if the name cannot be resolved,
+ * which should be unreachable after validation.
+ */
+export function resolveQualifiedColumn(ds, name) {
+    const resolution = resolveQualifiedField(ds, name);
+    if (!resolution || !resolution.resolved) {
+        throw new Error(resolution?.error ?? `Cannot resolve relationship field "${name}".`);
+    }
+    const { relationshipName, targetColumn } = resolution.resolved;
+    return `${relationshipName}.${targetColumn}`;
+}
+/**
+ * Applies each relationship LEFT JOIN to the builder and, when runtime tenancy
+ * is active on a target, scopes the joined rows with the tenant predicate.
+ * Builders that support single-match joins (`leftAnyJoin`, e.g. ClickHouse
+ * `LEFT ANY JOIN`) get them so duplicate target keys cannot fan out aggregates.
+ */
+export function applyRelationshipJoins(qb, ctx) {
+    if (!ctx) {
+        return qb;
+    }
+    for (const join of ctx.joins) {
+        const applyJoin = qb.leftAnyJoin?.bind(qb) ?? qb.leftJoin.bind(qb);
+        qb = applyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, join.tenant
+            ? {
+                column: `${join.relationship}.${join.tenant.field}`,
+                operator: join.tenant.operator,
+                value: join.tenant.value,
+            }
+            : undefined);
+    }
+    return qb;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Resolution helpers for relationship-qualified field names (`relationship.field`).
+ *
+ * v1 supports one hop over to-one relationships (`belongsTo`, `hasOne`) only,
+ * addressing dimensions declared on the target dataset. `hasMany` stays
+ * metadata-only to avoid fan-out corruption of aggregates. See
+ * `plans/relationship-aware-semantics-design.md`.
+ */
+import type { AnyDatasetInstance, DimensionDefinition, RelationshipDefinition } from '../types.js';
+/**
+ * Enumerates the queryable qualified field names (`<name>.<dimension>`) a
+ * relationship contributes, applying the same rules `resolveQualifiedField`
+ * enforces at query time: `hasMany` contributes nothing and SQL-backed target
+ * dimensions are excluded. Keep the two in sync — the catalog, contract, and
+ * generated input schemas all advertise exactly this list.
+ */
+export declare function listQueryableRelationshipFields(name: string, relationship: RelationshipDefinition): string[];
+export interface ParsedQualifiedField {
+    /** The relationship name (prefix before the first dot). */
+    relationship: string;
+    /** Everything after the first dot — the target field, possibly multi-hop. */
+    field: string;
+}
+/** True when a field name is relationship-qualified (contains a dot). */
+export declare function isQualifiedField(name: string): boolean;
+/**
+ * Splits a qualified name into its relationship prefix and remaining field.
+ * Returns null when `name` is not qualified (no dot), so callers can treat it
+ * as a local field.
+ */
+export declare function parseQualifiedField(name: string): ParsedQualifiedField | null;
+export interface ResolvedQualifiedField {
+    /** Relationship name, also used as the SQL table alias / qualified prefix. */
+    relationshipName: string;
+    relationship: RelationshipDefinition;
+    /** The resolved target dataset instance. */
+    target: AnyDatasetInstance;
+    /** Target dimension name (the allowlist key on the target). */
+    targetDimensionName: string;
+    targetDimension: DimensionDefinition;
+    /** Physical column backing the target dimension. */
+    targetColumn: string;
+    /** The qualified name exactly as referenced, e.g. `customer.country`. */
+    qualifiedName: string;
+}
+export type QualifiedFieldResolution = {
+    resolved: ResolvedQualifiedField;
+    error?: undefined;
+} | {
+    resolved?: undefined;
+    error: string;
+};
+/**
+ * Resolves a relationship-qualified field name against a base dataset.
+ *
+ * Returns null when `name` is not qualified (caller handles it as a local
+ * field). Otherwise returns either the resolved to-one target dimension or an
+ * actionable validation error (unknown relationship, multi-hop, `hasMany`,
+ * unknown target dimension, or SQL-backed target dimension).
+ */
+export declare function resolveQualifiedField(ds: AnyDatasetInstance, name: string): QualifiedFieldResolution | null;
+//# sourceMappingURL=relationship-fields.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-fields.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,sBAAsB,GACnC,MAAM,EAAE,CAQV;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAM7E;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,sBAAsB,CAAC;IACrC,4CAA4C;IAC5C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,mBAAmB,CAAC;IACrC,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,EAAE,sBAAsB,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,GACX,wBAAwB,GAAG,IAAI,CAuDjC"}

package/dist/utils/relationship-fields.js

@@ -0,0 +1,98 @@
+/**
+ * Resolution helpers for relationship-qualified field names (`relationship.field`).
+ *
+ * v1 supports one hop over to-one relationships (`belongsTo`, `hasOne`) only,
+ * addressing dimensions declared on the target dataset. `hasMany` stays
+ * metadata-only to avoid fan-out corruption of aggregates. See
+ * `plans/relationship-aware-semantics-design.md`.
+ */
+/**
+ * Enumerates the queryable qualified field names (`<name>.<dimension>`) a
+ * relationship contributes, applying the same rules `resolveQualifiedField`
+ * enforces at query time: `hasMany` contributes nothing and SQL-backed target
+ * dimensions are excluded. Keep the two in sync — the catalog, contract, and
+ * generated input schemas all advertise exactly this list.
+ */
+export function listQueryableRelationshipFields(name, relationship) {
+    if (relationship.kind === 'hasMany') {
+        return [];
+    }
+    const target = relationship.target();
+    return Object.entries(target?.dimensions ?? {})
+        .filter(([, dimension]) => !dimension.sql)
+        .map(([field]) => `${name}.${field}`);
+}
+/** True when a field name is relationship-qualified (contains a dot). */
+export function isQualifiedField(name) {
+    return name.includes('.');
+}
+/**
+ * Splits a qualified name into its relationship prefix and remaining field.
+ * Returns null when `name` is not qualified (no dot), so callers can treat it
+ * as a local field.
+ */
+export function parseQualifiedField(name) {
+    const dot = name.indexOf('.');
+    if (dot === -1) {
+        return null;
+    }
+    return { relationship: name.slice(0, dot), field: name.slice(dot + 1) };
+}
+/**
+ * Resolves a relationship-qualified field name against a base dataset.
+ *
+ * Returns null when `name` is not qualified (caller handles it as a local
+ * field). Otherwise returns either the resolved to-one target dimension or an
+ * actionable validation error (unknown relationship, multi-hop, `hasMany`,
+ * unknown target dimension, or SQL-backed target dimension).
+ */
+export function resolveQualifiedField(ds, name) {
+    const parsed = parseQualifiedField(name);
+    if (!parsed) {
+        return null;
+    }
+    const { relationship: relationshipName, field } = parsed;
+    const relationship = ds.relationships[relationshipName];
+    if (!relationship) {
+        const available = Object.keys(ds.relationships);
+        return {
+            error: available.length > 0
+                ? `Unknown relationship "${relationshipName}" in field "${name}" on dataset "${ds.name}". Available relationships: ${available.join(', ')}.`
+                : `Unknown field "${name}": dataset "${ds.name}" declares no relationships.`,
+        };
+    }
+    if (field.includes('.')) {
+        return {
+            error: `Multi-hop relationship path "${name}" is not supported. Only a single hop is allowed (e.g. "${relationshipName}.<field>").`,
+        };
+    }
+    if (relationship.kind === 'hasMany') {
+        return {
+            error: `Relationship "${relationshipName}" on dataset "${ds.name}" is a hasMany (to-many) relationship and is not queryable, because joining it would fan out and corrupt aggregates. It remains available as metadata only.`,
+        };
+    }
+    const target = relationship.target();
+    const targetDimension = target.dimensions[field];
+    if (!targetDimension) {
+        const available = Object.keys(target.dimensions);
+        return {
+            error: `Unknown dimension "${field}" on relationship "${relationshipName}" (target dataset "${target.name}"). Available: ${available.join(', ')}.`,
+        };
+    }
+    if (targetDimension.sql) {
+        return {
+            error: `Dimension "${name}" is SQL-backed on target dataset "${target.name}"; SQL-backed dimensions are not yet queryable through relationships.`,
+        };
+    }
+    return {
+        resolved: {
+            relationshipName,
+            relationship,
+            target,
+            targetDimensionName: field,
+            targetDimension,
+            targetColumn: targetDimension.column ?? field,
+            qualifiedName: name,
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Shared validation for relationship-qualified filters, used by both the
+ * dataset-query and metric-query validators.
+ */
+import type { AnyDatasetInstance, ExecutionContext, MetricFilter } from '../types.js';
+/**
+ * Validates a relationship-qualified filter (`relationship.field`). Returns an
+ * error message string, or null when the filter is valid.
+ *
+ * Enforces the same tenant rule the base dataset uses: when runtime tenancy is
+ * active and the joined target declares a `tenantKey`, an explicit filter on
+ * that column is rejected (the planner injects the tenant predicate instead).
+ */
+export declare function validateQualifiedFilter(ds: AnyDatasetInstance, filter: MetricFilter, context?: ExecutionContext): string | null;
+//# sourceMappingURL=relationship-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-validation.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACb,MAAM,aAAa,CAAC;AAKrB;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,IAAI,CAgBf"}

package/dist/utils/relationship-validation.js

@@ -0,0 +1,29 @@
+/**
+ * Shared validation for relationship-qualified filters, used by both the
+ * dataset-query and metric-query validators.
+ */
+import { validateFilterValue } from '../validation.js';
+import { getRuntimeTenantPredicate } from './tenant-runtime.js';
+import { resolveQualifiedField } from './relationship-fields.js';
+/**
+ * Validates a relationship-qualified filter (`relationship.field`). Returns an
+ * error message string, or null when the filter is valid.
+ *
+ * Enforces the same tenant rule the base dataset uses: when runtime tenancy is
+ * active and the joined target declares a `tenantKey`, an explicit filter on
+ * that column is rejected (the planner injects the tenant predicate instead).
+ */
+export function validateQualifiedFilter(ds, filter, context) {
+    const resolution = resolveQualifiedField(ds, filter.field);
+    if (!resolution) {
+        return null;
+    }
+    if (!resolution.resolved) {
+        return resolution.error;
+    }
+    const { target, targetColumn, targetDimension } = resolution.resolved;
+    if (getRuntimeTenantPredicate(context) && target.tenantKey && targetColumn === target.tenantKey) {
+        return `Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`;
+    }
+    return validateFilterValue(filter, targetDimension.fieldType);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Semantic layer for defining datasets, metrics, and semantic queries",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",