@hypequery/datasets 0.24.0 → 0.26.0

package/dist/utils/dataset-time-keys.js

@@ -0,0 +1,55 @@
+/**
+ * Multiple time axes per dataset (HQ-80).
+ *
+ * `timeKey` is a dataset's default time axis; `timeKeys` names the other axes
+ * a query may select with `query.timeKey`, such as `shipped_at` beside
+ * `created_at`. A query on another axis compiles against a view of the dataset
+ * whose `timeKey` is that axis, so grains, windows, shifts and time-range
+ * checks follow the selection without each of them knowing about it.
+ */
+/** Every time axis a query may select, the default first; empty without a `timeKey`. */
+export function datasetTimeKeys(dataset) {
+    if (!dataset.timeKey)
+        return [];
+    return [dataset.timeKey, ...(dataset.timeKeys ?? []).filter(key => key !== dataset.timeKey)];
+}
+/** The validation message for a query's `timeKey` selection, or undefined. */
+export function selectedTimeKeyError(dataset, timeKey) {
+    if (timeKey === undefined)
+        return undefined;
+    if (typeof timeKey !== 'string')
+        return 'Invalid timeKey: expected a string.';
+    const keys = datasetTimeKeys(dataset);
+    if (keys.length === 0) {
+        return `Cannot select timeKey "${timeKey}" — dataset "${dataset.name}" has no timeKey.`;
+    }
+    if (!keys.includes(timeKey)) {
+        return `Unknown timeKey "${timeKey}" on dataset "${dataset.name}". Available: ${keys.join(', ')}`;
+    }
+    return undefined;
+}
+/**
+ * True when a query selects an axis other than the dataset's default. Naming
+ * the default explicitly is the same query as omitting it.
+ */
+export function selectsAlternateTimeKey(dataset, timeKey) {
+    return timeKey !== undefined && timeKey !== dataset.timeKey;
+}
+/**
+ * The dataset as seen by a query on `timeKey`: the selected axis becomes
+ * `timeKey` and the rest stay declared, so the view is itself a valid dataset
+ * and rebasing it again is a no-op. Throws for an axis the dataset does not
+ * declare; validate first to report it as a query error.
+ */
+export function datasetOnTimeKey(dataset, timeKey) {
+    if (!selectsAlternateTimeKey(dataset, timeKey))
+        return dataset;
+    const error = selectedTimeKeyError(dataset, timeKey);
+    if (error)
+        throw new Error(error);
+    return {
+        ...dataset,
+        timeKey,
+        timeKeys: Object.freeze(datasetTimeKeys(dataset).filter(key => key !== timeKey)),
+    };
+}

package/dist/utils/enforced-constraints.d.ts

@@ -0,0 +1,14 @@
+import type { AnyDatasetInstance, ExecutionContext } from '../types.js';
+/** Constraints are policy, not queries; a handful per call is plenty (RFC 0019). */
+export declare const MAX_ENFORCED_CONSTRAINTS = 32;
+/**
+ * Errors for the call's RFC 0019 enforced constraints on `ds`. A constraint
+ * the dataset cannot enforce refuses the call, with a message that does not
+ * describe the constraint: it is the provider's policy, not the caller's
+ * input. `callerFilters` is the number of filters the caller supplied, which
+ * share the dataset's filter ceiling with the constraints.
+ */
+export declare function enforcedConstraintErrors(ds: AnyDatasetInstance, context: ExecutionContext | undefined, callerFilters: number): string[];
+/** Throws when the call's constraints cannot all be enforced on `ds`. */
+export declare function assertEnforcedConstraints(ds: AnyDatasetInstance, context?: ExecutionContext): void;
+//# sourceMappingURL=enforced-constraints.d.ts.map

package/dist/utils/enforced-constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforced-constraints.d.ts","sourceRoot":"","sources":["../../src/utils/enforced-constraints.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAgB,MAAM,aAAa,CAAC;AAKtF,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAiB3C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,aAAa,EAAE,MAAM,GACpB,MAAM,EAAE,CAaV;AAED,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAGlG"}

package/dist/utils/enforced-constraints.js

