@hypequery/datasets 0.16.0 → 0.17.1

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

@@ -0,0 +1,112 @@
+import { quoteSQLIdentifier } from '../sql-utils.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 => Object.hasOwn(ds.derivedMeasures, name));
+}
+function expressionSql(expression, uses) {
+    switch (expression.kind) {
+        case 'ref': {
+            if (!Object.hasOwn(uses, expression.name)) {
+                throw new Error(`Formula references undeclared input "${expression.name}".`);
+            }
+            const measureName = uses[expression.name];
+            return quoteSQLIdentifier(measureName);
+        }
+        case 'literal': {
+            if (expression.value === null)
+                return 'NULL';
+            if (typeof expression.value === 'number') {
+                if (!Number.isFinite(expression.value))
+                    throw new Error('Formula contains a non-finite number.');
+                return String(expression.value);
+            }
+            if (typeof expression.value === 'boolean')
+                return expression.value ? 'true' : 'false';
+            return `'${expression.value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
+        }
+        case 'binary': {
+            const operators = { add: '+', subtract: '-', multiply: '*', divide: '/' };
+            const operator = operators[expression.operator];
+            if (!operator)
+                throw new Error('Formula contains an unsupported binary operator.');
+            return `(${expressionSql(expression.left, uses)} ${operator} ${expressionSql(expression.right, uses)})`;
+        }
+        case 'function': {
+            const args = expression.args.map(arg => expressionSql(arg, uses));
+            switch (expression.name) {
+                case 'nullIfZero': return `NULLIF(${args[0]}, 0)`;
+                case 'coalesce': return `COALESCE(${args.join(', ')})`;
+                case 'round': return `ROUND(${args.join(', ')})`;
+                case 'floor': return `FLOOR(${args[0]})`;
+                case 'ceil': return `CEIL(${args[0]})`;
+                default: throw new Error('Formula contains an unsupported function.');
+            }
+        }
+    }
+}
+function derivedProjection(name, definition) {
+    const aliases = Object.fromEntries(Object.keys(definition.uses).map(alias => [alias, alias]));
+    return `${expressionSql(definition.formula(aliases).expression, definition.uses)} AS ${quoteSQLIdentifier(name)}`;
+}
+export function buildDerivedDatasetSql(ds, query, options, buildBaseQuery) {
+    const validation = validateDatasetQueryInput(ds, query, options.context);
+    if (!validation.valid) {
+        throw new Error(`Invalid dataset query: ${validation.errors.join('; ')}`);
+    }
+    const selected = query.measures ?? Object.keys(ds.measures);
+    const baseMeasures = new Set(selected.filter(name => Object.hasOwn(ds.measures, name)));
+    for (const name of selected) {
+        const derived = Object.hasOwn(ds.derivedMeasures, name) ? ds.derivedMeasures[name] : undefined;
+        if (derived)
+            Object.values(derived.uses).forEach(base => baseMeasures.add(base));
+    }
+    const inner = buildBaseQuery(ds, {
+        ...query,
+        measures: [...baseMeasures],
+        orderBy: undefined,
+        limit: undefined,
+        offset: undefined,
+    }, { ...options, executionLimit: undefined, skipDefaultOrderBy: true });
+    const { sql: innerSql, parameters } = inner.toSQLWithParams();
+    const projections = [];
+    if (query.by)
+        projections.push(quoteSQLIdentifier('period'));
+    for (const dimension of query.dimensions ?? [])
+        projections.push(quoteSQLIdentifier(dimension));
+    for (const name of selected) {
+        const derived = Object.hasOwn(ds.derivedMeasures, name) ? ds.derivedMeasures[name] : undefined;
+        projections.push(derived
+            ? derivedProjection(name, derived)
+            : quoteSQLIdentifier(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(', ')}`;
+    }
+    else if (query.by) {
+        sql += ` ORDER BY ${quoteSQLIdentifier('period')} ASC`;
+    }
+    const limit = options.executionLimit ?? query.limit;
+    if (limit !== undefined)
+        sql += ` LIMIT ${limit}`;
+    if (query.offset !== undefined)
+        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-measures.d.ts

@@ -0,0 +1,10 @@
+import type { BaseMeasures, DatasetMeasureDefinition, DerivedMeasureDefinition, DerivedMeasures, MeasureDefinition } from '../types.js';
+export declare function isDerivedMeasure(definition: DatasetMeasureDefinition): definition is DerivedMeasureDefinition;
+export declare function isBaseMeasure(definition: DatasetMeasureDefinition): definition is MeasureDefinition;
+export declare function baseMeasureNames(measures: Record<string, DatasetMeasureDefinition>): string[];
+export declare function splitDatasetMeasures<TMeasures extends Record<string, DatasetMeasureDefinition>>(measures: TMeasures | undefined): {
+    base: BaseMeasures<TMeasures>;
+    derived: DerivedMeasures<TMeasures>;
+};
+export declare function getDerivedMeasure(measures: Record<string, DatasetMeasureDefinition>, name: string): DerivedMeasureDefinition | undefined;
+//# sourceMappingURL=dataset-measures.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-measures.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-measures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,wBAAwB,GACnC,UAAU,IAAI,wBAAwB,CAExC;AAED,wBAAgB,aAAa,CAC3B,UAAU,EAAE,wBAAwB,GACnC,UAAU,IAAI,iBAAiB,CAEjC;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GAAG,MAAM,EAAE,CAI7F;AAED,wBAAgB,oBAAoB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC7F,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B;IAAE,IAAI,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAA;CAAE,CAMxE;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAClD,IAAI,EAAE,MAAM,GACX,wBAAwB,GAAG,SAAS,CAItC"}

package/dist/utils/dataset-measures.js

@@ -0,0 +1,24 @@
+export function isDerivedMeasure(definition) {
+    return definition.__type === 'derived_measure_definition';
+}
+export function isBaseMeasure(definition) {
+    return definition.__type === 'measure_definition';
+}
+export function baseMeasureNames(measures) {
+    return Object.entries(measures)
+        .filter(([, definition]) => isBaseMeasure(definition))
+        .map(([name]) => name);
+}
+export function splitDatasetMeasures(measures) {
+    const entries = Object.entries(measures ?? {});
+    return {
+        base: Object.fromEntries(entries.filter(([, definition]) => isBaseMeasure(definition))),
+        derived: Object.fromEntries(entries.filter(([, definition]) => isDerivedMeasure(definition))),
+    };
+}
+export function getDerivedMeasure(measures, name) {
+    if (!Object.hasOwn(measures, name))
+        return undefined;
+    const definition = measures[name];
+    return isDerivedMeasure(definition) ? definition : undefined;
+}

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

@@ -1,9 +1,9 @@
-import type { AggregationSpec, DatasetConfig, DimensionDefinition, MeasureDefinition, RelationshipDefinition, SemanticFiltersDefinition } from '../types.js';
-type AnyMeasures = Record<string, MeasureDefinition>;
+import type { AggregationSpec, DatasetConfig, DatasetMeasureDefinition, DimensionDefinition, MeasureDefinition, RelationshipDefinition, SemanticFiltersDefinition } from '../types.js';
+type AnyMeasures = Record<string, DatasetMeasureDefinition>;
 type AnyRelationships = Record<string, RelationshipDefinition>;
 export declare function normalizeDimensions<TDimensions extends Record<string, DimensionDefinition>>(config: DatasetConfig<TDimensions, AnyMeasures, AnyRelationships>): TDimensions;
 export declare function normalizeFilters(dimensions: Record<string, DimensionDefinition>, filters?: SemanticFiltersDefinition): SemanticFiltersDefinition;
-export declare function normalizeMeasures<TMeasures extends Record<string, MeasureDefinition>>(measures: TMeasures | undefined): TMeasures;
+export declare function normalizeMeasures<TMeasures extends Record<string, DatasetMeasureDefinition>>(measures: TMeasures | undefined): TMeasures;
 export declare function normalizeRelationships<TRelationships extends Record<string, RelationshipDefinition>>(relationships: TRelationships | undefined, source: string): TRelationships;
 export declare function measureToAggregationSpec(measureName: string, definition: MeasureDefinition): AggregationSpec;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"dataset-normalization.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-normalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AACrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACzF,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAChE,WAAW,CAEb;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,CAgB3B;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnF,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,CAEX;AAED,wBAAgB,sBAAsB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAClG,aAAa,EAAE,cAAc,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,cAAc,CAgBhB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,GAC5B,eAAe,CAcjB"}
+{"version":3,"file":"dataset-normalization.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-normalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AAC5D,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAE/D,wBAAgB,mBAAmB,CAAC,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACzF,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,EAAE,gBAAgB,CAAC,GAChE,WAAW,CAEb;AAED,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,OAAO,CAAC,EAAE,yBAAyB,GAClC,yBAAyB,CAgB3B;AAED,wBAAgB,iBAAiB,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1F,QAAQ,EAAE,SAAS,GAAG,SAAS,GAC9B,SAAS,CAEX;AAED,wBAAgB,sBAAsB,CAAC,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAClG,aAAa,EAAE,cAAc,GAAG,SAAS,EACzC,MAAM,EAAE,MAAM,GACb,cAAc,CAgBhB;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,GAC5B,eAAe,CAcjB"}

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

@@ -0,0 +1,10 @@
+import type { AnyDatasetInstance, DatasetQuery, DatasetQueryResult, ExecutionContext } from '../types.js';
+/** Apply the same result contract to builder-backed and derived dataset queries. */
+export declare function toDatasetQueryResult(rows: Record<string, unknown>[], options: {
+    dataset: AnyDatasetInstance;
+    query: DatasetQuery;
+    sql: string;
+    timingMs: number;
+    context?: ExecutionContext;
+}): DatasetQueryResult;
+//# sourceMappingURL=dataset-query-result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-query-result.d.ts","sourceRoot":"","sources":["../../src/utils/dataset-query-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAKrB,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,OAAO,EAAE;IACP,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B,GACA,kBAAkB,CAgBpB"}

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

@@ -0,0 +1,20 @@
+import { applyPagination } from './pagination.js';
+import { serializeSemanticMeasureValues } from './semantic-result-serialization.js';
+import { getRuntimeTenantId } from './tenant-runtime.js';
+/** Apply the same result contract to builder-backed and derived dataset queries. */
+export function toDatasetQueryResult(rows, options) {
+    const { dataset, query, sql, timingMs, context } = options;
+    const selectedMeasures = query.measures ?? Object.keys(dataset.measures);
+    const { data, pagination } = applyPagination(rows, query.limit, query.offset);
+    const serializedData = serializeSemanticMeasureValues(data, selectedMeasures);
+    return {
+        data: serializedData,
+        meta: {
+            sql,
+            timingMs,
+            tenant: getRuntimeTenantId(context),
+            rowCount: serializedData.length,
+            pagination,
+        },
+    };
+}

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

@@ -6,9 +6,9 @@ import { validateQualifiedFilter, validateRelationshipTenantRuntime, } from './r
 export function validateDatasetQueryInput(ds, query, context) {
     const errors = [];
     const dimensionNames = Object.keys(ds.dimensions);
-    const measureNames = Object.keys(ds.measures);
+    const measureNames = [...Object.keys(ds.measures), ...Object.keys(ds.derivedMeasures ?? {})];
     const selectedDimensions = query.dimensions ?? [];
-    const selectedMeasures = query.measures ?? measureNames;
+    const selectedMeasures = query.measures ?? Object.keys(ds.measures);
     const filterNames = Object.keys(ds.filters);
     const orderableFields = new Set([
         ...selectedDimensions,

package/dist/utils/derived-measure-validation.d.ts

@@ -0,0 +1,3 @@
+import type { DatasetMeasureDefinition } from '../types.js';
+export declare function validateDerivedMeasures(datasetName: string, measures: Record<string, DatasetMeasureDefinition>): void;
+//# sourceMappingURL=derived-measure-validation.d.ts.map

package/dist/utils/derived-measure-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-measure-validation.d.ts","sourceRoot":"","sources":["../../src/utils/derived-measure-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EAIzB,MAAM,aAAa,CAAC;AAmHrB,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GACjD,IAAI,CAqDN"}

package/dist/utils/derived-measure-validation.js

@@ -0,0 +1,138 @@
+import { isSafeSQLIdentifier } from '../sql-utils.js';
+import { isBaseMeasure, isDerivedMeasure } from './dataset-measures.js';
+function fail(datasetName, measureName, detail) {
+    throw new Error(`Invalid dataset "${datasetName}": derived measure "${measureName}" ${detail}`);
+}
+const BINARY_OPERATORS = new Set(['add', 'subtract', 'multiply', 'divide']);
+const FUNCTION_ARITIES = {
+    nullIfZero: [1],
+    coalesce: [2],
+    round: [2],
+    floor: [1],
+    ceil: [1],
+};
+function collectReferences(datasetName, measureName, expression, references, budget, depth = 0) {
+    budget.nodes += 1;
+    if (depth > 16 || budget.nodes > 256) {
+        fail(datasetName, measureName, 'formula exceeds the expression limits.');
+    }
+    if (typeof expression !== 'object' || expression === null) {
+        fail(datasetName, measureName, 'formula contains an invalid expression.');
+    }
+    switch (expression.kind) {
+        case 'ref':
+            if (typeof expression.name !== 'string' || !isSafeSQLIdentifier(expression.name)) {
+                fail(datasetName, measureName, 'formula contains an invalid input reference.');
+            }
+            references.add(expression.name);
+            return;
+        case 'literal':
+            if (expression.value !== null
+                && typeof expression.value !== 'string'
+                && typeof expression.value !== 'boolean'
+                && (typeof expression.value !== 'number' || !Number.isFinite(expression.value))) {
+                fail(datasetName, measureName, 'formula contains an invalid literal.');
+            }
+            return;
+        case 'binary':
+            if (!BINARY_OPERATORS.has(expression.operator)) {
+                fail(datasetName, measureName, 'formula contains an unsupported binary operator.');
+            }
+            collectReferences(datasetName, measureName, expression.left, references, budget, depth + 1);
+            collectReferences(datasetName, measureName, expression.right, references, budget, depth + 1);
+            return;
+        case 'function':
+            if (!Array.isArray(expression.args)
+                || !FUNCTION_ARITIES[expression.name]?.includes(expression.args.length)) {
+                fail(datasetName, measureName, 'formula contains an unsupported function or arity.');
+            }
+            expression.args.forEach(argument => collectReferences(datasetName, measureName, argument, references, budget, depth + 1));
+            return;
+        default:
+            fail(datasetName, measureName, 'formula contains an unsupported expression kind.');
+    }
+}
+function evaluateFormula(datasetName, measureName, definition) {
+    const aliases = Object.keys(definition.uses);
+    let formula;
+    try {
+        formula = definition.formula(Object.fromEntries(aliases.map(alias => [alias, alias])));
+    }
+    catch (error) {
+        fail(datasetName, measureName, `formula threw: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    if (typeof formula !== 'object'
+        || formula === null
+        || formula.__type !== 'formula_expr'
+        || typeof formula.toSQL !== 'function'
+        || typeof formula.expression !== 'object'
+        || formula.expression === null) {
+        fail(datasetName, measureName, 'formula must return a FormulaExpr.');
+    }
+    return formula;
+}
+function assertAcyclic(datasetName, derivedMeasures) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (name) => {
+        if (visiting.has(name))
+            fail(datasetName, name, 'contains a dependency cycle.');
+        if (visited.has(name))
+            return;
+        if (!Object.hasOwn(derivedMeasures, name))
+            return;
+        const definition = derivedMeasures[name];
+        visiting.add(name);
+        Object.values(definition.uses).forEach(dependency => visit(dependency));
+        visiting.delete(name);
+        visited.add(name);
+    };
+    Object.keys(derivedMeasures).forEach(visit);
+}
+export function validateDerivedMeasures(datasetName, measures) {
+    const baseMeasures = Object.fromEntries(Object.entries(measures).filter(([, definition]) => definition && isBaseMeasure(definition)));
+    const derivedMeasures = Object.fromEntries(Object.entries(measures).filter(([, definition]) => definition && isDerivedMeasure(definition)));
+    for (const [measureName, definition] of Object.entries(derivedMeasures)) {
+        if (!isSafeSQLIdentifier(measureName)) {
+            fail(datasetName, measureName, 'name is not a safe identifier.');
+        }
+        if (typeof definition !== 'object' || definition === null || definition.__type !== 'derived_measure_definition') {
+            fail(datasetName, measureName, 'must be created with measure.derived().');
+        }
+        if (typeof definition.uses !== 'object' || definition.uses === null || Array.isArray(definition.uses)) {
+            fail(datasetName, measureName, 'must declare an input map.');
+        }
+    }
+    assertAcyclic(datasetName, derivedMeasures);
+    for (const [measureName, definition] of Object.entries(derivedMeasures)) {
+        const uses = Object.entries(definition.uses);
+        if (uses.length === 0)
+            fail(datasetName, measureName, 'must reference at least one base measure.');
+        if (typeof definition.formula !== 'function')
+            fail(datasetName, measureName, 'must define a formula function.');
+        for (const [alias, dependencyName] of uses) {
+            if (!isSafeSQLIdentifier(alias))
+                fail(datasetName, measureName, `has invalid input alias "${alias}".`);
+            if (typeof dependencyName !== 'string' || dependencyName.includes('.')) {
+                fail(datasetName, measureName, `references cross-dataset measure "${String(dependencyName)}".`);
+            }
+            if (Object.hasOwn(derivedMeasures, dependencyName)) {
+                fail(datasetName, measureName, `references derived measure "${dependencyName}"; v1 inputs must be base measures.`);
+            }
+            if (!Object.hasOwn(baseMeasures, dependencyName))
+                fail(datasetName, measureName, `references missing measure "${dependencyName}".`);
+        }
+        const references = new Set();
+        collectReferences(datasetName, measureName, evaluateFormula(datasetName, measureName, definition).expression, references, { nodes: 0 });
+        for (const reference of references) {
+            if (!Object.hasOwn(definition.uses, reference)) {
+                fail(datasetName, measureName, `formula references undeclared input alias "${reference}".`);
+            }
+        }
+        for (const [alias] of uses) {
+            if (!references.has(alias)) {
+                fail(datasetName, measureName, `declares unused input alias "${alias}".`);
+            }
+        }
+    }
+}

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

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

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

@@ -4,7 +4,10 @@ function renderMeasureFilterLiteral(value) {
         return 'NULL';
     }
     if (typeof value === 'string') {
-        return `'${value.replace(/'/g, "''")}'`;
+        // ClickHouse also treats backslash as a string escape. Doubling quotes
+        // without escaping backslashes lets a value ending in \\ before a quote
+        // break out of the literal and change the predicate.
+        return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
     }
     if (typeof value === 'number') {
         if (!Number.isFinite(value)) {

package/dist/utils/protocol-metric-expressions.d.ts

@@ -1,6 +1,7 @@
 import { type ProtocolExpression, type ProtocolMetricDerivation } from '@hypequery/protocol';
-import type { AggregationSpec, DerivedMetricSpec, MetricFilter } from '../types.js';
+import type { AggregationSpec, DerivedMeasureDefinition, DerivedMetricSpec, MetricFilter } from '../types.js';
 export declare function filterExpression(filter: MetricFilter): ProtocolExpression;
+export declare function derivedMeasureExpression(definition: DerivedMeasureDefinition): ProtocolExpression;
 export declare function metricExpression(spec: AggregationSpec | DerivedMetricSpec): ProtocolExpression;
 /**
  * The formula in the shape it was authored in, beside the inlined form.

package/dist/utils/protocol-metric-expressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsCpF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}
+{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAGjG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}

package/dist/utils/protocol-metric-expressions.js

@@ -85,6 +85,10 @@ function semanticExpression(expression, references = {}) {
             };
     }
 }
+export function derivedMeasureExpression(definition) {
+    const aliases = Object.fromEntries(Object.keys(definition.uses).map(alias => [alias, alias]));
+    return semanticExpression(definition.formula(aliases).expression);
+}
 export function metricExpression(spec) {
     if (spec.__type === 'aggregation_spec')
         return aggregationExpression(spec);

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

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

package/dist/utils/relationship-fields.js

@@ -64,7 +64,9 @@ export function resolveQualifiedField(ds, name) {
         return null;
     }
     const { relationship: relationshipName, field } = parsed;
-    const relationship = ds.relationships[relationshipName];
+    const relationship = Object.hasOwn(ds.relationships, relationshipName)
+        ? ds.relationships[relationshipName]
+        : undefined;
     if (!relationship) {
         const available = Object.keys(ds.relationships);
         return {
@@ -84,7 +86,9 @@ export function resolveQualifiedField(ds, name) {
         };
     }
     const target = relationship.target();
-    const targetDimension = target.dimensions[field];
+    const targetDimension = Object.hasOwn(target.dimensions, field)
+        ? target.dimensions[field]
+        : undefined;
     if (!targetDimension) {
         const available = Object.keys(target.dimensions);
         return {

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

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

package/dist/utils/relationship-validation.js

@@ -43,9 +43,20 @@ export function validateQualifiedFilter(ds, filter, context) {
     if (!resolution.resolved) {
         return resolution.error;
     }
-    const { target, targetColumn, targetDimension } = resolution.resolved;
+    const { target, targetColumn, targetDimension, targetDimensionName } = resolution.resolved;
     if (getRuntimeTenantPredicate(context) && target.tenantKey && targetColumn === target.tenantKey) {
         return `Cannot filter on tenant field "${filter.field}" when runtime tenancy enforcement is active.`;
     }
+    // A relationship does not turn every target dimension into an exposed
+    // filter. Apply the target's explicit or generated filter allowlist and
+    // operator policy. An explicit filter can override filterable: false.
+    const definition = target.filters[targetDimensionName];
+    if (!definition
+        || definition.field !== targetDimensionName) {
+        return `Filter "${filter.field}" is not exposed by target dataset "${target.name}".`;
+    }
+    if (definition.operators && !definition.operators.includes(filter.operator)) {
+        return `Filter "${filter.field}" does not allow operator "${filter.operator}".`;
+    }
     return validateFilterValue(filter, targetDimension.fieldType);
 }

package/dist/utils/semantic-metadata-validation.d.ts

@@ -1,4 +1,4 @@
-import type { DatasetConfig, DimensionDefinition, MeasureDefinition, RelationshipDefinition, SemanticMetadata } from '../types.js';
+import type { DatasetConfig, DatasetMeasureDefinition, DimensionDefinition, RelationshipDefinition, SemanticMetadata } from '../types.js';
 export declare function validateSemanticMetadata(datasetName: string, location: string, metadata: SemanticMetadata): void;
-export declare function validateDatasetAgentMetadata<TDimensions extends Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition>>(datasetName: string, config: DatasetConfig<TDimensions, TMeasures, TRelationships>): void;
+export declare function validateDatasetAgentMetadata<TDimensions extends Record<string, DimensionDefinition>, TMeasures extends Record<string, DatasetMeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition>>(datasetName: string, config: DatasetConfig<TDimensions, TMeasures, TRelationships>): void;
 //# sourceMappingURL=semantic-metadata-validation.d.ts.map

package/dist/utils/semantic-metadata-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAoBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnD,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CAuDN"}
+{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAoBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1D,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CAuDN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Code-first TypeScript semantic layer for ClickHouse datasets, metrics, multi-tenancy, and AI agents",
   "keywords": [
     "semantic-layer",
@@ -42,7 +42,7 @@
     "dist"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.13.0",
+    "@hypequery/protocol": "^0.14.0",
     "@noble/hashes": "^1.8.0",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.23.5"
@@ -60,7 +60,7 @@
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^3.2.6",
     "vitest": "^3.2.6",
-    "@hypequery/protocol-conformance": "^0.11.1"
+    "@hypequery/protocol-conformance": "^0.11.2"
   },
   "repository": {
     "type": "git",