@hypequery/datasets 0.21.0 → 0.22.0

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

@@ -0,0 +1,71 @@
+import { queryMeasureDefinitions } from './relationship-measures.js';
+import { buildDatasetQueryBuilder } from './build-dataset-query-builder.js';
+import { baseMeasureNames } from './dataset-measures.js';
+import { buildDerivedDatasetSql, hasSelectedDerivedMeasure } from './dataset-derived-query.js';
+import { measureDependencyNames } from './measure-dependencies.js';
+import { overfetchLimit } from './pagination.js';
+import { resolveResultLimit } from './result-limits.js';
+import { buildTimeMeasureDatasetSql } from './time-measure-dataset-sql.js';
+import { selectedTimeMeasures } from './time-query-measures.js';
+/** The one dispatch point for dataset preview and query-builder execution. */
+export function prepareDatasetQuery(dataset, input, options, mode = 'execution') {
+    const query = structuredClone({
+        ...input,
+        limit: mode === 'execution' ? resolveResultLimit(input.limit, dataset.limits).limit : input.limit,
+    });
+    // Preserve omission while validating/planning: maxMeasures constrains an
+    // explicit selection, not the dataset's default set of base measures.
+    const measures = query.measures ?? baseMeasureNames(dataset.measures);
+    const executionLimit = mode === 'execution' ? overfetchLimit(query.limit) : query.limit;
+    const executionOptions = { ...options, executionLimit };
+    const preflightStatements = [];
+    let statement;
+    let execute;
+    let plan;
+    const abortSignal = options.context?.abortSignal;
+    if (selectedTimeMeasures(dataset, query).size) {
+        plan = 'time';
+        const compiled = buildTimeMeasureDatasetSql(dataset, query, executionOptions);
+        statement = compiled;
+        preflightStatements.push({ sql: compiled.timeAxisSql, parameters: compiled.parameters });
+        execute = async () => {
+            await options.builderFactory.rawQuery(compiled.timeAxisSql, compiled.parameters, { abortSignal });
+            return options.builderFactory.rawQuery(compiled.sql, compiled.parameters, { abortSignal });
+        };
+    }
+    else if (hasSelectedDerivedMeasure(dataset, query)) {
+        plan = 'derived';
+        statement = buildDerivedDatasetSql(dataset, query, executionOptions, buildDatasetQueryBuilder);
+        execute = () => options.builderFactory.rawQuery(statement.sql, statement.parameters, { abortSignal });
+    }
+    else {
+        plan = 'aggregate';
+        const builder = buildDatasetQueryBuilder(dataset, query, executionOptions);
+        statement = builder.toSQLWithParams();
+        // Retain builder execution: custom builders may carry adapter settings.
+        execute = () => builder.execute({ abortSignal });
+    }
+    const description = Object.freeze({
+        kind: 'dataset-compilation', version: 1, dataset: dataset.name, plan,
+        dimensions: Object.freeze([...(query.dimensions ?? [])]),
+        measures: Object.freeze([...measures]),
+        measureDependencies: Object.freeze(measureDependencyNames(queryMeasureDefinitions(dataset, measures), measures)),
+        filters: Object.freeze((query.filters ?? []).map(({ field, operator }) => Object.freeze({ field, operator }))),
+        segments: Object.freeze([...(query.segments ?? [])]),
+        by: query.by, timezone: query.timezone,
+        effectiveLimit: query.limit, executionLimit, offset: query.offset ?? 0,
+        parameterCount: statement.parameters.length,
+        preflightStatementCount: preflightStatements.length,
+    });
+    const compilation = Object.freeze({
+        sql: statement.sql,
+        parameters: Object.freeze(structuredClone(statement.parameters)),
+        query: Object.freeze(structuredClone({ ...query, measures })),
+        preflightStatements: Object.freeze(preflightStatements.map(preflight => Object.freeze({
+            sql: preflight.sql, parameters: Object.freeze(structuredClone(preflight.parameters)),
+        }))),
+        describe: () => description,
+        toJSON: () => description,
+    });
+    return { compilation, execute };
+}

