@hypequery/datasets 0.19.0 → 0.20.0

package/dist/utils/time-measure-source-sql.d.ts

@@ -0,0 +1,22 @@
+import type { AnyDatasetInstance, DatasetQuery, MeasureDefinition, MetricFilter } from '../types.js';
+import type { DatasetQueryExecutionOptions } from '../dataset-query.js';
+export interface TimeMeasureSqlDimension {
+    name: string;
+    alias: string;
+}
+export interface TimeMeasureSqlBase {
+    name: string;
+    definition: MeasureDefinition;
+    value: string;
+    arg: string;
+}
+export interface TimeMeasureSqlSource {
+    ctes: string[];
+    parameters: unknown[];
+    dimensions: TimeMeasureSqlDimension[];
+    bases: TimeMeasureSqlBase[];
+    rowAlias: string;
+}
+/** Isolate authored expressions, joins, tenancy and filters from internal SQL aliases. */
+export declare function buildTimeMeasureSourceSql(ds: AnyDatasetInstance, query: DatasetQuery, baseNames: Iterable<string>, filters: readonly MetricFilter[], options: DatasetQueryExecutionOptions): TimeMeasureSqlSource;
+//# sourceMappingURL=time-measure-source-sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"time-measure-source-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-source-sql.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAUxE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,iBAAiB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0FAA0F;AAC1F,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,kBAAkB,EACtB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC3B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,OAAO,EAAE,4BAA4B,GACpC,oBAAoB,CA2DtB"}

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

@@ -0,0 +1,75 @@
+import { queryTimeSql } from './query-timezone.js';
+import { resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn } from '../query-planner.js';
+import { applyRelationshipJoins, buildRelationshipBuilderContext, qualifyBaseColumn } from './relationship-builder-plan.js';
+import { getRuntimeTenantPredicate } from './tenant-runtime.js';
+import { segmentFilters } from './segments.js';
+import { getBaseMeasure } from './dataset-measures.js';
+import { measureToAggregationSpec } from './dataset-normalization.js';
+import { applyFilteredAggregationExpression } from './filtered-aggregation-sql.js';
+import { assertNoRawSqlUnderJoins } from './sql-under-joins.js';
+/** Isolate authored expressions, joins, tenancy and filters from internal SQL aliases. */
+export function buildTimeMeasureSourceSql(ds, query, baseNames, filters, options) {
+    const bases = [];
+    const joinCtx = buildRelationshipBuilderContext(ds, query, options.context);
+    // Keep source expressions in their own SELECT scope: internal aliases cannot
+    // capture authored SQL identifiers, even if a physical column shares a name.
+    let raw = applyRelationshipJoins(options.builderFactory.table(ds.source), joinCtx);
+    const dims = (query.dimensions ?? []).map((name, i) => ({ name, alias: `_hq_d${i}` }));
+    const sourceParts = [resolveDimensionExpression(ds, ds.timeKey, joinCtx)];
+    for (const dimension of dims)
+        sourceParts.push(resolveDimensionExpression(ds, dimension.name, joinCtx));
+    for (const name of baseNames) {
+        const definition = getBaseMeasure(ds.measures, name);
+        if (!definition)
+            throw new Error(`Window input "${name}" is not a base measure.`);
+        const spec = measureToAggregationSpec(name, definition);
+        if (spec.sql)
+            assertNoRawSqlUnderJoins('measure', name, spec.sql, joinCtx);
+        const value = `_hq_v${bases.length}`;
+        const arg = `_hq_a${bases.length}`;
+        bases.push({ name, definition, value, arg });
+        const expression = spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx);
+        sourceParts.push(applyFilteredAggregationExpression(ds, spec, expression, joinCtx));
+        sourceParts.push(spec.argField ? resolveDimensionExpression(ds, spec.argField, joinCtx) : 'NULL');
+    }
+    // A positional tuple isolates internal names from the source table's names.
+    const sourceIdentifiers = [
+        ...sourceParts,
+        ...Object.keys(ds.dimensions),
+        ...Object.values(ds.dimensions).map(dimension => dimension.sql ?? dimension.column ?? ''),
+        ...Object.values(ds.filters).map(filter => filter.field ?? ''),
+        ds.tenantKey ?? '',
+    ];
+    let rowAlias = '_hq_row';
+    while (sourceIdentifiers.some(text => text.includes(rowAlias)))
+        rowAlias += '_';
+    raw = raw.select([`tuple(${sourceParts.join(', ')}) AS ${rowAlias}`]);
+    const tenant = getRuntimeTenantPredicate(options.context);
+    const tenantColumn = resolveTenantFilterColumn(ds, options.context);
+    if (tenant && tenantColumn)
+        raw = raw.where(qualifyBaseColumn(joinCtx, tenantColumn), tenant.operator, tenant.value);
+    for (const filter of filters) {
+        raw = raw.where(resolveFilterField(ds, filter.field, joinCtx), filter.operator, filter.value);
+    }
+    for (const filter of segmentFilters(ds, query.segments)) {
+        raw = raw.where(resolveDimensionExpression(ds, filter.field, joinCtx), filter.operator, filter.value);
+    }
+    const { sql: rawSql, parameters } = raw.toSQLWithParams();
+    const sourceColumns = [`${queryTimeSql(`assumeNotNull(tupleElement(${rowAlias}, 1))`, query.timezone)} AS _hq_time`];
+    dims.forEach((dimension, i) => sourceColumns.push(`tupleElement(${rowAlias}, ${i + 2}) AS ${dimension.alias}`));
+    bases.forEach((base, i) => {
+        const valuePosition = dims.length + 2 + i * 2;
+        sourceColumns.push(`tupleElement(${rowAlias}, ${valuePosition}) AS ${base.value}`);
+        sourceColumns.push(`tupleElement(${rowAlias}, ${valuePosition + 1}) AS ${base.arg}`);
+    });
+    return {
+        ctes: [
+            `_hq_raw AS (${rawSql})`,
+            `_hq_source AS (SELECT ${sourceColumns.join(', ')} FROM _hq_raw WHERE isNotNull(tupleElement(${rowAlias}, 1)))`,
+        ],
+        parameters,
+        dimensions: dims,
+        bases,
+        rowAlias,
+    };
+}