@@ -0,0 +1,57 @@
+import { isSemanticFilterOperator } from '../constants.js';
+import { validateFilterValue } from '../validation.js';
+import { isQualifiedField, resolveQualifiedField } from './relationship-fields.js';
+import { validateQualifiedFilter } from './relationship-validation.js';
+/** Constraints are policy, not queries; a handful per call is plenty (RFC 0019). */
+export const MAX_ENFORCED_CONSTRAINTS = 32;
+function constraintError(ds, constraint, context) {
+    if (typeof constraint !== 'object' || constraint === null)
+        return true;
+    const filter = constraint;
+    if (typeof filter.field !== 'string' || !isSemanticFilterOperator(filter.operator))
+        return true;
+    if (isQualifiedField(filter.field)) {
+        if (!resolveQualifiedField(ds, filter.field)?.resolved)
+            return true;
+        return validateQualifiedFilter(ds, filter, context) !== null;
+    }
+    if (!Object.hasOwn(ds.filters, filter.field))
+        return true;
+    const definition = ds.filters[filter.field];
+    if (definition.operators && !definition.operators.includes(filter.operator))
+        return true;
+    const fieldType = ds.dimensions[definition.field ?? filter.field]?.fieldType;
+    return !!fieldType && validateFilterValue(filter, fieldType) !== null;
+}
+/**
+ * Errors for the call's RFC 0019 enforced constraints on `ds`. A constraint
+ * the dataset cannot enforce refuses the call, with a message that does not
+ * describe the constraint: it is the provider's policy, not the caller's
+ * input. `callerFilters` is the number of filters the caller supplied, which
+ * share the dataset's filter ceiling with the constraints.
+ */
+export function enforcedConstraintErrors(ds, context, callerFilters) {
+    const constraints = context?.runtime?.constraints;
+    if (constraints === undefined)
+        return [];
+    const unenforceable = [`Dataset "${ds.name}" cannot enforce a runtime constraint.`];
+    if (!Array.isArray(constraints) || constraints.length > MAX_ENFORCED_CONSTRAINTS)
+        return unenforceable;
+    if (constraints.length === 0)
+        return [];
+    const maxFilters = ds.limits?.maxFilters;
+    if (maxFilters && constraints.length > maxFilters)
+        return unenforceable;
+    if (constraints.some(constraint => constraintError(ds, constraint, context)))
+        return unenforceable;
+    if (maxFilters && callerFilters > maxFilters - constraints.length) {
+        return [`Too many filters: ${callerFilters} (max ${maxFilters - constraints.length} under the enforced constraints)`];
+    }
+    return [];
+}
+/** Throws when the call's constraints cannot all be enforced on `ds`. */
+export function assertEnforcedConstraints(ds, context) {
+    const [error] = enforcedConstraintErrors(ds, context, 0);
+    if (error)
+        throw new Error(error);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"metric-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/metric-derived-query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAoB,MAAM,8BAA8B,CAAC;AAS9F,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAUvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKrD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,cAAc,EAAE,uBAAuB,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAyHlB"}
+{"version":3,"file":"metric-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/metric-derived-query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAoB,MAAM,8BAA8B,CAAC;AAQ9F,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAMrD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,cAAc,EAAE,uBAAuB,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAmHlB"}

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

@@ -1,30 +1,29 @@
-import { datasetSourceBuilder } from './dataset-source.js';
+import { scopedDatasetSource } from './scoped-dataset-source.js';
 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 { assertRawSqlForDialect } from './raw-sql-dialect-check.js';
-import { applyAggregationSpec, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from '../query-planner.js';
+import { applyAggregationSpec, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, } from '../query-planner.js';
 import { queryTimeFilter } from './query-timezone.js';
 import { StatementParameters } from './statement-parameters.js';
 import { formulaExpressionSql } from './derived-measure-sql.js';
 import { isTenantScopedFilter } from './metric-handle.js';
-import { getRuntimeTenantPredicate } from './tenant-runtime.js';
-import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn, } from './relationship-builder-plan.js';
+import { buildRelationshipBuilderContext } 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';
+import { datasetOnTimeKey } from './dataset-time-keys.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);
     assertRawSqlForDialect(ref.dataset, dialect);