package/dist/utils/composite-time-measure-sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-time-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/composite-time-measure-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAW9D,mFAAmF;AACnF,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,4BAA4B,EAAE,IAAI,EAAE,eAAe;;;;EAgDrJ"}
+{"version":3,"file":"composite-time-measure-sql.d.ts","sourceRoot":"","sources":["../../src/utils/composite-time-measure-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAW9D,mFAAmF;AACnF,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,4BAA4B,EAAE,IAAI,EAAE,eAAe;;;;EAgDrJ"}

package/dist/utils/composite-time-measure-sql.js

@@ -1,3 +1,4 @@
+import { queryMeasureDefinitions } from './relationship-measures.js';
 import { quoteSQLIdentifier } from '../sql-utils.js';
 import { isDerivedMeasure, isWindowMeasure } from './dataset-measures.js';
 import { buildMeasureEvaluationGraph, evaluationFormula } from './measure-evaluation-graph.js';
@@ -9,7 +10,7 @@ import { derivedProjection } from './derived-measure-sql.js';
 import { buildTimeMeasureResultSql } from './time-measure-result-sql.js';
 /** Aggregate each dependency in its evaluation context, then evaluate formulas. */
 export function buildCompositeTimeMeasureSql(ds, query, options, axis) {
-    const graph = buildMeasureEvaluationGraph(ds.measures, query.measures ?? []);
+    const graph = buildMeasureEvaluationGraph(queryMeasureDefinitions(ds, query.measures ?? []), query.measures ?? []);
     const leaves = graph.nodes.filter(node => !isDerivedMeasure(node.definition));
     const baseNames = new Set(leaves.map(node => isWindowMeasure(node.definition) ? node.definition.measure : node.name));
     const source = buildTimeMeasureSourceSql(ds, query, baseNames, axis.filters, options);

package/dist/utils/dataset-derived-query.d.ts

@@ -1,4 +1,4 @@
-import type { AnyDatasetInstance, DatasetQuery, DatasetQueryResult } from '../types.js';
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
 import type { QueryBuilderLike } from '../query-builder-protocol.js';
 import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
 type BuildBaseQuery = (dataset: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions) => QueryBuilderLike;
@@ -7,6 +7,5 @@ export declare function buildDerivedDatasetSql(ds: AnyDatasetInstance, query: Da
     sql: string;
     parameters: unknown[];
 };
-export declare function runDerivedDatasetQuery(ds: AnyDatasetInstance, query: DatasetQuery, options: DatasetQueryExecutionOptions, buildBaseQuery: BuildBaseQuery): Promise<DatasetQueryResult>;
 export {};
 //# sourceMappingURL=dataset-derived-query.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-derived-query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,KAAK,cAAc,GAAG,CACpB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,KAClC,gBAAgB,CAAC;AAEtB,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE9F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CA2CxC;AAED,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAgB7B"}
+{"version":3,"file":"dataset-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-derived-query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAExE,KAAK,cAAc,GAAG,CACpB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,KAClC,gBAAgB,CAAC;AAEtB,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAE9F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B,EACrC,cAAc,EAAE,cAAc,GAC7B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CA4CxC"}

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

@@ -1,10 +1,10 @@
+import { queryMeasureDefinitions } from './relationship-measures.js';
+import { semanticOrderDirection } from './semantic-query-syntax.js';
 import { measureDependencyNames } from './measure-dependencies.js';
 import { derivedExpressionSql } from './derived-measure-sql.js';
 import { baseMeasureNames, getBaseMeasure, getDerivedMeasure } from './dataset-measures.js';
-import { quoteSQLIdentifier } from '../sql-utils.js';
+import { resolveDatasetSqlDialect } from './dataset-sql-dialect.js';
 import { validateDatasetQueryInput } from './dataset-query-validation.js';
-import { overfetchLimit } from './pagination.js';
-import { toDatasetQueryResult } from './dataset-query-result.js';
 export function hasSelectedDerivedMeasure(ds, query) {
     return (query.measures ?? []).some(name => getDerivedMeasure(ds.measures, name) !== undefined);
 }
@@ -13,11 +13,12 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
     if (!validation.valid) {
         throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
     }
+    const dialect = resolveDatasetSqlDialect(options.builderFactory);
     const selected = query.measures ?? baseMeasureNames(ds.measures);
-    const baseMeasures = measureDependencyNames(ds.measures, selected).filter(name => getBaseMeasure(ds.measures, name));
+    const baseMeasures = measureDependencyNames(queryMeasureDefinitions(ds, selected), selected).filter(name => name.includes('.') || getBaseMeasure(ds.measures, name));
     const resolve = (name) => {
         const derived = getDerivedMeasure(ds.measures, name);
-        return derived ? `(${derivedExpressionSql(derived, resolve)})` : quoteSQLIdentifier(name);
+        return derived ? `(${derivedExpressionSql(derived, resolve)})` : dialect.quoteIdentifier(name);
     };
     const inner = buildBaseQuery(ds, {
         ...query,
@@ -29,21 +30,21 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
     const { sql: innerSql, parameters } = inner.toSQLWithParams();
     const projections = [];
     if (query.by)
-        projections.push(quoteSQLIdentifier('period'));
+        projections.push(dialect.quoteIdentifier('period'));
     for (const dimension of query.dimensions ?? [])
-        projections.push(quoteSQLIdentifier(dimension));
+        projections.push(dialect.quoteIdentifier(dimension));
     for (const name of selected) {
         const derived = getDerivedMeasure(ds.measures, name);
         projections.push(derived
-            ? `${derivedExpressionSql(derived, resolve)} AS ${quoteSQLIdentifier(name)}`
-            : quoteSQLIdentifier(name));
+            ? `${derivedExpressionSql(derived, resolve)} AS ${dialect.quoteIdentifier(name)}`
+            : dialect.quoteIdentifier(name));
     }
     let sql = `WITH base AS (${innerSql}) SELECT ${projections.join(', ')} FROM base`;
     if (query.orderBy?.length) {
-        sql += ` ORDER BY ${query.orderBy.map(order => (`${quoteSQLIdentifier(order.field)} ${order.direction === 'asc' ? 'ASC' : 'DESC'}`)).join(', ')}`;
+        sql += ` ORDER BY ${query.orderBy.map(order => (`${dialect.quoteIdentifier(order.field)} ${semanticOrderDirection(order.direction)}`)).join(', ')}`;
     }
     else if (query.by) {
-        sql += ` ORDER BY ${quoteSQLIdentifier('period')} ASC`;
+        sql += ` ORDER BY ${dialect.quoteIdentifier('period')} ASC`;
     }
     const limit = options.executionLimit ?? query.limit;
     if (limit !== undefined)
@@ -52,18 +53,3 @@ export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
         sql += ` OFFSET ${query.offset}`;
     return { sql, parameters };
 }
-export async function runDerivedDatasetQuery(ds, query, options, buildBaseQuery) {
-    const start = Date.now();
-    const { sql, parameters } = buildDerivedDatasetSql(ds, query, {
-        ...options,
-        executionLimit: overfetchLimit(query.limit),
-    }, buildBaseQuery);
-    const rows = await options.builderFactory.rawQuery(sql, parameters, { abortSignal: options.context?.abortSignal });
-    return toDatasetQueryResult(rows, {
-        dataset: ds,
-        query,
-        sql,
-        timingMs: Date.now() - start,
-        context: options.context,
-    });
-}

package/dist/utils/dataset-filter-types.d.ts

@@ -0,0 +1,28 @@
+import type { DatasetInstance, DimensionDefinition, MetricFilter, MetricFilterOperator, RelationshipDefinition, SemanticFilterDefinition, SemanticFiltersDefinition } from '../types.js';
+/** The generated allowlist mirrors normalizeFilters; explicit maps replace it. */
+export type NormalizedDatasetFilters<TDimensions extends Record<string, DimensionDefinition>, TFilters extends SemanticFiltersDefinition | undefined> = TFilters extends SemanticFiltersDefinition ? TFilters : {
+    [K in keyof TDimensions as TDimensions[K] extends {
+        filterable: false;
+    } ? never : K]: SemanticFilterDefinition & {
+        field: K & string;
+    };
+};
+type FilterOperators<TDefinition> = TDefinition extends {
+    operators: readonly (infer TOperator extends MetricFilterOperator)[];
+} ? TOperator : MetricFilterOperator;
+type LocalFilterFor<TFilters extends SemanticFiltersDefinition> = {
+    [K in keyof TFilters & string]: K extends `${string}.${string}` ? never : MetricFilter<K, unknown, FilterOperators<TFilters[K]>>;
+}[keyof TFilters & string];
+type RelationshipFilterFor<TRelationships extends Record<string, RelationshipDefinition>> = {
+    [R in keyof TRelationships & string]: TRelationships[R] extends RelationshipDefinition<infer TTarget, infer TKind> ? TKind extends 'hasMany' ? never : TTarget extends DatasetInstance<any, any, any, any> ? {
+        [K in keyof TTarget['filters'] & keyof TTarget['dimensions'] & string]: TTarget['dimensions'][K] extends {
+            sql: string;
+        } ? never : K extends TTarget['filters'][K]['field'] ? MetricFilter<`${R}.${K}`, unknown, FilterOperators<TTarget['filters'][K]>> : never;
+    }[keyof TTarget['filters'] & keyof TTarget['dimensions'] & string] : never : never;
+}[keyof TRelationships & string];
+/** Filter names and operator policies exposed by a dataset and its to-one targets. */
+export type DatasetFilterFor<TDataset extends DatasetInstance<any, any, any, any>> = LocalFilterFor<TDataset['filters']> | RelationshipFilterFor<TDataset['relationships']>;
+/** Names in the normalized filter allowlist, including one-hop relationship filters. */
+export type DatasetFilterNames<TDataset extends DatasetInstance<any, any, any, any>> = DatasetFilterFor<TDataset>['field'];
+export {};
+//# sourceMappingURL=dataset-filter-types.d.ts.map

package/dist/utils/dataset-filter-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-filter-types.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-filter-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB,kFAAkF;AAClF,MAAM,MAAM,wBAAwB,CAClC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,QAAQ,SAAS,yBAAyB,GAAG,SAAS,IACpD,QAAQ,SAAS,yBAAyB,GAAG,QAAQ,GAAG;KACzD,CAAC,IAAI,MAAM,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,SAAS;QAAE,UAAU,EAAE,KAAK,CAAA;KAAE,GAAG,KAAK,GAAG,CAAC,GAAG,wBAAwB,GAAG;QAC/G,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;KACnB;CACF,CAAC;AAEF,KAAK,eAAe,CAAC,WAAW,IAAI,WAAW,SAAS;IACtD,SAAS,EAAE,SAAS,CAAC,MAAM,SAAS,SAAS,oBAAoB,CAAC,EAAE,CAAC;CACtE,GAAG,SAAS,GAAG,oBAAoB,CAAC;AAErC,KAAK,cAAc,CAAC,QAAQ,SAAS,yBAAyB,IAAI;KAC/D,CAAC,IAAI,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,GAC3D,KAAK,GACL,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3D,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC;AAE3B,KAAK,qBAAqB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,IAAI;KACzF,CAAC,IAAI,MAAM,cAAc,GAAG,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,SAAS,sBAAsB,CAAC,MAAM,OAAO,EAAE,MAAM,KAAK,CAAC,GAC9G,KAAK,SAAS,SAAS,GAAG,KAAK,GAC7B,OAAO,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACjD;SACC,CAAC,IAAI,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,GACnE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,KAAK,GACpD,CAAC,SAAS,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GACtC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1E,KAAK;KACd,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,GAChE,KAAK,GACT,KAAK;CACV,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,CAAC;AAEjC,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,CAAC,QAAQ,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAC7E,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,GACnC,qBAAqB,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC;AAErD,wFAAwF;AACxF,MAAM,MAAM,kBAAkB,CAAC,QAAQ,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IACjF,gBAAgB,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC"}

package/dist/utils/dataset-filter-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAiB9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAmKlB"}
+{"version":3,"file":"dataset-query-validation.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAiB9E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAuKlB"}

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

@@ -1,3 +1,5 @@
+import { resolveRelationshipMeasure } from './relationship-measures.js';
+import { semanticQuerySyntaxErrors } from './semantic-query-syntax.js';
 import { queryTimezoneErrors } from './query-timezone.js';
 import { baseMeasureNames } from './dataset-measures.js';
 import { validateFilterValue } from '../validation.js';
@@ -8,11 +10,16 @@ import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './r
 import { segmentSelectionErrors } from './segments.js';
 import { analyzeTimeMeasureAxis } from './time-measure-axis.js';
 export function validateDatasetQueryInput(ds, query, context) {
-    const errors = queryTimezoneErrors(query.timezone);
+    const errors = [...semanticQuerySyntaxErrors(query), ...queryTimezoneErrors(query.timezone)];
     const dimensionNames = Object.keys(ds.dimensions);
     const measureNames = Object.keys(ds.measures);
     const selectedDimensions = query.dimensions ?? [];
     const selectedMeasures = query.measures ?? baseMeasureNames(ds.measures);
+    for (const name of selectedDimensions) {
+        if (selectedMeasures.includes(name)) {
+            errors.push(`Output "${name}" cannot be selected as both a dimension and a measure. Select one or give the definitions distinct names.`);
+        }
+    }
     const filterNames = Object.keys(ds.filters);
     const orderableFields = new Set([
         ...selectedDimensions,
@@ -47,7 +54,12 @@ export function validateDatasetQueryInput(ds, query, context) {
     if (query.measures) {
         for (const measure of query.measures) {
             if (isQualifiedField(measure)) {
-                errors.push(`Measure "${measure}" is relationship-qualified. Measures can only be defined on the base dataset "${ds.name}", not traversed through relationships.`);
+                try {
+                    resolveRelationshipMeasure(ds, measure);
+                }
+                catch (error) {
+                    errors.push(error.message);
+                }
                 continue;
             }
             if (!measureNames.includes(measure)) {
@@ -95,7 +107,7 @@ export function validateDatasetQueryInput(ds, query, context) {
     if (query.orderBy) {
         const invalid = [];
         for (const order of query.orderBy) {
-            if (isQualifiedField(order.field)) {
+            if (isQualifiedField(order.field) && !selectedMeasures.includes(order.field)) {
                 const resolution = resolveQualifiedField(ds, order.field);
                 if (resolution?.error) {
                     errors.push(resolution.error);

package/dist/utils/dataset-sql-dialect.d.ts

@@ -0,0 +1,5 @@
+import type { DatasetSqlDialect } from '../dataset-sql-dialect.js';
+import type { QueryBuilderFactoryInput } from '../query-builder-protocol.js';
+/** Resolve from the active factory, so a runtime builder override carries its dialect. */
+export declare function resolveDatasetSqlDialect(factory: QueryBuilderFactoryInput): DatasetSqlDialect;
+//# sourceMappingURL=dataset-sql-dialect.d.ts.map

package/dist/utils/dataset-sql-dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-sql-dialect.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-sql-dialect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAG7E,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAE7F"}

package/dist/utils/dataset-sql-dialect.js

@@ -0,0 +1,5 @@
+import { clickhouseDatasetSqlDialect } from './clickhouse-dataset-sql-dialect.js';
+/** Resolve from the active factory, so a runtime builder override carries its dialect. */
+export function resolveDatasetSqlDialect(factory) {
+    return factory.datasetSqlDialect ?? clickhouseDatasetSqlDialect;
+}

package/dist/utils/dataset-target.d.ts

@@ -0,0 +1,3 @@
+import type { AnyDatasetInstance } from '../types.js';
+export declare function isDatasetInstance(target: unknown): target is AnyDatasetInstance;
+//# sourceMappingURL=dataset-target.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-target.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,kBAAkB,CAE/E"}

package/dist/utils/dataset-target.js

@@ -0,0 +1,3 @@
+export function isDatasetInstance(target) {
+    return !!target && typeof target === 'object' && '__type' in target && target.__type === 'dataset';
+}

package/dist/utils/filter-definition.d.ts

@@ -0,0 +1,3 @@
+import type { MetricFilter, MetricFilterOperator } from '../types.js';
+export declare function createFilter<const TField extends string, const TValue, TOperator extends MetricFilterOperator>(field: TField, operator: TOperator, value: TValue): MetricFilter<TField, TValue, TOperator>;
+//# sourceMappingURL=filter-definition.d.ts.map

package/dist/utils/filter-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-definition.d.ts","sourceRoot":"","sources":["../../src/utils/filter-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEtE,wBAAgB,YAAY,CAC1B,KAAK,CAAC,MAAM,SAAS,MAAM,EAC3B,KAAK,CAAC,MAAM,EACZ,SAAS,SAAS,oBAAoB,EACtC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAE5F"}

package/dist/utils/filter-definition.js

@@ -0,0 +1,3 @@
+export function createFilter(field, operator, value) {
+    return { field, operator, value };
+}

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

@@ -0,0 +1,8 @@
+import type { MetricRef, MetricQuery, ExecutionContext, TimeGrain } from '../types.js';
+import type { QueryBuilderFactoryLike } from '../query-builder-protocol.js';
+import type { DerivedMetricSpec } from '../types.js';
+export declare function buildDerivedMetricSql(ref: MetricRef, spec: DerivedMetricSpec, query: MetricQuery, grain: TimeGrain | undefined, builderFactory: QueryBuilderFactoryLike, context?: ExecutionContext): {
+    sql: string;
+    params: unknown[];
+};
+//# sourceMappingURL=metric-derived-query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metric-derived-query.d.ts","sourceRoot":"","sources":["../../src/utils/metric-derived-query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,KAAK,EAAE,uBAAuB,EAAoB,MAAM,8BAA8B,CAAC;AAiB9F,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;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAiHpC"}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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