package/dist/utils/time-measure-values-sql.d.ts

@@ -0,0 +1,20 @@
+import type { TimeGrain, WindowMeasureDefinition } from '../types.js';
+import type { TimeMeasureAxis } from './time-measure-axis.js';
+import type { TimeMeasureSqlBase, TimeMeasureSqlDimension } from './time-measure-source-sql.js';
+export interface TimeMeasureSqlInput {
+    name: string;
+    base: TimeMeasureSqlBase;
+    window?: WindowMeasureDefinition;
+    /** Source rows mapped to output periods before aggregation. */
+    rowsSql: string;
+    /** Extra population CTEs, such as aligned shift ranges. */
+    rowCtes?: string[];
+    /** Shift populations already map exclusively to the requested output series. */
+    restrictToAxis?: boolean;
+}
+export declare function windowScanStartSql(window: WindowMeasureDefinition, grain: TimeGrain): string;
+/** Base measures respect partial endpoints; windows use entire contributing buckets. */
+export declare function windowMeasureRowsSql(window: WindowMeasureDefinition | undefined, axis: TimeMeasureAxis): string;
+/** Fill dimension combinations, aggregate populations, and join measure values onto the series. */
+export declare function buildTimeMeasureValuesSql(dims: readonly TimeMeasureSqlDimension[], inputs: readonly TimeMeasureSqlInput[], axis: TimeMeasureAxis): string[];
+//# sourceMappingURL=time-measure-values-sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"time-measure-values-sql.d.ts","sourceRoot":"","sources":["../../src/utils/time-measure-values-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAKhG,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gFAAgF;IAChF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAwBD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,uBAAuB,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAI5F;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,uBAAuB,GAAG,SAAS,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAG/G;AAED,mGAAmG;AACnG,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,SAAS,uBAAuB,EAAE,EACxC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,IAAI,EAAE,eAAe,GACpB,MAAM,EAAE,CA0CV"}

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

