@hypequery/datasets 0.8.0 → 0.10.0

package/dist/in-memory-backend.js

@@ -44,6 +44,40 @@ function applyTenant(rows, tenant) {
     }
     return rows.filter((row) => row[tenant.field] === tenant.value);
 }
+/**
+ * Enriches base rows with columns from to-one joined targets, keyed by the
+ * qualified name `<relationship>.<column>`. Mirrors a query-time LEFT JOIN:
+ * base rows without a matching target keep the joined columns undefined.
+ */
+function applyJoins(rows, joins, tables) {
+    if (!joins || joins.length === 0) {
+        return rows;
+    }
+    const indexes = joins.map((join) => {
+        const targetRows = applyTenant(tables[join.source] ?? [], join.tenant);
+        const index = new Map();
+        for (const row of targetRows) {
+            const key = String(row[join.to]);
+            // To-one: first matching target wins; a mis-declared to-many still won't fan out.
+            if (!index.has(key)) {
+                index.set(key, row);
+            }
+        }
+        return { join, index };
+    });
+    return rows.map((row) => {
+        const enriched = { ...row };
+        for (const { join, index } of indexes) {
+            const match = index.get(String(row[join.from]));
+            if (match) {
+                for (const [column, value] of Object.entries(match)) {
+                    enriched[`${join.relationship}.${column}`] = value;
+                }
+            }
+        }
+        return enriched;
+    });
+}
 function periodForValue(value, grain) {
     const date = new Date(String(value));
     if (Number.isNaN(date.getTime())) {
@@ -75,9 +109,63 @@ function groupKey(row, plan) {
     }
     return JSON.stringify(parts);
 }
+/**
+ * Percentile by linear interpolation over sorted values. Approximate parity
+ * with ClickHouse's sampling-based `quantile`; exact only for clean inputs.
+ */
+function percentileOf(values, level) {
+    if (values.length === 0) {
+        // ClickHouse `quantile` over an empty set yields nan.
+        return Number.NaN;
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const position = (sorted.length - 1) * level;
+    const lower = Math.floor(position);
+    const upper = Math.ceil(position);
+    if (lower === upper) {
+        return sorted[lower];
+    }
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+/**
+ * Sample variance. Fewer than two values yields NaN, as in ClickHouse:
+ * `varSamp`/`stddevSamp` divide by n - 1, so a single row gives nan.
+ */
+function sampleVarianceOf(values) {
+    if (values.length < 2) {
+        return Number.NaN;
+    }
+    const mean = values.reduce((total, value) => total + value, 0) / values.length;
+    const squaredDeviations = values.reduce((total, value) => total + (value - mean) ** 2, 0);
+    return squaredDeviations / (values.length - 1);
+}
+/** Value of `field` on the row where `argField` is most extreme; empty → null. */
+function argExtremeOf(rows, field, argField, extreme) {
+    let best;
+    for (const row of rows) {
+        // ClickHouse argMax/argMin skip rows where either the value being
+        // returned or the ordering value is NULL ("both `arg` and `val` behave
+        // as aggregate functions, they both skip NULL"). Verified against
+        // ClickHouse 25.1: argMax(amount, created_at) over
+        // [(NULL, '2024-01-05'), (10, '2024-01-01')] returns 10, not NULL.
+        if (row[argField] == null || row[field] == null) {
+            continue;
+        }
+        if (best === undefined
+            || (extreme === 'max' ? row[argField] > best[argField] : row[argField] < best[argField])) {
+            best = row;
+        }
+    }
+    return best?.[field] ?? null;
+}
 function aggregateRows(rows, aggregation) {
+    if ((aggregation.aggregation === 'argMax' || aggregation.aggregation === 'argMin')
+        && aggregation.filters?.length) {
+        throw new Error(`Measure filters are not supported on ${aggregation.aggregation} aggregations.`);
+    }
     const filteredRows = applyFilters(rows, aggregation.filters ?? []);
     const values = filteredRows.map((row) => row[aggregation.field]);
+    const numericValues = () => values.filter((value) => value != null).map((value) => Number(value));
     switch (aggregation.aggregation) {
         case 'sum':
             return values.reduce((total, value) => total + Number(value ?? 0), 0);
@@ -93,6 +181,23 @@ function aggregateRows(rows, aggregation) {
             return Math.min(...values.map((value) => Number(value)));
         case 'max':
             return Math.max(...values.map((value) => Number(value)));
+        case 'argMax':
+        case 'argMin': {
+            if (!aggregation.argField) {
+                throw new Error(`Aggregation "${aggregation.aggregation}" for "${aggregation.name}" requires an argField.`);
+            }
+            return argExtremeOf(filteredRows, aggregation.field, aggregation.argField, aggregation.aggregation === 'argMax' ? 'max' : 'min');
+        }
+        case 'percentile': {
+            if (aggregation.level == null) {
+                throw new Error(`Aggregation "percentile" for "${aggregation.name}" requires a level.`);
+            }
+            return percentileOf(numericValues(), aggregation.level);
+        }
+        case 'stddev':
+            return Math.sqrt(sampleVarianceOf(numericValues()));
+        case 'variance':
+            return sampleVarianceOf(numericValues());
         default:
             return 0;
     }
@@ -175,17 +280,28 @@ function serializeMeasures(rows, measures) {
     return rows.map((row) => {
         const next = { ...row };
         for (const name of measures) {
-            if (next[name] != null) {
+            if (typeof next[name] === 'number' && !Number.isFinite(next[name])) {
+                // ClickHouse JSON output serializes nan/inf as null
+                // (output_format_json_quote_denormals defaults to 0).
+                next[name] = null;
+            }
+            else if (next[name] != null) {
                 next[name] = String(next[name]);
             }
         }
         return next;
     });
 }
+/**
+ * @deprecated The plan/backend execution path is frozen (bug fixes only); this
+ * backend remains as the test harness for that path. New code should use
+ * `createDatasetClient({ queryBuilder })`.
+ */
 export function createInMemoryBackend(tables) {
     function executeAggregate(plan) {
         const table = tables[plan.source] ?? [];
-        const filteredRows = applyFilters(applyTenant(table, plan.tenant), plan.filters);
+        const joinedRows = applyJoins(table, plan.joins, tables);
+        const filteredRows = applyFilters(applyTenant(joinedRows, plan.tenant), plan.filters);
         const groups = new Map();
         for (const row of filteredRows) {
             const key = groupKey(row, plan);

package/dist/index.d.ts

@@ -2,11 +2,12 @@ export { dataset } from './dataset.js';
 export { dimension } from './field.js';
 export { measure } from './measure.js';
 export { belongsTo, hasMany, hasOne } from './relationships.js';
-export { sum, count, countDistinct, avg, min, max } from './aggregations.js';
+export { sum, count, countDistinct, avg, min, max, percentile, median, argMax, argMin, stddev, variance } from './aggregations.js';
 export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, } from './formulas.js';
 export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, } from './query-helpers.js';
 export { createDatasetRegistry } from './registry.js';
-export { getDatasetCatalog, getDatasetCatalogs } from './catalog.js';
+export { getDatasetCatalog, getDatasetCatalogs, getQueryableRelationshipFields } from './catalog.js';
+export { listQueryableRelationshipFields } from './utils/relationship-fields.js';
 export type { DatasetCatalog, DatasetCatalogMap, DatasetCatalogSource, DimensionCatalogEntry, MeasureCatalogEntry, MetricCatalogEntry, FilterCatalogEntry, RelationshipCatalogEntry, } from './catalog.js';
 export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC_CONTRACT_VERSION, } from './contract.js';
 export type { SemanticContract, SerializeSemanticContractOptions, ContractDataset, ContractDimension, ContractMeasure, ContractMetric, ContractFilter, ContractRelationship, } from './contract.js';
@@ -26,5 +27,5 @@ export type { QueryBuilderLike, QueryBuilderFactoryLike, QueryBuilderFactoryComp
 export { toQueryBuilderFactory } from './query-builder-protocol.js';
 export { validateSQLIdentifier, isSafeSQLIdentifier, quoteSQLIdentifier } from './sql-utils.js';
 export { GRAIN_FUNCTIONS, SEMANTIC_FILTER_OPERATORS, SUPPORTED_TIME_GRAINS } from './constants.js';
-export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetLimits, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';
+export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetLimits, DatasetInstance, AnyDatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, DatasetDimensionNames, DatasetQueryableDimensions, DatasetMeasureNames, DatasetOrderableNames, DatasetQueryFor, DatasetRow, DatasetRowFor, DatasetQueryResultFor, MetricQueryFor, MetricRow, MetricRowFor, MetricResultFor, KnownStringKeys, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -7,7 +7,7 @@ export { measure } from './measure.js';
 // Relationship helpers
 export { belongsTo, hasMany, hasOne } from './relationships.js';
 // Aggregation helpers
-export { sum, count, countDistinct, avg, min, max } from './aggregations.js';
+export { sum, count, countDistinct, avg, min, max, percentile, median, argMax, argMin, stddev, variance } from './aggregations.js';
 // Formula helpers
 export { divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, } from './formulas.js';
 // Semantic query helpers
@@ -15,7 +15,8 @@ export { eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc,
 // Registry
 export { createDatasetRegistry } from './registry.js';
 // Catalog
-export { getDatasetCatalog, getDatasetCatalogs } from './catalog.js';
+export { getDatasetCatalog, getDatasetCatalogs, getQueryableRelationshipFields } from './catalog.js';
+export { listQueryableRelationshipFields } from './utils/relationship-fields.js';
 // Semantic contract (stable, hashable export for snapshots/diffs/validation)
 export { serializeSemanticContract, contractToStableJson, hashContract, SEMANTIC_CONTRACT_VERSION, } from './contract.js';
 // Agent/tool metadata
@@ -25,6 +26,9 @@ export { createDatasetClient } from './executor.js';
 // Semantic query result cache
 export { createMemoryCacheStore } from './cache/semantic-query-cache.js';
 export { buildDatasetQuerySignature, buildMetricQuerySignature, } from './cache/query-signature.js';
+// Plan/backend protocol — FROZEN. Deprecated in favor of the query-builder
+// path (`createDatasetClient({ queryBuilder })`); bug fixes only, no new
+// features. See the deprecation notes on each declaration.
 export { createInMemoryBackend } from './in-memory-backend.js';
 export { validateFilterValue, matchesFieldType } from './validation.js';
 export { toQueryBuilderFactory } from './query-builder-protocol.js';

package/dist/measure.d.ts

@@ -1,4 +1,6 @@
 import type { MeasureDefinition, MeasureOptions } from './types.js';
+export declare function validatePercentileLevel(level: number): void;
+declare function createPercentileMeasure(field: string, level: number, opts?: MeasureOptions): MeasureDefinition;
 export declare const measure: {
     readonly sum: (field: string, opts?: MeasureOptions) => MeasureDefinition;
     readonly count: (field: string, opts?: MeasureOptions) => MeasureDefinition;
@@ -6,5 +8,23 @@ export declare const measure: {
     readonly avg: (field: string, opts?: MeasureOptions) => MeasureDefinition;
     readonly min: (field: string, opts?: MeasureOptions) => MeasureDefinition;
     readonly max: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    /** Approximate percentile of a numeric field (ClickHouse `quantile(level)`). */
+    readonly percentile: typeof createPercentileMeasure;
+    /** Median — sugar for `percentile(field, 0.5)`. */
+    readonly median: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    /**
+     * Value of `field` on the row where `by` is greatest (ClickHouse `argMax`).
+     * The runtime value follows `field`'s type; aggregate result columns are
+     * exposed as strings to match the dataset result contract.
+     * Measure filters are not supported on argMax/argMin.
+     */
+    readonly argMax: (field: string, by: string, opts?: Omit<MeasureOptions, "filters">) => MeasureDefinition;
+    /** Value of `field` on the row where `by` is smallest (ClickHouse `argMin`). */
+    readonly argMin: (field: string, by: string, opts?: Omit<MeasureOptions, "filters">) => MeasureDefinition;
+    /** Sample standard deviation (ClickHouse `stddevSamp`). */
+    readonly stddev: (field: string, opts?: MeasureOptions) => MeasureDefinition;
+    /** Sample variance (ClickHouse `varSamp`). */
+    readonly variance: (field: string, opts?: MeasureOptions) => MeasureDefinition;
 };
+export {};
 //# sourceMappingURL=measure.d.ts.map

package/dist/measure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAcxF,eAAO,MAAM,OAAO;0BAXH,MAAM,SAAS,cAAc,KAAG,iBAAiB;4BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;oCAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;CAkBxD,CAAC"}
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../src/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAsB,MAAM,YAAY,CAAC;AAcxF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI3D;AAmBD,iBAAS,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,iBAAiB,CAYvG;AAED,eAAO,MAAM,OAAO;0BAhDH,MAAM,SAAS,cAAc,KAAG,iBAAiB;4BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;oCAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;0BAAjD,MAAM,SAAS,cAAc,KAAG,iBAAiB;IAuDhE,gFAAgF;;IAEhF,mDAAmD;6BACnC,MAAM,SAAS,cAAc,KAAG,iBAAiB;IAEjE;;;;;OAKG;6BA/CY,MAAM,MAAM,MAAM,SAAS,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,KAAG,iBAAiB;IAiD7F,gFAAgF;6BAjDjE,MAAM,MAAM,MAAM,SAAS,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,KAAG,iBAAiB;IAmD7F,2DAA2D;6BArE5C,MAAM,SAAS,cAAc,KAAG,iBAAiB;IAuEhE,8CAA8C;+BAvE/B,MAAM,SAAS,cAAc,KAAG,iBAAiB;CAyExD,CAAC"}

package/dist/measure.js

@@ -9,6 +9,40 @@ function createMeasureHelper(aggregation) {
         filters: opts?.filters,
     });
 }
+export function validatePercentileLevel(level) {
+    if (typeof level !== 'number' || !Number.isFinite(level) || level < 0 || level > 1) {
+        throw new Error(`Invalid percentile level ${level}: expected a number between 0 and 1.`);
+    }
+}
+function createArgMeasureHelper(aggregation) {
+    return (field, by, opts) => {
+        if (typeof by !== 'string' || by.trim().length === 0) {
+            throw new Error(`measure.${aggregation}("${field}", by) requires a "by" field.`);
+        }
+        return {
+            __type: 'measure_definition',
+            aggregation,
+            field,
+            argField: by,
+            sql: opts?.sql,
+            label: opts?.label,
+            description: opts?.description,
+        };
+    };
+}
+function createPercentileMeasure(field, level, opts) {
+    validatePercentileLevel(level);
+    return {
+        __type: 'measure_definition',
+        aggregation: 'percentile',
+        field,
+        level,
+        sql: opts?.sql,
+        label: opts?.label,
+        description: opts?.description,
+        filters: opts?.filters,
+    };
+}
 export const measure = {
     sum: createMeasureHelper('sum'),
     count: createMeasureHelper('count'),
@@ -16,4 +50,21 @@ export const measure = {
     avg: createMeasureHelper('avg'),
     min: createMeasureHelper('min'),
     max: createMeasureHelper('max'),
+    /** Approximate percentile of a numeric field (ClickHouse `quantile(level)`). */
+    percentile: createPercentileMeasure,
+    /** Median — sugar for `percentile(field, 0.5)`. */
+    median: (field, opts) => createPercentileMeasure(field, 0.5, opts),
+    /**
+     * Value of `field` on the row where `by` is greatest (ClickHouse `argMax`).
+     * The runtime value follows `field`'s type; aggregate result columns are
+     * exposed as strings to match the dataset result contract.
+     * Measure filters are not supported on argMax/argMin.
+     */
+    argMax: createArgMeasureHelper('argMax'),
+    /** Value of `field` on the row where `by` is smallest (ClickHouse `argMin`). */
+    argMin: createArgMeasureHelper('argMin'),
+    /** Sample standard deviation (ClickHouse `stddevSamp`). */
+    stddev: createMeasureHelper('stddev'),
+    /** Sample variance (ClickHouse `varSamp`). */
+    variance: createMeasureHelper('variance'),
 };

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

@@ -17,7 +17,24 @@ export interface QueryBuilderLike {
     avg(column: string, alias?: string): QueryBuilderLike;
     min(column: string, alias?: string): QueryBuilderLike;
     max(column: string, alias?: string): QueryBuilderLike;
+    /** Value of `column` on the row where `argColumn` is greatest. */
+    argMax?(column: string, argColumn: string, alias?: string): QueryBuilderLike;
+    /** Value of `column` on the row where `argColumn` is smallest. */
+    argMin?(column: string, argColumn: string, alias?: string): QueryBuilderLike;
+    /** Approximate percentile of `column` at `level` in [0, 1]. */
+    quantile?(column: string, level: number, alias?: string): QueryBuilderLike;
+    /** Sample standard deviation of `column`. */
+    stddev?(column: string, alias?: string): QueryBuilderLike;
+    /** Sample variance of `column`. */
+    variance?(column: string, alias?: string): QueryBuilderLike;
     where(column: string, operator: string, value: unknown): QueryBuilderLike;
+    leftJoin(table: string, leftColumn: string, rightColumn: string, alias?: string, on?: QueryBuilderJoinCondition | QueryBuilderJoinCondition[]): QueryBuilderLike;
+    /**
+     * Optional single-match LEFT JOIN (ClickHouse `LEFT ANY JOIN`). When a
+     * builder provides it, relationship joins use it so duplicate target join
+     * keys cannot fan out aggregates; otherwise `leftJoin` is used.
+     */
+    leftAnyJoin?(table: string, leftColumn: string, rightColumn: string, alias?: string, on?: QueryBuilderJoinCondition | QueryBuilderJoinCondition[]): QueryBuilderLike;
     groupBy(columns: string | string[]): QueryBuilderLike;
     orderBy(column: string, direction?: 'ASC' | 'DESC'): QueryBuilderLike;
     limit(count: number): QueryBuilderLike;
@@ -28,6 +45,11 @@ export interface QueryBuilderLike {
     };
     execute<T = Record<string, unknown>>(): Promise<T[]>;
 }
+export interface QueryBuilderJoinCondition {
+    column: string;
+    operator: string;
+    value: unknown;
+}
 /** A query builder factory (what `createQueryBuilder(config)` returns). */
 export interface QueryBuilderFactoryLike {
     table(name: string): QueryBuilderLike;

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

@@ -1 +1 @@
-{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAGrD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACxD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAChE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGtD,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAG1E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,gBAAgB,CAAC;IAGtD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,gBAAgB,CAAC;IACtE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAGxC,eAAe,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC1D,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtD;AAED,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACtF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,iEAAiE;AACjE,MAAM,MAAM,wBAAwB,GAChC,uBAAuB,GACvB,6BAA6B,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAEzB"}
+{"version":3,"file":"query-builder-protocol.d.ts","sourceRoot":"","sources":["../src/query-builder-protocol.ts"],"names":[],"mappings":"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"}

package/dist/query-planner.d.ts

@@ -1,15 +1,16 @@
 import type { AggregationSpec, AnyDatasetInstance, ExecutionContext, MeasureDefinition, MetricOrderBy, TimeGrain } from "./types.js";
 import type { QueryBuilderLike } from "./query-builder-protocol.js";
+import { type RelationshipBuilderContext } from './utils/relationship-builder-plan.js';
 type DatasetShape = AnyDatasetInstance;
-export declare function resolveDimensionExpression(ds: DatasetShape, dimensionName: string): string;
-export declare function resolveFilterField(ds: DatasetShape, filterField: string): string;
-export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined): {
+export declare function resolveDimensionExpression(ds: DatasetShape, dimensionName: string, joinCtx?: RelationshipBuilderContext): string;
+export declare function resolveFilterField(ds: DatasetShape, filterField: string, joinCtx?: RelationshipBuilderContext): string;
+export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined, joinCtx?: RelationshipBuilderContext): {
     selectParts: string[];
     groupByParts: string[];
 };
-export declare function applyAggregationSpec(qb: QueryBuilderLike, ds: DatasetShape, spec: AggregationSpec, alias: string): QueryBuilderLike;
-export declare function applyMeasureDefinition(qb: QueryBuilderLike, ds: DatasetShape, name: string, definition: MeasureDefinition): QueryBuilderLike;
-export declare function appendOrderLimitOffset(qb: QueryBuilderLike, orderBy: MetricOrderBy[] | undefined, grain: TimeGrain | undefined, limit?: number, offset?: number): QueryBuilderLike;
+export declare function applyAggregationSpec(qb: QueryBuilderLike, ds: DatasetShape, spec: AggregationSpec, alias: string, joinCtx?: RelationshipBuilderContext): QueryBuilderLike;
+export declare function applyMeasureDefinition(qb: QueryBuilderLike, ds: DatasetShape, name: string, definition: MeasureDefinition, joinCtx?: RelationshipBuilderContext): QueryBuilderLike;
+export declare function appendOrderLimitOffset(qb: QueryBuilderLike, orderBy: MetricOrderBy[] | undefined, grain: TimeGrain | undefined, limit?: number, offset?: number, joinCtx?: RelationshipBuilderContext): QueryBuilderLike;
 export declare function resolveTenantFilterColumn(ds: DatasetShape, context?: ExecutionContext): string | undefined;
 export {};
 //# sourceMappingURL=query-planner.d.ts.map

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

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

package/dist/query-planner.js

@@ -1,18 +1,48 @@
 import { GRAIN_FUNCTIONS } from "./constants.js";
 import { applyFilteredAggregationExpression } from './utils/filtered-aggregation-sql.js';
 import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
+import { quoteSQLIdentifier } from './sql-utils.js';
+import { isQualifiedField } from './utils/relationship-fields.js';
+import { qualifyBaseColumn, resolveQualifiedColumn, } from './utils/relationship-builder-plan.js';
+import { measureToAggregationSpec } from './utils/dataset-normalization.js';
+import { validatePercentileLevel } from './measure.js';
 function toOrderDirection(direction) {
     return direction === 'asc' ? 'ASC' : 'DESC';
 }
-export function resolveDimensionExpression(ds, dimensionName) {
+/**
+ * Raw SQL expressions on the base dataset are emitted verbatim, so their column
+ * references are not table-qualified. When relationship joins are active a bare
+ * `price` in such an expression is ambiguous if the joined table also has a
+ * `price` column. Until the builder rewrites identifiers inside expressions,
+ * reject the combination rather than emit ambiguous SQL.
+ */
+function assertNoRawSqlUnderJoins(kind, name, sql, joinCtx) {
+    if (!joinCtx) {
+        return;
+    }
+    throw new Error(`SQL-backed ${kind} "${name}" cannot be combined with relationship joins: its expression ` +
+        `("${sql}") is not table-qualified and may collide with joined columns. Query it without ` +
+        `relationship-qualified fields, or redeclare it as a plain column.`);
+}
+export function resolveDimensionExpression(ds, dimensionName, joinCtx) {
+    if (joinCtx && isQualifiedField(dimensionName)) {
+        return resolveQualifiedColumn(ds, dimensionName);
+    }
     const definition = ds.dimensions[dimensionName];
-    return definition?.sql ?? definition?.column ?? dimensionName;
+    if (definition?.sql) {
+        assertNoRawSqlUnderJoins('dimension', dimensionName, definition.sql, joinCtx);
+        return definition.sql;
+    }
+    return qualifyBaseColumn(joinCtx, definition?.column ?? dimensionName);
 }
-export function resolveFilterField(ds, filterField) {
+export function resolveFilterField(ds, filterField, joinCtx) {
+    if (joinCtx && isQualifiedField(filterField)) {
+        return resolveQualifiedColumn(ds, filterField);
+    }
     const resolvedField = ds.filters[filterField]?.field ?? filterField;
-    return resolveDimensionExpression(ds, resolvedField);
+    return resolveDimensionExpression(ds, resolvedField, joinCtx);
 }
-export function buildDimensionSelectionPlan(ds, dimensions, grain) {
+export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx) {
     const selectParts = [];
     const groupByParts = new Set();
     if (grain) {
@@ -20,23 +50,36 @@ export function buildDimensionSelectionPlan(ds, dimensions, grain) {
         if (!fn) {
             throw new Error(`Unsupported time grain "${grain}".`);
         }
-        selectParts.push(`${fn}(${ds.timeKey}) AS period`);
+        selectParts.push(`${fn}(${qualifyBaseColumn(joinCtx, String(ds.timeKey))}) AS period`);
         groupByParts.add("period");
     }
     for (const dimensionName of dimensions) {
-        const expression = resolveDimensionExpression(ds, dimensionName);
-        if (expression === dimensionName) {
+        const expression = resolveDimensionExpression(ds, dimensionName, joinCtx);
+        if (joinCtx) {
+            // With joins in scope, every selection is table-qualified and aliased so
+            // grouping/ordering can reference the alias unambiguously.
+            const alias = isQualifiedField(dimensionName)
+                ? quoteSQLIdentifier(dimensionName)
+                : dimensionName;
+            selectParts.push(`${expression} AS ${alias}`);
+            groupByParts.add(alias);
+        }
+        else if (expression === dimensionName) {
             selectParts.push(dimensionName);
+            groupByParts.add(dimensionName);
         }
         else {
             selectParts.push(`${expression} AS ${dimensionName}`);
+            groupByParts.add(dimensionName);
         }
-        groupByParts.add(dimensionName);
     }
     return { selectParts, groupByParts: Array.from(groupByParts) };
 }
-export function applyAggregationSpec(qb, ds, spec, alias) {
-    const fieldOrExpr = applyFilteredAggregationExpression(ds, spec, spec.sql ?? resolveDimensionExpression(ds, spec.field));
+export function applyAggregationSpec(qb, ds, spec, alias, joinCtx) {
+    if (spec.sql) {
+        assertNoRawSqlUnderJoins('measure', alias, spec.sql, joinCtx);
+    }
+    const fieldOrExpr = applyFilteredAggregationExpression(ds, spec, spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx), joinCtx);
     switch (spec.aggregation) {
         case "sum":
             return qb.sum(fieldOrExpr, alias);
@@ -50,39 +93,57 @@ export function applyAggregationSpec(qb, ds, spec, alias) {
             return qb.min(fieldOrExpr, alias);
         case "max":
             return qb.max(fieldOrExpr, alias);
+        case "argMax":
+        case "argMin": {
+            if (!spec.argField) {
+                throw new Error(`Aggregation "${spec.aggregation}" for "${alias}" requires an argField ("by" column).`);
+            }
+            const argExpr = resolveDimensionExpression(ds, spec.argField, joinCtx);
+            if (spec.aggregation === "argMax") {
+                if (!qb.argMax) {
+                    throw new Error('Query builder does not support argMax aggregations.');
+                }
+                return qb.argMax(fieldOrExpr, argExpr, alias);
+            }
+            if (!qb.argMin) {
+                throw new Error('Query builder does not support argMin aggregations.');
+            }
+            return qb.argMin(fieldOrExpr, argExpr, alias);
+        }
+        case "percentile": {
+            if (spec.level == null) {
+                throw new Error(`Aggregation "percentile" for "${alias}" requires a level.`);
+            }
+            validatePercentileLevel(spec.level);
+            if (!qb.quantile) {
+                throw new Error('Query builder does not support percentile aggregations.');
+            }
+            return qb.quantile(fieldOrExpr, spec.level, alias);
+        }
+        case "stddev":
+            if (!qb.stddev) {
+                throw new Error('Query builder does not support stddev aggregations.');
+            }
+            return qb.stddev(fieldOrExpr, alias);
+        case "variance":
+            if (!qb.variance) {
+                throw new Error('Query builder does not support variance aggregations.');
+            }
+            return qb.variance(fieldOrExpr, alias);
         default:
             throw new Error(`Unknown aggregation type: ${spec.aggregation}`);
     }
 }
-export function applyMeasureDefinition(qb, ds, name, definition) {
-    const baseFieldOrExpr = definition.sql ?? resolveDimensionExpression(ds, definition.field);
-    const fieldOrExpr = applyFilteredAggregationExpression(ds, {
-        __type: 'aggregation_spec',
-        aggregation: definition.aggregation,
-        field: definition.field,
-        filters: definition.filters,
-    }, baseFieldOrExpr);
-    switch (definition.aggregation) {
-        case "sum":
-            return qb.sum(fieldOrExpr, name);
-        case "count":
-            return qb.count(fieldOrExpr, name);
-        case "countDistinct":
-            return qb.countDistinct(fieldOrExpr, name);
-        case "avg":
-            return qb.avg(fieldOrExpr, name);
-        case "min":
-            return qb.min(fieldOrExpr, name);
-        case "max":
-            return qb.max(fieldOrExpr, name);
-        default:
-            throw new Error(`Unsupported measure aggregation: ${definition.aggregation}`);
-    }
+export function applyMeasureDefinition(qb, ds, name, definition, joinCtx) {
+    return applyAggregationSpec(qb, ds, measureToAggregationSpec(name, definition), name, joinCtx);
 }
-export function appendOrderLimitOffset(qb, orderBy, grain, limit, offset) {
+export function appendOrderLimitOffset(qb, orderBy, grain, limit, offset, joinCtx) {
     if (orderBy && orderBy.length > 0) {
         for (const order of orderBy) {
-            qb = qb.orderBy(order.field, toOrderDirection(order.direction));
+            const column = joinCtx && isQualifiedField(order.field)
+                ? quoteSQLIdentifier(order.field)
+                : order.field;
+            qb = qb.orderBy(column, toOrderDirection(order.direction));
         }
     }
     else if (grain) {

package/dist/relationships.d.ts

@@ -18,27 +18,27 @@
  */
 import type { RelationshipDefinition } from './types.js';
 /** Many-to-one relationship (FK on this table). */
-export declare function belongsTo(target: () => {
+export declare function belongsTo<TTarget extends {
     __type: 'dataset';
     name: string;
-}, join: {
+}>(target: () => TTarget, join: {
     from: string;
     to: string;
-}): RelationshipDefinition;
+}): RelationshipDefinition<TTarget, 'belongsTo'>;
 /** One-to-many relationship (FK on target table). */
-export declare function hasMany(target: () => {
+export declare function hasMany<TTarget extends {
     __type: 'dataset';
     name: string;
-}, join: {
+}>(target: () => TTarget, join: {
     from: string;
     to: string;
-}): RelationshipDefinition;
+}): RelationshipDefinition<TTarget, 'hasMany'>;
 /** One-to-one relationship (FK on target table). */
-export declare function hasOne(target: () => {
+export declare function hasOne<TTarget extends {
     __type: 'dataset';
     name: string;
-}, join: {
+}>(target: () => TTarget, join: {
     from: string;
     to: string;
-}): RelationshipDefinition;
+}): RelationshipDefinition<TTarget, 'hasOne'>;
 //# sourceMappingURL=relationships.d.ts.map

package/dist/relationships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../src/relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAoB,MAAM,YAAY,CAAC;AAgB3E,mDAAmD;AACnD,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAExB;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAExB;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAExB"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../src/relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAoB,MAAM,YAAY,CAAC;AAmB3E,mDAAmD;AACnD,wBAAgB,SAAS,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC3E,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,WAAW,CAAC,CAE9C;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACzE,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,SAAS,CAAC,CAE5C;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,OAAO,SAAS;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACxE,MAAM,EAAE,MAAM,OAAO,EACrB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjC,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAE3C"}