@hypequery/datasets 0.8.0 → 0.9.0

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;AAE9C,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,CA2BlB;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,CAiClB;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,46 @@
 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';
 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 +48,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);
@@ -54,14 +95,17 @@ export function applyAggregationSpec(qb, ds, spec, alias) {
             throw new Error(`Unknown aggregation type: ${spec.aggregation}`);
     }
 }
-export function applyMeasureDefinition(qb, ds, name, definition) {
-    const baseFieldOrExpr = definition.sql ?? resolveDimensionExpression(ds, definition.field);
+export function applyMeasureDefinition(qb, ds, name, definition, joinCtx) {
+    if (definition.sql) {
+        assertNoRawSqlUnderJoins('measure', name, definition.sql, joinCtx);
+    }
+    const baseFieldOrExpr = definition.sql ?? resolveDimensionExpression(ds, definition.field, joinCtx);
     const fieldOrExpr = applyFilteredAggregationExpression(ds, {
         __type: 'aggregation_spec',
         aggregation: definition.aggregation,
         field: definition.field,
         filters: definition.filters,
-    }, baseFieldOrExpr);
+    }, baseFieldOrExpr, joinCtx);
     switch (definition.aggregation) {
         case "sum":
             return qb.sum(fieldOrExpr, name);
@@ -79,10 +123,13 @@ export function applyMeasureDefinition(qb, ds, name, definition) {
             throw new Error(`Unsupported measure aggregation: ${definition.aggregation}`);
     }
 }
-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"}

package/dist/semantic-plan.d.ts

@@ -1,6 +1,16 @@
+/**
+ * Database-neutral semantic plan protocol (`PlanNode` / `SemanticBackend`).
+ *
+ * FROZEN: this execution path is superseded by the query-builder path —
+ * `createDatasetClient({ queryBuilder })` is the canonical way to execute
+ * semantic queries. The plan/backend protocol receives bug fixes only; new
+ * semantic features land on the query-builder path and are not guaranteed to
+ * be mirrored here.
+ */
 import type { AggregationType, FieldType, MetricFilter, MetricOrderBy, TimeGrain } from './types.js';
 export type SemanticBinaryOperator = 'add' | 'subtract' | 'multiply' | 'divide';
 export type SemanticFunctionName = 'nullIfZero' | 'coalesce' | 'round' | 'floor' | 'ceil';