@@ -0,0 +1,87 @@
+import { GRAIN_FUNCTIONS } from '../constants.js';
+import { quoteSQLIdentifier } from '../sql-utils.js';
+import { addTimeSql as add, subtractTimeSql as subtract } from './time-arithmetic-sql.js';
+import { isCountAggregation, windowAggregateSql } from './window-aggregation-sql.js';
+import { calendarBucketGuardSql } from './time-axis-calendar-guard.js';
+/** One row is emitted into each bounded window it contributes to. */
+function contributionSql(window, grain) {
+    const bucket = `${GRAIN_FUNCTIONS[grain]}(_hq_time)`;
+    if (!window)
+        return bucket;
+    if (window.cumulative)
+        return `greatest(${bucket}, _hq_first)`;
+    let count;
+    if (window.trailing) {
+        const end = add(bucket, window.trailing.amount, window.trailing.unit);
+        count = `dateDiff('${grain}', ${bucket}, ${end})`;
+    }
+    else if (window.toDate) {
+        const calendarStart = `${GRAIN_FUNCTIONS[window.toDate]}(_hq_time)`;
+        const end = add(calendarStart, 1, window.toDate);
+        count = `dateDiff('${grain}', ${bucket}, ${end})`;
+    }
+    else {
+        throw new Error('Window measure has no supported mode.');
+    }
+    const fanoutGuard = `throwIf(${count} > 1000, 'A window row contributes to more than 1000 buckets.')`;
+    const calendarGuard = calendarBucketGuardSql(bucket, `${count} + ${fanoutGuard}`, grain);
+    const bucketIndices = `arrayJoin(range(toUInt64(${count} + ${fanoutGuard} + ${calendarGuard})))`;
+    return add(bucket, bucketIndices, grain);
+}
+export function windowScanStartSql(window, grain) {
+    if (window.trailing)
+        return subtract(add('_hq_first', 1, grain), window.trailing.amount, window.trailing.unit);
+    if (window.toDate)
+        return `${GRAIN_FUNCTIONS[window.toDate]}(_hq_first)`;
+    throw new Error('Cumulative windows have unbounded history.');
+}
+/** Base measures respect partial endpoints; windows use entire contributing buckets. */
+export function windowMeasureRowsSql(window, axis) {
+    const range = window ? '' : ` WHERE _hq_time ${axis.lowerInclusive ? '>=' : '>'} _hq_lower AND _hq_time ${axis.upperInclusive ? '<=' : '<'} _hq_upper`;
+    return `SELECT *, ${contributionSql(window, axis.grain)} AS _hq_period FROM _hq_scanned${range}`;
+}
+/** Fill dimension combinations, aggregate populations, and join measure values onto the series. */
+export function buildTimeMeasureValuesSql(dims, inputs, axis) {
+    const ctes = [];
+    const keys = dims.map(dimension => dimension.alias);
+    const combinations = keys.length
+        ? ` CROSS JOIN (SELECT DISTINCT ${keys.join(', ')} FROM _hq_scanned) AS _hq_combinations`
+        : '';
+    ctes.push(`_hq_skeleton AS (SELECT * FROM _hq_series${combinations})`);
+    const projections = ['s._hq_period AS period', ...dims.map(dimension => `s.${dimension.alias} AS ${quoteSQLIdentifier(dimension.name)}`)];
+    const joins = [];
+    let index = 0;
+    for (const input of inputs) {
+        const { name, base, window, rowsSql, rowCtes = [], restrictToAxis = true } = input;
+        const output = `_hq_m${index}`;
+        const fan = `_hq_fan${index}`;
+        const aggregate = `_hq_agg${index}`;
+        ctes.push(...rowCtes, `${fan} AS (${rowsSql})`);
+        // toNullable makes unmatched LEFT JOIN values NULL regardless of join_use_nulls.
+        const expression = windowAggregateSql(base.definition, base.value, base.arg);
+        const groupColumns = `_hq_period${keys.length ? `, ${keys.join(', ')}` : ''}`;
+        const outputRange = restrictToAxis ? ' WHERE _hq_period BETWEEN _hq_first AND _hq_last' : '';
+        const trailingRange = window?.trailing
+            ? ` AND _hq_time >= ${subtract(add('_hq_period', 1, axis.grain), window.trailing.amount, window.trailing.unit)}`
+            : '';
+        const aggregationSql = `SELECT ${groupColumns}, toNullable(${expression}) AS ${output}`
+            + ` FROM ${fan}${outputRange}${trailingRange} GROUP BY ${groupColumns}`;
+        ctes.push(`${aggregate} AS (${aggregationSql})`);
+        const alias = `m${index}`;
+        const condition = [`s._hq_period = ${alias}._hq_period`, ...keys.map(key => `isNotDistinctFrom(s.${key}, ${alias}.${key})`)];
+        joins.push(`LEFT JOIN ${aggregate} AS ${alias} ON ${condition.join(' AND ')}`);
+        let value = `${alias}.${output}`;
+        if (window?.cumulative) {
+            const operation = base.definition.aggregation === 'count' ? 'sum' : base.definition.aggregation;
+            const partition = keys.length ? `PARTITION BY ${keys.map(key => `s.${key}`).join(', ')} ` : '';
+            const frame = `${partition}ORDER BY s._hq_period ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`;
+            value = `${operation}OrNull(${value}) OVER (${frame})`;
+        }
+        if (isCountAggregation(base.definition))
+            value = `coalesce(${value}, 0)`;
+        projections.push(`${value} AS ${quoteSQLIdentifier(name)}`);
+        index++;
+    }
+    ctes.push(`_hq_values AS (SELECT ${projections.join(', ')} FROM _hq_skeleton AS s ${joins.join(' ')})`);
+    return ctes;
+}