-    const ds = ref.dataset;
+    const ds = datasetOnTimeKey(ref.dataset, query.timeKey);
     const joinCtx = buildRelationshipBuilderContext(ds, query, context, dialect);
     // Build the CTE inner query using the builder
-    let cteBuilder = datasetSourceBuilder(builderFactory, ds);
-    cteBuilder = applyRelationshipJoins(cteBuilder, joinCtx);
+    let cteBuilder = scopedDatasetSource({ builderFactory, ds, context, joinCtx, dialect, timezone: query.timezone });
     const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain, joinCtx, query.timezone, dialect);
     if (selectParts.length > 0) {
         cteBuilder = cteBuilder.select(selectParts);
@@ -50,11 +49,6 @@ export function buildDerivedMetricSql(ref, spec, query, grain, builderFactory, c
         aggregateAliases.push(quoted);
     }
     // 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.`);

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

@@ -1,5 +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;
+export declare function buildMetricQueryBuilder(ref: MetricRef, spec: AggregationSpec, dataset: 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

@@ -1 +1 @@
-{"version":3,"file":"metric-query-builder.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-builder.ts"],"names":[],"mappings":"AAKA,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,CA6DlB"}
+{"version":3,"file":"metric-query-builder.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-builder.ts"],"names":[],"mappings":"AAKA,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;AAa9F,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvE,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,cAAc,EAAE,uBAAuB,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAsDlB"}

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

@@ -1,23 +1,23 @@
-import { datasetSourceBuilder } from './dataset-source.js';
+import { scopedDatasetSource } from './scoped-dataset-source.js';
 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 { assertRawSqlForDialect } from './raw-sql-dialect-check.js';
-import { applyAggregationSpec, appendOrderLimitOffset, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn, } from '../query-planner.js';
+import { applyAggregationSpec, appendOrderLimitOffset, buildDimensionSelectionPlan, resolveDimensionExpression, resolveFilterField, } from '../query-planner.js';
 import { queryTimeFilter } 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 { buildRelationshipBuilderContext } from './relationship-builder-plan.js';
 import { segmentFilters } from './segments.js';
-export function buildMetricQueryBuilder(ref, spec, ds, query, grain, builderFactory, context) {
+import { datasetOnTimeKey } from './dataset-time-keys.js';
+export function buildMetricQueryBuilder(ref, spec, dataset, query, grain, builderFactory, context) {
     const syntaxErrors = semanticQuerySyntaxErrors(query);
     if (syntaxErrors.length)
         throw new Error(syntaxErrors.join('; '));
+    const ds = datasetOnTimeKey(dataset, query.timeKey);
     const dialect = resolveDatasetSqlDialect(builderFactory);
     assertRawSqlForDialect(ds, dialect);
     const joinCtx = buildRelationshipBuilderContext(ds, query, context, dialect);
-    let qb = datasetSourceBuilder(builderFactory, ds);
-    qb = applyRelationshipJoins(qb, joinCtx);
+    let qb = scopedDatasetSource({ builderFactory, ds, context, joinCtx, dialect, timezone: query.timezone });
     const { selectParts, groupByParts } = buildDimensionSelectionPlan(ds, query.dimensions ?? [], grain, joinCtx, query.timezone, dialect);
     if (selectParts.length > 0) {
         qb = qb.select(selectParts);
@@ -28,12 +28,6 @@ export function buildMetricQueryBuilder(ref, spec, ds, query, grain, builderFact
         qb = qb.groupBy(groupByParts);
     }
     qb = applyAggregationSpec(qb, ds, spec, ref.name, joinCtx, dialect);
-    // 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)) {

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

@@ -1 +1 @@
-{"version":3,"file":"metric-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-validation.ts"],"names":[],"mappings":"AAEA,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,CAoIlB"}
+{"version":3,"file":"metric-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/metric-query-validation.ts"],"names":[],"mappings":"AAEA,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;AAQ3G,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAuIlB"}

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

@@ -9,10 +9,15 @@ 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';
+import { datasetOnTimeKey, selectedTimeKeyError } from './dataset-time-keys.js';
+import { enforcedConstraintErrors } from './enforced-constraints.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 timeKeyError = selectedTimeKeyError(ref.dataset, query.timeKey);
+    if (timeKeyError)
+        errors.push(timeKeyError);
+    const ds = timeKeyError ? ref.dataset : datasetOnTimeKey(ref.dataset, query.timeKey);
     const dimensionNames = Object.keys(ds.dimensions);
     const filterNames = Object.keys(ds.filters);
     const grain = getMetricGrain(metric, query);
@@ -29,6 +34,7 @@ export function validateMetricQueryInput(metric, query, context) {
     if (relationshipTenantError) {
         errors.push(relationshipTenantError);
     }
+    errors.push(...enforcedConstraintErrors(ds, context, query.filters?.length ?? 0));
     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}".`);
     }