+/** @deprecated Part of the frozen plan/backend protocol; use `createDatasetClient({ queryBuilder })` instead. */
 export type SemanticExpression = {
     kind: 'ref';
     name: string;
@@ -17,17 +27,43 @@ export type SemanticExpression = {
     name: SemanticFunctionName;
     args: SemanticExpression[];
 };
+/** @deprecated Part of the frozen plan/backend protocol; use `createDatasetClient({ queryBuilder })` instead. */
 export interface SemanticDimensionPlan {
     name: string;
     field: string;
     fieldType?: FieldType;
 }
+/** @deprecated Part of the frozen plan/backend protocol; use `createDatasetClient({ queryBuilder })` instead. */
 export interface SemanticAggregationPlan {
     name: string;
     aggregation: AggregationType;
     field: string;
     filters?: MetricFilter[];
 }
+export type SemanticTenantPredicate = {
+    field: string;
+    operator: 'eq';
+    value: string;
+} | {
+    field: string;
+    operator: 'in';
+    value: string[];
+};
+/**
+ * A query-time LEFT JOIN for a to-one relationship. `relationship` is the alias
+ * used to qualify joined columns (`<relationship>.<column>`); `from`/`to` are
+ * the unqualified base and target join columns. An optional `tenant` predicate
+ * scopes the joined target when runtime tenancy is active on the target.
+ */
+export interface SemanticJoinPlan {
+    relationship: string;
+    source: string;
+    from: string;
+    to: string;
+    type: 'left';
+    tenant?: SemanticTenantPredicate;
+}
+/** @deprecated Part of the frozen plan/backend protocol; use `createDatasetClient({ queryBuilder })` instead. */
 export interface SemanticGrainPlan {
     field: string;
     unit: TimeGrain;
@@ -35,6 +71,7 @@ export interface SemanticGrainPlan {
     timezone?: string;
     weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
 }
+/** @deprecated Part of the frozen plan/backend protocol; use `createDatasetClient({ queryBuilder })` instead. */
 export type PlanNode = {
     kind: 'aggregate';
     source: string;
@@ -45,15 +82,13 @@ export type PlanNode = {
     orderBy?: MetricOrderBy[];
     limit?: number;
     offset?: number;
-    tenant?: {
-        field: string;
-        operator: 'eq';
-        value: string;
-    } | {
-        field: string;
-        operator: 'in';
-        value: string[];
-    };
+    tenant?: SemanticTenantPredicate;
+    /**
+     * To-one relationship LEFT JOINs. When present, joined columns referenced by
+     * dimensions/filters are qualified as `<relationship>.<column>`; base columns
+     * stay unqualified (SQL backends qualify them with `source` as needed).
+     */
+    joins?: SemanticJoinPlan[];
 } | {
     kind: 'derive';
     input: PlanNode;
@@ -65,6 +100,7 @@ export type PlanNode = {
     limit?: number;
     offset?: number;
 };
+/** @deprecated Part of the frozen plan/backend protocol; use `createDatasetClient({ queryBuilder })` instead. */
 export interface SemanticBackendResult<T = Record<string, unknown>> {
     data: T[];
     meta?: {
@@ -73,6 +109,11 @@ export interface SemanticBackendResult<T = Record<string, unknown>> {
         tenant?: string;
     };
 }
+/**
+ * @deprecated The plan/backend execution path is frozen (bug fixes only).
+ * Pass a query builder to `createDatasetClient({ queryBuilder })` instead of
+ * implementing a backend.
+ */
 export interface SemanticBackend {
     execute<T = Record<string, unknown>>(plan: PlanNode): Promise<SemanticBackendResult<T>>;
     explain?(plan: PlanNode): Promise<{

package/dist/semantic-plan.d.ts.map

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

package/dist/semantic-plan.js

@@ -1 +1,10 @@
+/**
+ * Database-neutral semantic plan protocol (`PlanNode` / `SemanticBackend`).
+ *
+ * FROZEN: this execution path is superseded by the query-builder path —
+ * `createDatasetClient({ queryBuilder })` is the canonical way to execute
+ * semantic queries. The plan/backend protocol receives bug fixes only; new
+ * semantic features land on the query-builder path and are not guaranteed to
+ * be mirrored here.
+ */
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAEhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAGT,MAAM,oBAAoB,CAAC;AAgH5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV;AAuFD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAUV"}
+{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,WAAW,EACX,SAAS,EACT,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AAuL5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAaV;AAuFD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAUV"}

package/dist/semantic-planner.js

@@ -2,6 +2,7 @@ import { getMetricGrain, getMetricRef, } from './utils/metric-handle.js';
 import { validateDatasetQuery } from './dataset-query.js';
 import { isSupportedTimeGrain } from './constants.js';
 import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
+import { isQualifiedField, resolveQualifiedField } from './utils/relationship-fields.js';
 function resolveField(ds, field) {
     const dimension = ds.dimensions[field];
     if (dimension?.sql) {
@@ -10,15 +11,41 @@ function resolveField(ds, field) {
     }
     return dimension?.column ?? field;
 }
+/**
+ * Resolves a relationship-qualified field to its plan field name
+ * (`<relationship>.<targetColumn>`). Validation runs before planning, so an
+ * unresolved qualified name here is a programming error.
+ */
+function resolveQualifiedPlanField(ds, name) {
+    const resolution = resolveQualifiedField(ds, name);
+    if (!resolution || !resolution.resolved) {
+        throw new Error(resolution?.error ?? `Cannot resolve relationship field "${name}".`);
+    }
+    return resolution.resolved;
+}
 function dimensionsForQuery(ds, dimensions = []) {
-    return dimensions.map((name) => ({
-        name,
-        field: resolveField(ds, name),
-        fieldType: ds.dimensions[name]?.fieldType,
-    }));
+    return dimensions.map((name) => {
+        if (isQualifiedField(name)) {
+            const { relationshipName, targetColumn, targetDimension } = resolveQualifiedPlanField(ds, name);
+            return {
+                name,
+                field: `${relationshipName}.${targetColumn}`,
+                fieldType: targetDimension.fieldType,
+            };
+        }
+        return {
+            name,
+            field: resolveField(ds, name),
+            fieldType: ds.dimensions[name]?.fieldType,
+        };
+    });
 }
 function normalizeFilters(ds, filters = []) {
     return filters.map((filter) => {
+        if (isQualifiedField(filter.field)) {
+            const { relationshipName, targetColumn } = resolveQualifiedPlanField(ds, filter.field);
+            return { ...filter, field: `${relationshipName}.${targetColumn}` };
+        }
         const resolvedField = ds.filters[filter.field]?.field ?? filter.field;
         return {
             ...filter,
@@ -26,6 +53,40 @@ function normalizeFilters(ds, filters = []) {
         };
     });
 }
+/**
+ * Collects deduped to-one LEFT JOINs for every relationship referenced by the
+ * query's dimensions, filters, or orderBy, scoping each joined target with the
+ * runtime tenant predicate when the target declares a `tenantKey`.
+ */
+function collectJoins(ds, dimensions = [], filters = [], orderBy = [], context) {
+    const referenced = [
+        ...dimensions,
+        ...filters.map((filter) => filter.field),
+        ...orderBy.map((order) => order.field),
+    ].filter(isQualifiedField);
+    if (referenced.length === 0) {
+        return undefined;
+    }
+    const tenantPredicate = getRuntimeTenantPredicate(context);
+    const joins = new Map();
+    for (const name of referenced) {
+        const { relationshipName, relationship, target } = resolveQualifiedPlanField(ds, name);
+        if (joins.has(relationshipName)) {
+            continue;
+        }
+        joins.set(relationshipName, {
+            relationship: relationshipName,
+            source: target.source,
+            from: relationship.from,
+            to: relationship.to,
+            type: 'left',
+            tenant: tenantPredicate && target.tenantKey
+                ? { field: target.tenantKey, ...tenantPredicate }
+                : undefined,
+        });
+    }
+    return Array.from(joins.values());
+}
 function aggregationForMeasure(ds, name) {
     const measure = ds.measures[name];
     if (!measure) {
@@ -77,6 +138,7 @@ function aggregatePlan(ds, query, aggregations, context) {
         limit: query.limit,
         offset: query.offset,
         tenant: tenantForContext(ds, context),
+        joins: collectJoins(ds, query.dimensions, query.filters, query.orderBy, context),
     };
 }
 export function buildDatasetPlan(ds, query = {}, context) {

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAGZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EAIjB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAGtB,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,WAAW,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,CAAC;AAEvE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CACL,MAAM,EAAE,kBAAkB,GAAG,YAAY,EACzC,KAAK,CAAC,EAAE,YAAY,GAAG,WAAW,EAClC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC/C,SAAS,EAAE,oBAAoB,CAAC;IAChC,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,UAAU,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;CACzB;AA8VD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,sBAAsB,EAAE,CAenG;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,oBAAoB,EAAE,CASrF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAWjG;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,iBAAiB,EAAE,CAM/E;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAGZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EAKjB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AAGtB,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,MAAM,WAAW,sBAAsB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,CAAC;AAEvE,MAAM,WAAW,oBAAoB;IACnC,OAAO,CACL,MAAM,EAAE,kBAAkB,GAAG,YAAY,EACzC,KAAK,CAAC,EAAE,YAAY,GAAG,WAAW,EAClC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC/C,SAAS,EAAE,oBAAoB,CAAC;IAChC,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,UAAU,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;CACzB;AAoXD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,sBAAsB,EAAE,CAenG;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,oBAAoB,EAAE,CASrF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAWjG;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,iBAAiB,EAAE,CAM/E;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/tools.js

@@ -1,4 +1,4 @@
-import { getDatasetCatalog, getDatasetCatalogs, } from './catalog.js';
+import { getDatasetCatalog, getDatasetCatalogs, getQueryableRelationshipFields, } from './catalog.js';
 import { SEMANTIC_FILTER_OPERATORS } from './constants.js';
 function enumSchema(values, description) {
     const unique = Array.from(new Set(values));
@@ -29,11 +29,19 @@ function limitSchema(catalogs) {
         ...(finiteLimits.length > 0 ? { maximum: Math.max(...finiteLimits) } : {}),
     };
 }
+function catalogFieldLists(catalog) {
+    const relationshipFields = getQueryableRelationshipFields(catalog);
+    return {
+        dimensions: [...Object.keys(catalog.dimensions), ...relationshipFields],
+        filters: [...Object.keys(catalog.filters), ...relationshipFields],
+    };
+}
 function querySchema(catalogs, includeDataset) {
+    const fieldLists = catalogs.map(catalogFieldLists);
     const datasetNames = catalogs.map(catalog => catalog.name);
-    const dimensionNames = Array.from(new Set(catalogs.flatMap(catalog => Object.keys(catalog.dimensions))));
+    const dimensionNames = Array.from(new Set(fieldLists.flatMap(fields => fields.dimensions)));
     const measureNames = Array.from(new Set(catalogs.flatMap(catalog => Object.keys(catalog.measures))));
-    const filterNames = Array.from(new Set(catalogs.flatMap(catalog => Object.keys(catalog.filters))));
+    const filterNames = Array.from(new Set(fieldLists.flatMap(fields => fields.filters)));
     const grainNames = Array.from(new Set(catalogs.flatMap(catalog => catalog.supportedGrains)));
     const orderFields = Array.from(new Set(catalogs.flatMap(catalog => catalog.orderableFields)));
     const properties = {
@@ -150,7 +158,7 @@ function assertAllowedValues(values, allowed, label) {
         throw new Error(`Invalid ${label}: ${invalid.join(', ')}. Available: ${allowed.join(', ') || '(none)'}.`);
     }
 }
-function normalizeDatasetQuery(input, catalog, options = {}) {
+function normalizeDatasetQuery(input, catalog, fields, options = {}) {
     const dimensions = assertStringArray(input.dimensions, 'dimensions');
     const measures = assertStringArray(input.measures, 'measures');
     const filters = assertFilters(input.filters);
@@ -158,12 +166,12 @@ function normalizeDatasetQuery(input, catalog, options = {}) {
     const limit = assertNonNegativeInteger(input.limit, 'limit');
     const offset = assertNonNegativeInteger(input.offset, 'offset');
     let by;
-    assertAllowedValues(dimensions, Object.keys(catalog.dimensions), 'dimensions');
+    assertAllowedValues(dimensions, fields.dimensions, 'dimensions');
     assertAllowedValues(measures, Object.keys(catalog.measures), 'measures');
-    assertAllowedValues(filters.map(filter => filter.field), Object.keys(catalog.filters), 'filter fields');
+    assertAllowedValues(filters.map(filter => filter.field), fields.filters, 'filter fields');
     assertAllowedValues(orderBy.map(order => order.field), options.orderableFields ?? catalog.orderableFields, 'orderBy fields');
     for (const filter of filters) {
-        const allowedOperators = catalog.filters[filter.field]?.operators ?? [];
+        const allowedOperators = catalog.filters[filter.field]?.operators ?? [...SEMANTIC_FILTER_OPERATORS];
         if (!allowedOperators.includes(filter.operator)) {
             throw new Error(`Invalid filter operator for "${filter.field}": ${filter.operator}. Allowed: ${allowedOperators.join(', ')}.`);
         }
@@ -204,6 +212,7 @@ function redactSql(result, includeSql) {
 }
 function buildCatalogTool(datasets, catalogs, analytics, includeSql) {
     const catalogList = Object.values(catalogs);
+    const fieldLists = Object.fromEntries(Object.entries(catalogs).map(([name, catalog]) => [name, catalogFieldLists(catalog)]));
     return {
         name: 'query_dataset',
         description: 'Query governed analytics datasets by selecting dimensions, measures, filters, and time grains.',
@@ -213,7 +222,7 @@ function buildCatalogTool(datasets, catalogs, analytics, includeSql) {
                 throw new Error(`Invalid dataset: ${String(input.dataset)}. Available: ${Object.keys(datasets).join(', ')}.`);
             }
             const catalog = catalogs[input.dataset];
-            const query = normalizeDatasetQuery(input, catalog);
+            const query = normalizeDatasetQuery(input, catalog, fieldLists[input.dataset]);
             const result = await analytics.execute(datasets[input.dataset], query, context);
             return redactSql(result, includeSql);
         },
@@ -222,19 +231,20 @@ function buildCatalogTool(datasets, catalogs, analytics, includeSql) {
 function buildDatasetTools(datasets, catalogs, analytics, includeSql) {
     return Object.entries(datasets).map(([datasetName, dataset]) => {
         const catalog = catalogs[datasetName];
+        const fields = catalogFieldLists(catalog);
         return {
             name: `query_${toolNamePart(datasetName)}`,
             description: `Query the ${datasetName} analytics dataset.`,
             parameters: querySchema([catalog], false),
             async execute(input, context) {
-                const query = normalizeDatasetQuery(input, catalog);
+                const query = normalizeDatasetQuery(input, catalog, fields);
                 const result = await analytics.execute(dataset, query, context);
                 return redactSql(result, includeSql);
             },
         };
     });
 }
-function metricQuerySchema(catalog, metricName) {
+function metricQuerySchema(catalog, orderableFields) {
     const schema = querySchema([catalog], false);
     const properties = schema.properties ?? {};
     delete properties.measures;
@@ -243,7 +253,7 @@ function metricQuerySchema(catalog, metricName) {
         items: {
             type: 'object',
             properties: {
-                field: enumSchema([...Object.keys(catalog.dimensions), metricName, ...(catalog.timeKey ? ['period'] : [])]),
+                field: enumSchema(orderableFields),
                 direction: enumSchema(['asc', 'desc']),
             },
             required: ['field', 'direction'],
@@ -259,18 +269,19 @@ function buildMetricTools(datasets, catalogs, analytics, includeSql) {
     const tools = [];
     for (const [datasetName, dataset] of Object.entries(datasets)) {
         const catalog = catalogs[datasetName];
+        const fields = catalogFieldLists(catalog);
         for (const [metricName, metric] of Object.entries(dataset.metrics ?? {})) {
+            const orderableFields = [
+                ...fields.dimensions,
+                metricName,
+                ...(catalog.timeKey ? ['period'] : []),
+            ];
             tools.push({
                 name: `query_${toolNamePart(metricName)}`,
                 description: `Query the ${metricName} metric from the ${datasetName} dataset.`,
-                parameters: metricQuerySchema(catalog, metricName),
+                parameters: metricQuerySchema(catalog, orderableFields),
                 async execute(input, context) {
-                    const orderableFields = [
-                        ...Object.keys(catalog.dimensions),
-                        metricName,
-                        ...(catalog.timeKey ? ['period'] : []),
-                    ];
-                    const query = normalizeDatasetQuery({ ...input, measures: [] }, catalog, { orderableFields });
+                    const query = normalizeDatasetQuery({ ...input, measures: [] }, catalog, fields, { orderableFields });
                     const result = await analytics.execute(metric, query, context);
                     return redactSql(result, includeSql);
                 },