package/dist/utils/time-query-measures.d.ts

@@ -0,0 +1,6 @@
+import type { AnyDatasetInstance, DatasetQuery, ShiftMeasureDefinition, WindowMeasureDefinition, DerivedMeasureDefinition, DatasetMeasureDefinition } from '../types.js';
+export type TimeMeasureDefinition = WindowMeasureDefinition | ShiftMeasureDefinition;
+export declare function selectedTimeMeasures(dataset: AnyDatasetInstance, query: DatasetQuery): Map<string, TimeMeasureDefinition>;
+export declare function usesTimeMeasure(definition: DerivedMeasureDefinition, measures: Readonly<Record<string, DatasetMeasureDefinition>>): boolean;
+export declare function rejectTimeMeasuresOnBackend(dataset: AnyDatasetInstance, query: DatasetQuery): void;
+//# sourceMappingURL=time-query-measures.d.ts.map

package/dist/utils/time-query-measures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-query-measures.d.ts","sourceRoot":"","sources":["../../src/utils/time-query-measures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGzK,MAAM,MAAM,qBAAqB,GAAG,uBAAuB,GAAG,sBAAsB,CAAC;AAErF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAYzH;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,wBAAwB,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,GAAG,OAAO,CAE3I;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAOlG"}

package/dist/utils/time-query-measures.js

@@ -0,0 +1,28 @@
+import { getDerivedMeasure, isShiftMeasure, isWindowMeasure } from './dataset-measures.js';
+export function selectedTimeMeasures(dataset, query) {
+    const names = new Set(query.measures ?? []);
+    for (const name of query.measures ?? []) {
+        const derived = getDerivedMeasure(dataset.measures, name);
+        if (derived)
+            Object.values(derived.uses).forEach(input => names.add(input));
+    }
+    const measures = new Map();
+    for (const name of names) {
+        const definition = Object.hasOwn(dataset.measures, name) ? dataset.measures[name] : undefined;
+        if (isWindowMeasure(definition) || isShiftMeasure(definition))
+            measures.set(name, definition);
+    }
+    return measures;
+}
+export function usesTimeMeasure(definition, measures) {
+    return Object.values(definition.uses).some(name => Object.hasOwn(measures, name) && (isWindowMeasure(measures[name]) || isShiftMeasure(measures[name])));
+}
+export function rejectTimeMeasuresOnBackend(dataset, query) {
+    const measures = [...selectedTimeMeasures(dataset, query).values()];
+    if (!measures.length)
+        return;
+    const windows = measures.some(isWindowMeasure);
+    const shifts = measures.some(isShiftMeasure);
+    const subject = windows && shifts ? 'Window and shift' : shifts ? 'Shift' : 'Window';
+    throw new Error(`${subject} dataset measures require the queryBuilder execution path.`);
+}

package/dist/utils/window-aggregation-sql.d.ts

@@ -0,0 +1,5 @@
+import type { MeasureDefinition } from '../types.js';
+/** NULL for an empty non-count population, including nullable measure inputs. */
+export declare function windowAggregateSql(definition: MeasureDefinition, value: string, arg: string): string;
+export declare function isCountAggregation(definition: MeasureDefinition): boolean;
+//# sourceMappingURL=window-aggregation-sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"window-aggregation-sql.d.ts","sourceRoot":"","sources":["../../src/utils/window-aggregation-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAYpG;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAEzE"}

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