package/dist/utils/portable-aggregations.d.ts

@@ -4,12 +4,15 @@
  * `approxCountDistinct` runs locally, but it is an expression extension 2 and
  * deployment contract 3 feature (RFC 0015). Publishing emits contract 2 until
  * it can emit contract 3, so it refuses the measure with an error naming it.
- * `merge` reads ClickHouse aggregate-state columns and has no contract form.
+ * `merge` is a deployment measure with its state function (RFC 0022), but the
+ * expression grammar has no merge aggregate, so a metric over one is refused.
  */
-import type { ProtocolAggregation } from '@hypequery/protocol';
+import type { ProtocolAggregation, ProtocolDatasetMeasure } from '@hypequery/protocol';
 import type { AggregationType } from '../types.js';
 type PortableAggregation = Exclude<ProtocolAggregation, 'approxCountDistinct'>;
-/** Returns `aggregation` when publishing can carry it; otherwise throws naming `owner`. */
+/** A dataset measure's aggregation as the contract carries it; otherwise throws naming `owner`. */
+export declare function requirePublishableMeasureAggregation(aggregation: AggregationType, owner: string): ProtocolDatasetMeasure['aggregation'];
+/** Returns `aggregation` when an expression can carry it; otherwise throws naming `owner`. */
 export declare function requirePortableAggregation(aggregation: AggregationType, owner: string): PortableAggregation;
 export {};
 //# sourceMappingURL=portable-aggregations.d.ts.map