@@ -0,0 +1,17 @@
+/** NULL for an empty non-count population, including nullable measure inputs. */
+export function windowAggregateSql(definition, value, arg) {
+    switch (definition.aggregation) {
+        case 'count': return `count(${value})`;
+        case 'countDistinct': return `uniqExact(${value})`;
+        case 'approxCountDistinct': return `uniq(${value})`;
+        case 'percentile': return `quantileOrNull(${definition.level})(${value})`;
+        case 'argMax': return `argMaxOrNull(${value}, ${arg})`;
+        case 'argMin': return `argMinOrNull(${value}, ${arg})`;
+        case 'stddev': return `stddevSampOrNull(${value})`;
+        case 'variance': return `varSampOrNull(${value})`;
+        default: return `${definition.aggregation}OrNull(${value})`;
+    }
+}
+export function isCountAggregation(definition) {
+    return ['count', 'countDistinct', 'approxCountDistinct'].includes(definition.aggregation);
+}

package/dist/utils/window-catalog-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { MeasureTimeInterval, TimeGrain, WindowMeasureDefinition, ShiftMeasureDefinition } from '../types.js';
+/** Additive metadata shared by local catalogs and their agent-safe projection. */
+export interface WindowCatalogMetadata {
+    kind?: 'window' | 'shift';
+    interval?: MeasureTimeInterval;
+    measure?: string;
+    trailing?: MeasureTimeInterval;
+    toDate?: Exclude<TimeGrain, 'minute'>;
+    cumulative?: true;
+    requiresTimeRange?: true;
+    supportedGrains?: TimeGrain[];
+}
+export declare function windowCatalogMetadata(definition: WindowMeasureDefinition | ShiftMeasureDefinition | WindowCatalogMetadata): WindowCatalogMetadata;
+//# sourceMappingURL=window-catalog-metadata.d.ts.map

package/dist/utils/window-catalog-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-catalog-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/window-catalog-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEnH,kFAAkF;AAClF,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACtC,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,iBAAiB,CAAC,EAAE,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,SAAS,EAAE,CAAC;CAC/B;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,uBAAuB,GAAG,sBAAsB,GAAG,qBAAqB,GAAG,qBAAqB,CAgBjJ"}

package/dist/utils/window-catalog-metadata.js

@@ -0,0 +1,17 @@
+export function windowCatalogMetadata(definition) {
+    const grains = 'supportedGrains' in definition && definition.supportedGrains
+        ? { supportedGrains: [...definition.supportedGrains] } : {};
+    if ('interval' in definition && definition.interval) {
+        return { ...grains, kind: 'shift', measure: definition.measure, interval: { ...definition.interval }, requiresTimeRange: true };
+    }
+    if ('__type' in definition || definition.kind === 'window') {
+        return {
+            ...grains,
+            kind: 'window', measure: definition.measure, requiresTimeRange: true,
+            ...('trailing' in definition && definition.trailing ? { trailing: { ...definition.trailing } } : {}),
+            ...('toDate' in definition && definition.toDate ? { toDate: definition.toDate } : {}),
+            ...('cumulative' in definition && definition.cumulative ? { cumulative: true } : {}),
+        };
+    }
+    return definition.requiresTimeRange ? { ...grains, requiresTimeRange: true } : grains;
+}

package/dist/utils/window-measure-definition.d.ts

@@ -0,0 +1,4 @@
+import type { WindowMeasureDefinition, WindowMeasureMode } from '../types.js';
+export type WindowMeasureOptions = Pick<WindowMeasureDefinition, 'label' | 'description' | 'examples' | 'synonyms' | 'format' | 'unit' | 'currency' | 'sensitivity'>;
+export declare function createWindowMeasure<const TMeasureName extends string>(baseMeasure: TMeasureName, window: WindowMeasureMode, options?: WindowMeasureOptions): WindowMeasureDefinition<TMeasureName>;
+//# sourceMappingURL=window-measure-definition.d.ts.map

package/dist/utils/window-measure-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-measure-definition.d.ts","sourceRoot":"","sources":["../../src/utils/window-measure-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG9E,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,uBAAuB,EAC7D,OAAO,GAAG,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC,CAAC;AAEtG,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,YAAY,SAAS,MAAM,EACnE,WAAW,EAAE,YAAY,EACzB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,uBAAuB,CAAC,YAAY,CAAC,CASvC"}

package/dist/utils/window-measure-definition.js

@@ -0,0 +1,11 @@
+import { snapshotSemanticMetadata } from './semantic-metadata.js';
+export function createWindowMeasure(baseMeasure, window, options) {
+    return {
+        __type: 'window_measure_definition',
+        measure: baseMeasure,
+        ...window,
+        ...snapshotSemanticMetadata(options ?? {}),
+        ...(options?.label === undefined ? {} : { label: options.label }),
+        ...(options?.description === undefined ? {} : { description: options.description }),
+    };
+}

package/dist/utils/window-measure-dependencies.d.ts

@@ -0,0 +1,4 @@
+import type { DatasetMeasureDefinition, DerivedMeasureDefinition } from '../types.js';
+/** Whether a derived measure requires window planning to execute. */
+export declare function usesWindowMeasure(definition: DerivedMeasureDefinition, measures: Readonly<Record<string, DatasetMeasureDefinition>>): boolean;
+//# sourceMappingURL=window-measure-dependencies.d.ts.map

package/dist/utils/window-measure-dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-measure-dependencies.d.ts","sourceRoot":"","sources":["../../src/utils/window-measure-dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGtF,qEAAqE;AACrE,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,wBAAwB,EACpC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,GAC3D,OAAO,CAIT"}

package/dist/utils/window-measure-dependencies.js