package/dist/utils/portable-aggregations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"portable-aggregations.d.ts","sourceRoot":"","sources":["../../src/utils/portable-aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;AAE/E,2FAA2F;AAC3F,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAcrB"}
+{"version":3,"file":"portable-aggregations.d.ts","sourceRoot":"","sources":["../../src/utils/portable-aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;AAc/E,mGAAmG;AACnG,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,sBAAsB,CAAC,aAAa,CAAC,CAGvC;AAED,8FAA8F;AAC9F,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,eAAe,EAC5B,KAAK,EAAE,MAAM,GACZ,mBAAmB,CASrB"}

package/dist/utils/portable-aggregations.js

@@ -4,17 +4,26 @@
  * `approxCountDistinct` runs locally, but it is an expression extension 2 and
  * deployment contract 3 feature (RFC 0015). Publishing emits contract 2 until
  * it can emit contract 3, so it refuses the measure with an error naming it.
- * `merge` reads ClickHouse aggregate-state columns and has no contract form.
+ * `merge` is a deployment measure with its state function (RFC 0022), but the
+ * expression grammar has no merge aggregate, so a metric over one is refused.
  */
-/** Returns `aggregation` when publishing can carry it; otherwise throws naming `owner`. */
-export function requirePortableAggregation(aggregation, owner) {
-    if (aggregation === 'merge') {
-        throw new Error(`${owner} uses merge, which cannot be published: the deployment contract has no aggregate-state ` +
-            'measures. Use it for local queries only.');
-    }
+function refuseApproximate(aggregation, owner) {
     if (aggregation === 'approxCountDistinct') {
         throw new Error(`${owner} uses approxCountDistinct, which cannot be published yet: approximate aggregations ` +
             'need deployment contract 3 (RFC 0015). Use it for local queries, or publish countDistinct instead.');
     }
+}
+/** A dataset measure's aggregation as the contract carries it; otherwise throws naming `owner`. */
+export function requirePublishableMeasureAggregation(aggregation, owner) {
+    refuseApproximate(aggregation, owner);
+    return aggregation;
+}
+/** Returns `aggregation` when an expression can carry it; otherwise throws naming `owner`. */
+export function requirePortableAggregation(aggregation, owner) {
+    if (aggregation === 'merge') {
+        throw new Error(`${owner} uses merge, which a published metric cannot express: the expression grammar has no ` +
+            'aggregate-state merge. Publish the merge measure itself and query it, or use it for local queries only.');
+    }
+    refuseApproximate(aggregation, owner);
     return aggregation;
 }

package/dist/utils/query-timezone.d.ts

@@ -5,7 +5,7 @@ export declare function isQueryTimezone(value: unknown): value is string;
 export declare function queryTimezoneErrors(timezone: unknown): string[];
 /** Conversion preserves timestamp instants and interprets Date values as local dates. */
 export declare function queryTimeSql(dialect: DatasetSqlDialectRules, expression: string, timezone: string | undefined): string;
-/** True when a local filter field reads the dataset's time-key column. */
+/** True when a local filter field reads one of the dataset's time-axis columns. */
 export declare function isTimeKeyFilter(ds: AnyDatasetInstance, field: string): boolean;
 /** Apply the query zone to time-key predicates, including semantic filter aliases. */
 export declare function queryTimeFilterSql(dialect: DatasetSqlDialectRules, ds: AnyDatasetInstance, field: string, expression: string, timezone: string | undefined): string;

package/dist/utils/query-timezone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-timezone.d.ts","sourceRoot":"","sources":["../../src/utils/query-timezone.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAK1F,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAS/D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAG/D;AASD,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEtH;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAM9E;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,EAC/B,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GACtF,MAAM,CAER;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,EAC/B,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,GAAE,sBAA2B,GACnC,kBAAkB,EAAE,CAwCtB"}
+{"version":3,"file":"query-timezone.d.ts","sourceRoot":"","sources":["../../src/utils/query-timezone.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAM1F,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAS/D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAG/D;AASD,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEtH;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAK9E;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,EAC/B,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GACtF,MAAM,CAER;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,EAC/B,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,GAAE,sBAA2B,GACnC,kBAAkB,EAAE,CAwCtB"}

package/dist/utils/query-timezone.js

@@ -1,6 +1,7 @@
 import { resolveDimensionFieldType, resolveFilterFieldType } from './filter-field-type.js';
 import { instantWallClock, parseTimestampInstant } from './timestamp-instants.js';
 import { mixedInstantListError } from '../validation.js';
+import { datasetTimeKeys } from './dataset-time-keys.js';
 /** Named zones only: reject fixed offsets, invalid zones, and SQL fragments. */
 export function isQueryTimezone(value) {
     if (typeof value !== 'string' || value.length > 100
@@ -29,14 +30,13 @@ function canonicalTimezone(timezone) {
 export function queryTimeSql(dialect, expression, timezone) {
     return dialect.toQueryTimezone(expression, canonicalTimezone(timezone));
 }
-/** True when a local filter field reads the dataset's time-key column. */
+/** True when a local filter field reads one of the dataset's time-axis columns. */
 export function isTimeKeyFilter(ds, field) {
     if (!ds.timeKey || field.includes('.'))
         return false;
     const resolved = ds.filters[field]?.field ?? field;
     const column = ds.dimensions[resolved]?.column ?? resolved;
-    const timeColumn = ds.dimensions[ds.timeKey]?.column ?? ds.timeKey;
-    return column === timeColumn;
+    return datasetTimeKeys(ds).some(timeKey => (ds.dimensions[timeKey]?.column ?? timeKey) === column);
 }
 /** Apply the query zone to time-key predicates, including semantic filter aliases. */
 export function queryTimeFilterSql(dialect, ds, field, expression, timezone) {

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

@@ -19,7 +19,7 @@ import type { DatasetSqlDialectRules } from '../dataset-sql-dialect.js';
  */
 import type { AnyDatasetInstance, DatasetQuery, ExecutionContext, MetricQuery } from '../types.js';
 import type { QueryBuilderLike } from '../query-builder-protocol.js';
-import { type TenantPredicate } from './tenant-runtime.js';
+import { type RowScopePredicate } from './row-scope.js';
 export interface ResolvedBuilderJoin {
     /** Relationship name, used as the joined table's SQL alias. */
     relationship: string;
@@ -32,10 +32,10 @@ export interface ResolvedBuilderJoin {
     from: string;
     /** Target join column (unqualified). */
     to: string;
-    /** Tenant predicate applied to the joined target, when active. */
-    tenant?: TenantPredicate & {
-        field: string;
-    };
+    /** The target's own row scope (RFC 0020), applied in the join condition. */
+    scope: RowScopePredicate[];
+    /** The target is read with `FINAL` (RFC 0021), so the query needs the PREWHERE pin. */
+    final: boolean;
 }
 export interface RelationshipBuilderContext {
     baseSource: string;
@@ -46,9 +46,10 @@ export interface RelationshipBuilderContext {
 }
 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.
+ * Builds the join context for a query, or returns undefined when neither the
+ * query nor the call's enforced constraints reference a relationship-qualified
+ * field. 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, dialect?: DatasetSqlDialectRules): RelationshipBuilderContext | undefined;
 /** Qualifies a base physical column with the base source when joins are active. */
@@ -68,8 +69,9 @@ export declare function qualifyBaseColumn(ctx: RelationshipBuilderContext | unde
 export declare function resolveQualifiedExpression(ds: AnyDatasetInstance, name: string, ctx: RelationshipBuilderContext): string;
 /**
  * Applies each relationship join to the builder as a single-match LEFT JOIN
- * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`) and, when runtime tenancy
- * is active on a target, scopes the joined rows with the tenant predicate.
+ * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`), scoping the joined rows
+ * with the target's own row scope: an out-of-scope target row behaves exactly
+ * like a missing one.
  *
  * A builder without `leftAnyJoin` is refused rather than downgraded to a plain
  * `leftJoin`: duplicate target keys would fan out base rows and silently

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,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGxE;;;;;;;;;;;;;;;;GAgBG;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,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,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;IACrD,oEAAoE;IACpE,OAAO,EAAE,sBAAsB,CAAC;CACjC;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,sBAAoD,GAC5D,0BAA0B,GAAG,SAAS,CAgDxC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,0BAA0B,GAAG,SAAS,EAC3C,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,0BAA0B,GAC9B,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAoClB"}
+{"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,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGxE;;;;;;;;;;;;;;;;GAgBG;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,EAAuC,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAG7F,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,uFAAuF;IACvF,KAAK,EAAE,OAAO,CAAC;CAChB;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;IACrD,oEAAoE;IACpE,OAAO,EAAE,sBAAsB,CAAC;CACjC;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;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,gBAAgB,EAC1B,OAAO,GAAE,sBAAoD,GAC5D,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;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,0BAA0B,GAC9B,MAAM,CAaR;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,GAAG,EAAE,0BAA0B,GAAG,SAAS,GAC1C,gBAAgB,CAoClB"}

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

@@ -2,12 +2,13 @@ import { relationshipKeys } from './relationship-keys.js';
 import { relationshipJoinSource } 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 { datasetRowScope, runtimeConstraints } from './row-scope.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.
+ * Builds the join context for a query, or returns undefined when neither the
+ * query nor the call's enforced constraints reference a relationship-qualified
+ * field. Validation runs first, so any qualified name that fails to resolve
+ * here is skipped defensively.
  */
 export function buildRelationshipBuilderContext(ds, query, context, dialect = clickhouseDatasetSqlDialect) {
     const referenced = [
@@ -15,11 +16,11 @@ export function buildRelationshipBuilderContext(ds, query, context, dialect = cl
         ...(query.measures ?? []),
         ...(query.filters ?? []).map((filter) => filter.field),
         ...(query.orderBy ?? []).map((order) => order.field),
+        ...runtimeConstraints(context).map((constraint) => constraint.field),
     ].filter(isQualifiedField);
     if (referenced.length === 0) {
         return undefined;
     }
-    const tenantPredicate = getRuntimeTenantPredicate(context);
     const joinByRelationship = new Map();
     for (const name of referenced) {
         const resolution = resolveRelationshipReference(ds, name, query.measures);
@@ -42,9 +43,8 @@ export function buildRelationshipBuilderContext(ds, query, context, dialect = cl
             from: relationship.from,
             to: relationship.to,
             keys,
-            tenant: tenantPredicate && target.tenantKey
-                ? { field: target.tenantKey, ...tenantPredicate }
-                : undefined,
+            scope: datasetRowScope(target, context),
+            final: Boolean(target.rowResolution),
         });
     }
     return {
@@ -86,8 +86,9 @@ export function resolveQualifiedExpression(ds, name, ctx) {
 }
 /**
  * Applies each relationship join to the builder as a single-match LEFT JOIN
- * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`) and, when runtime tenancy
- * is active on a target, scopes the joined rows with the tenant predicate.
+ * (`leftAnyJoin`, e.g. ClickHouse `LEFT ANY JOIN`), scoping the joined rows
+ * with the target's own row scope: an out-of-scope target row behaves exactly
+ * like a missing one.
  *
  * A builder without `leftAnyJoin` is refused rather than downgraded to a plain
  * `leftJoin`: duplicate target keys would fan out base rows and silently
@@ -104,20 +105,20 @@ export function applyRelationshipJoins(qb, ctx) {
                 'would fan out duplicate target keys and inflate aggregates, so relationship-qualified fields ' +
                 'are unavailable with this builder.');
         }
-        const tenant = join.tenant
-            ? {
-                column: `${join.relationship}.${join.tenant.field}`,
-                operator: join.tenant.operator,
-                value: join.tenant.value,
-            }
-            : undefined;
+        const conditions = join.scope.map(predicate => ({
+            column: `${join.relationship}.${predicate.column}`,
+            operator: predicate.operator,
+            value: predicate.value,
+        }));
+        // A single condition keeps the object form older builders accept.
+        const scope = conditions.length > 1 ? conditions : conditions[0];
         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);
+            qb = qb.leftAnyJoin(join.source, [pairs[0], ...pairs.slice(1)], join.relationship, scope);
             continue;
         }
-        qb = qb.leftAnyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, tenant);
+        qb = qb.leftAnyJoin(join.source, `${ctx.baseSource}.${join.from}`, `${join.relationship}.${join.to}`, join.relationship, scope);
     }
     return qb;
 }

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,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,sBAAsB;;;EAkBlJ;AAeD,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,EAAE,OAAO,EAAE,sBAAsB;;;;EAexJ"}
+{"version":3,"file":"relationship-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,aAAa,CAAC;AAEvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAIjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,sBAAsB;;;EAoBlJ;AAeD,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,EAAE,OAAO,EAAE,sBAAsB;;;;EAexJ"}

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

@@ -1,3 +1,4 @@
+import { currentRowPredicate } from './dataset-source.js';
 import { resolveRelationshipMeasure } from './relationship-measures.js';
 import { resolveDimensionExpression } from '../query-planner.js';
 import { measureToAggregationSpec } from './dataset-normalization.js';
@@ -35,15 +36,17 @@ export function relationshipJoinSource(target, to, names, dialect) {
     // Sorted so the SQL is byte-identical however the target's dimensions are
     // ordered (authored vs. rehydrated catalogs declare them differently).
     const projection = [...columns].sort().map(quote);
-    return { source: `(SELECT ${[...projection, `${dialect.toNullable('1')} AS ${quote(marker)}`].join(', ')} FROM ${source})`, marker };
+    const current = currentRowPredicate(target);
+    const where = current ? ` WHERE ${quote(current.column)} = ${current.value}` : '';
+    return { source: `(SELECT ${[...projection, `${dialect.toNullable('1')} AS ${quote(marker)}`].join(', ')} FROM ${source}${where})`, marker };
 }
 /** The target's quoted table, read with `FINAL` when the target dataset requires it. */
 function relationshipTargetTable(target, dialect) {
     const quoted = dialect.quoteQualifiedName(target.source);
-    if (!target.final)
+    if (!target.rowResolution)
         return quoted;
     if (!dialect.finalTable) {
-        throw new Error(`Dataset "${target.name}" is declared final: true, but the "${dialect.name}" SQL dialect has no FINAL ` +
+        throw new Error(`Dataset "${target.name}" reads its source with FINAL, but the "${dialect.name}" SQL dialect has no FINAL ` +
             'modifier, so it cannot be joined without counting unmerged row versions.');
     }
     return dialect.finalTable(quoted);

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

@@ -1 +1 @@
-{"version":3,"file":"relationship-validation.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-validation.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAWrB,KAAK,iBAAiB,GAAG,IAAI,CAC3B,YAAY,GAAG,WAAW,EAC1B,YAAY,GAAG,SAAS,GAAG,SAAS,CACrC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAoBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,IAAI,CA4Bf"}
+{"version":3,"file":"relationship-validation.d.ts","sourceRoot":"","sources":["../../src/utils/relationship-validation.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAYrB,KAAK,iBAAiB,GAAG,IAAI,CAC3B,YAAY,GAAG,WAAW,EAC1B,YAAY,GAAG,SAAS,GAAG,SAAS,CACrC,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAqBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,kBAAkB,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,IAAI,CA4Bf"}

package/dist/utils/relationship-validation.js

@@ -1,6 +1,7 @@
 import { resolveRelationshipReference } from './relationship-measures.js';
 import { validateFilterValue } from '../validation.js';
 import { getRuntimeTenantPredicate, hasTenantRuntime, } from './tenant-runtime.js';
+import { runtimeConstraints } from './row-scope.js';
 import { isQualifiedField, resolveQualifiedField, } from './relationship-fields.js';
 /**
  * Tenant-less base datasets may still reach tenant-scoped data through a
@@ -16,6 +17,7 @@ export function validateRelationshipTenantRuntime(ds, query, context) {
         ...(query.measures ?? []),
         ...(query.filters ?? []).map((filter) => filter.field),
         ...(query.orderBy ?? []).map((order) => order.field),
+        ...runtimeConstraints(context).map((constraint) => constraint.field),
     ].filter(isQualifiedField);
     for (const name of referenced) {
         const resolution = resolveRelationshipReference(ds, name, query.measures);

package/dist/utils/row-scope.d.ts

@@ -0,0 +1,23 @@
+import type { AnyDatasetInstance, ExecutionContext, MetricFilter } from '../types.js';
+import type { QueryBuilderLike } from '../query-builder-protocol.js';
+import { type TenantPredicate } from './tenant-runtime.js';
+/** A trusted predicate on one of a dataset's own physical columns. */
+export type RowScopePredicate = TenantPredicate & {
+    readonly column: string;
+};
+/**
+ * The trusted predicates restricting which source rows of `ds` any query may
+ * read (RFC 0020). They apply to the queried dataset and to every joined
+ * relationship target alike. `tenantKey` with a runtime tenant lowers to one
+ * predicate; the trusted cross-tenant scope (`scope: 'all'`) lowers to none.
+ */
+export declare function datasetRowScope(ds: Pick<AnyDatasetInstance, 'tenantKey'>, context?: ExecutionContext): RowScopePredicate[];
+/**
+ * The call's RFC 0019 enforced constraints, from trusted context only. They
+ * apply to the queried dataset, in its filter vocabulary, never to joined
+ * targets.
+ */
+export declare function runtimeConstraints(context?: ExecutionContext): readonly MetricFilter[];
+/** ANDs each row-scope predicate onto `qb`, with columns qualified by `qualify`. */
+export declare function applyRowScope(qb: QueryBuilderLike, scope: readonly RowScopePredicate[], qualify?: (column: string) => string): QueryBuilderLike;
+//# sourceMappingURL=row-scope.d.ts.map