@@ -0,0 +1,5 @@
+import { isWindowMeasure } from './dataset-measures.js';
+/** Whether a derived measure requires window planning to execute. */
+export function usesWindowMeasure(definition, measures) {
+    return Object.values(definition.uses).some(name => Object.hasOwn(measures, name) && isWindowMeasure(measures[name]));
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"window-measure-validation.d.ts","sourceRoot":"","sources":["../../src/utils/window-measure-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAA8C,MAAM,aAAa,CAAC;AASxG,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,GACjD,IAAI,CAQN"}

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

@@ -0,0 +1,49 @@
+import { SUPPORTED_TIME_GRAINS } from '../constants.js';
+import { isSafeSQLIdentifier } from '../sql-utils.js';
+import { getBaseMeasure, isWindowMeasure } from './dataset-measures.js';
+const TRAILING_UNITS = new Set(SUPPORTED_TIME_GRAINS);
+const TO_DATE_GRAINS = new Set(SUPPORTED_TIME_GRAINS.filter(grain => grain !== 'minute'));
+const CUMULATIVE_AGGREGATIONS = new Set(['sum', 'count', 'min', 'max']);
+export function validateWindowMeasures(datasetName, timeKey, measures) {
+    for (const [name, definition] of Object.entries(measures)) {
+        if (!isWindowMeasure(definition))
+            continue;
+        const problem = windowMeasureProblem(name, definition, timeKey, measures);
+        if (problem) {
+            throw new Error(`Invalid dataset "${datasetName}": window measure "${name}" ${problem}`);
+        }
+    }
+}
+/** Why a window measure is invalid, or undefined when it is valid. */
+function windowMeasureProblem(name, definition, timeKey, measures) {
+    if (!isSafeSQLIdentifier(name))
+        return 'name is not a safe identifier.';
+    if (!timeKey)
+        return 'requires a timeKey.';
+    const base = getBaseMeasure(measures, definition.measure);
+    if (!base)
+        return `must wrap a base measure; "${String(definition.measure)}" is not one.`;
+    return windowModeProblem(definition, base);
+}
+/** Checks that exactly one of trailing / toDate / cumulative is declared, and that it is well formed. */
+function windowModeProblem(definition, base) {
+    const { trailing, toDate, cumulative } = definition;
+    const declaredModes = [trailing, toDate, cumulative].filter(mode => mode !== undefined).length;
+    if (declaredModes !== 1)
+        return 'must declare exactly one window mode.';
+    if (trailing !== undefined) {
+        const valid = typeof trailing === 'object' && trailing !== null
+            && Number.isSafeInteger(trailing.amount) && trailing.amount > 0
+            && TRAILING_UNITS.has(trailing.unit);
+        return valid ? undefined : 'trailing interval needs a positive safe integer and supported unit.';
+    }
+    if (toDate !== undefined) {
+        return TO_DATE_GRAINS.has(toDate) ? undefined : 'toDate needs a supported grain coarser than minute.';
+    }
+    if (cumulative !== true)
+        return 'cumulative must be true.';
+    if (!CUMULATIVE_AGGREGATIONS.has(base.aggregation)) {
+        return `cannot accumulate ${base.aggregation}; use sum, count, min, or max.`;
+    }
+    return undefined;
+}

package/dist/utils/window-query-measures.d.ts

@@ -0,0 +1,4 @@
+import type { AnyDatasetInstance, DatasetQuery, WindowMeasureDefinition } from '../types.js';
+/** Windows selected directly or needed by a selected formula. */
+export declare function selectedWindowMeasures(dataset: AnyDatasetInstance, query: DatasetQuery): Map<string, WindowMeasureDefinition>;
+//# sourceMappingURL=window-query-measures.d.ts.map

package/dist/utils/window-query-measures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-query-measures.d.ts","sourceRoot":"","sources":["../../src/utils/window-query-measures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG7F,iEAAiE;AACjE,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,YAAY,GAClB,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAYtC"}

package/dist/utils/window-query-measures.js

@@ -0,0 +1,17 @@
+import { getDerivedMeasure, isWindowMeasure } from './dataset-measures.js';
+/** Windows selected directly or needed by a selected formula. */
+export function selectedWindowMeasures(dataset, query) {
+    const names = new Set(query.measures ?? []);
+    for (const name of query.measures ?? []) {
+        const derived = getDerivedMeasure(dataset.measures, name);
+        if (derived)
+            Object.values(derived.uses).forEach(input => names.add(input));
+    }
+    const windows = new Map();
+    for (const name of names) {
+        const definition = Object.hasOwn(dataset.measures, name) ? dataset.measures[name] : undefined;
+        if (isWindowMeasure(definition))
+            windows.set(name, definition);
+    }
+    return windows;
+}

package/dist/utils/window-query-signature.d.ts

@@ -0,0 +1,4 @@
+import type { AnyDatasetInstance, DatasetQuery } from '../types.js';
+/** Preserve existing cache keys; add execution dependencies for windows and shifts. */
+export declare function windowQuerySignature(ds: AnyDatasetInstance, query: DatasetQuery): Record<string, unknown>;
+//# sourceMappingURL=window-query-signature.d.ts.map

package/dist/utils/window-query-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-query-signature.d.ts","sourceRoot":"","sources":["../../src/utils/window-query-signature.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMpE,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzG"}

package/dist/utils/window-query-signature.js

@@ -0,0 +1,25 @@
+import { getBaseMeasure, getDerivedMeasure } from './dataset-measures.js';
+import { selectedTimeMeasures } from './time-query-measures.js';
+import { windowCatalogMetadata } from './window-catalog-metadata.js';
+import { measureToAggregationSpec } from './dataset-normalization.js';
+/** Preserve existing cache keys; add execution dependencies for windows and shifts. */
+export function windowQuerySignature(ds, query) {
+    const timeMeasures = selectedTimeMeasures(ds, query);
+    if (!timeMeasures.size)
+        return {};
+    return {
+        windowTimeKey: ds.timeKey,
+        windowTimeDimension: ds.timeKey ? ds.dimensions[ds.timeKey] : undefined,
+        windows: [...timeMeasures].sort(([a], [b]) => a.localeCompare(b)).map(([name, definition]) => {
+            const base = getBaseMeasure(ds.measures, definition.measure);
+            return { name, ...windowCatalogMetadata(definition), base: base ? measureToAggregationSpec(definition.measure, base) : undefined };
+        }),
+        windowFormulas: (query.measures ?? []).flatMap(name => {
+            const derived = getDerivedMeasure(ds.measures, name);
+            if (!derived)
+                return [];
+            const aliases = Object.fromEntries(Object.keys(derived.uses).map(alias => [alias, alias]));
+            return [{ name, uses: derived.uses, expression: derived.formula(aliases).expression }];
+        }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "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.16.0",
+    "@hypequery/protocol": "^0.17.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.13.0"
+    "@hypequery/protocol-conformance": "^0.14.0"
   },
   "repository": {
     "type": "git",