@hypequery/datasets 0.23.1 → 0.24.0

package/dist/protocol-schema-adapter.js

@@ -1,249 +1,16 @@
-import { validateCanonicalValue, validateProtocolSchema, } from '@hypequery/protocol';
-export class ProtocolSchemaAdapterError extends TypeError {
-    path;
-    constructor(message, path = '$') {
-        super(`${message} at ${path}`);
-        this.name = 'ProtocolSchemaAdapterError';
-        this.path = path;
-    }
-}
-function canonicalValue(input, path) {
-    try {
-        if (Array.isArray(input)) {
-            return validateCanonicalValue({
-                $hypequery: {
-                    type: 'array',
-                    version: 1,
-                    values: input.map((item, index) => canonicalValue(item, `${path}[${index}]`)),
-                },
-            });
-        }
-        if (typeof input === 'object' && input !== null) {
-            if ('$hypequery' in input)
-                return validateCanonicalValue(input);
-            const prototype = Object.getPrototypeOf(input);
-            if (prototype !== Object.prototype && prototype !== null) {
-                throw new ProtocolSchemaAdapterError('Default is not portable plain data', path);
-            }
-            return validateCanonicalValue({
-                $hypequery: {
-                    type: 'map',
-                    version: 1,
-                    entries: Object.entries(input)
-                        .sort(([left], [right]) => left.localeCompare(right))
-                        .map(([key, value]) => [key, canonicalValue(value, `${path}.${key}`)]),
-                },
-            });
-        }
-        return validateCanonicalValue(input);
-    }
-    catch (error) {
-        if (error instanceof ProtocolSchemaAdapterError)
-            throw error;
-        throw new ProtocolSchemaAdapterError('Default is not a canonical protocol value', path);
-    }
-}
-function typeName(schema) {
-    return String(schema?._def?.typeName ?? 'Unknown');
-}
-function description(schema) {
-    return typeof schema.description === 'string'
-        ? schema.description
-        : undefined;
-}
-function annotate(schema, result) {
-    const value = description(schema);
-    return value === undefined ? result : { ...result, description: value };
-}
-function convertString(schema, path) {
-    const result = { kind: 'string' };
-    for (const check of schema._def.checks) {
-        switch (check.kind) {
-            case 'min':
-                result.minLength = check.value;
-                break;
-            case 'max':
-                result.maxLength = check.value;
-                break;
-            case 'length':
-                result.minLength = check.value;
-                result.maxLength = check.value;
-                break;
-            default:
-                throw new ProtocolSchemaAdapterError(`Unsupported Zod string check "${String(check.kind)}"`, path);
-        }
-    }
-    return annotate(schema, result);
-}
-function convertNumber(schema, path) {
-    const result = { kind: 'number' };
-    for (const check of schema._def.checks) {
-        switch (check.kind) {
-            case 'int':
-                result.kind = 'integer';
-                break;
-            case 'min':
-                result[check.inclusive === false ? 'exclusiveMinimum' : 'minimum'] = check.value;
-                break;
-            case 'max':
-                result[check.inclusive === false ? 'exclusiveMaximum' : 'maximum'] = check.value;
-                break;
-            case 'finite':
-                break;
-            default:
-                throw new ProtocolSchemaAdapterError(`Unsupported Zod number check "${String(check.kind)}"`, path);
-        }
-    }
-    return annotate(schema, result);
-}
-function isOptionalProperty(schema) {
-    const name = typeName(schema);
-    return name === 'ZodOptional' || name === 'ZodDefault';
-}
-function nativeEnumValues(input) {
-    const values = Object.keys(input)
-        .filter(key => typeof input[String(input[key])] !== 'number')
-        .map(key => input[key]);
-    return [...new Set(values)];
-}
-function isUnconstrainedRecordKey(schema) {
-    if (schema === undefined || typeName(schema) !== 'ZodString')
-        return false;
-    const definition = schema._def;
-    return Array.isArray(definition.checks)
-        && definition.checks.length === 0
-        && definition.coerce !== true;
-}
-function convert(schema, path) {
-    const definition = schema._def;
-    switch (typeName(schema)) {
-        case 'ZodAny':
-        case 'ZodUnknown':
-            return annotate(schema, { kind: 'any' });
-        case 'ZodNever':
-        case 'ZodVoid':
-        case 'ZodUndefined':
-            return annotate(schema, { kind: 'void' });
-        case 'ZodNull':
-            return annotate(schema, { kind: 'null' });
-        case 'ZodBoolean':
-            return annotate(schema, { kind: 'boolean' });
-        case 'ZodString':
-            return convertString(schema, path);
-        case 'ZodNumber':
-            return convertNumber(schema, path);
-        case 'ZodLiteral':
-            return annotate(schema, {
-                kind: 'literal',
-                value: canonicalValue(definition.value, `${path}.value`),
-            });
-        case 'ZodEnum':
-            return annotate(schema, {
-                kind: 'enum',
-                values: [...definition.values],
-            });
-        case 'ZodNativeEnum': {
-            const values = nativeEnumValues(definition.values);
-            return annotate(schema, { kind: 'enum', values });
-        }
-        case 'ZodArray': {
-            const result = {
-                kind: 'array',
-                items: convert(definition.type, `${path}.items`),
-            };
-            if (definition.minLength?.value !== undefined)
-                result.minItems = definition.minLength.value;
-            if (definition.maxLength?.value !== undefined)
-                result.maxItems = definition.maxLength.value;
-            if (definition.exactLength?.value !== undefined) {
-                result.minItems = definition.exactLength.value;
-                result.maxItems = definition.exactLength.value;
-            }
-            return annotate(schema, result);
-        }
-        case 'ZodObject': {
-            if (typeName(definition.catchall) !== 'ZodNever') {
-                throw new ProtocolSchemaAdapterError('Unsupported Zod object catchall', path);
-            }
-            const shape = definition.shape();
-            const properties = Object.fromEntries(Object.entries(shape).map(([name, property]) => [
-                name,
-                convert(property, `${path}.properties.${name}`),
-            ]));
-            const required = Object.entries(shape)
-                .filter(([, property]) => !isOptionalProperty(property))
-                .map(([name]) => name);
-            const unknownProperties = definition.unknownKeys === 'passthrough'
-                ? 'preserve'
-                : definition.unknownKeys === 'strict'
-                    ? 'reject'
-                    : 'strip';
-            return annotate(schema, {
-                kind: 'object',
-                properties,
-                required,
-                unknownProperties,
-            });
-        }
-        case 'ZodRecord':
-            if (!isUnconstrainedRecordKey(definition.keyType)) {
-                throw new ProtocolSchemaAdapterError('Unsupported constrained Zod record key', path);
-            }
-            return annotate(schema, {
-                kind: 'record',
-                values: convert(definition.valueType, `${path}.values`),
-            });
-        case 'ZodUnion':
-            return annotate(schema, {
-                kind: 'union',
-                variants: definition.options.map((option, index) => convert(option, `${path}.variants[${index}]`)),
-            });
-        case 'ZodDiscriminatedUnion':
-            // RFC 0004 has no separate discriminator index. Converting every option
-            // drops only Zod's lookup metadata; each object's literal discriminator
-            // property remains part of its protocol variant.
-            return annotate(schema, {
-                kind: 'union',
-                variants: [...definition.options.values()].map((option, index) => convert(option, `${path}.variants[${index}]`)),
-            });
-        case 'ZodNullable':
-            return annotate(schema, {
-                kind: 'union',
-                variants: [convert(definition.innerType, `${path}.variants[0]`), { kind: 'null' }],
-            });
-        case 'ZodOptional':
-            return annotate(schema, convert(definition.innerType, path));
-        case 'ZodDefault': {
-            const inner = convert(definition.innerType, path);
-            if (inner.kind === 'void') {
-                throw new ProtocolSchemaAdapterError('Void schemas cannot carry defaults', path);
-            }
-            return annotate(schema, {
-                ...inner,
-                default: canonicalValue(definition.defaultValue(), `${path}.default`),
-            });
-        }
-        case 'ZodBranded':
-            return annotate(schema, convert(definition.type, path));
-        case 'ZodReadonly':
-            return annotate(schema, convert(definition.innerType, path));
-        case 'ZodEffects': {
-            const effectType = String(definition.effect?.type ?? 'unknown');
-            if (effectType !== 'refinement') {
-                throw new ProtocolSchemaAdapterError(`Unsupported Zod effect "${effectType}"`, path);
-            }
-            // A refinement preserves the wrapped schema's input and output shape.
-            // The rule itself remains enforced by Zod, but cannot be advertised by
-            // ProtocolSchema (for example, a cross-field selection requirement).
-            return annotate(schema, convert(definition.schema, path));
-        }
-        default:
-            throw new ProtocolSchemaAdapterError(`Unsupported Zod type "${typeName(schema)}"`, path);
-    }
-}
-/** Converts the portable subset of a Zod v3 schema into RFC 0004. */
+import { validateProtocolSchema } from '@hypequery/protocol';
+import { isZod4Schema } from './utils/zod-schema-version.js';
+import { convertZodV3Schema } from './utils/zod-v3-protocol-schema.js';
+import { convertZodV4Schema } from './utils/zod-v4-protocol-schema.js';
+export { ProtocolSchemaAdapterError } from './utils/protocol-schema-conversion.js';
+/**
+ * Converts the portable subset of a Zod schema into RFC 0004. Accepts schemas
+ * from Zod 3 or Zod 4, so a caller's own copy of Zod need not match ours.
+ */
 export function zodToProtocolSchema(schema, path = '$') {
     if (schema === undefined)
         return validateProtocolSchema({ kind: 'any' });
-    return validateProtocolSchema(convert(schema, path));
+    return validateProtocolSchema(isZod4Schema(schema)
+        ? convertZodV4Schema(schema, path)
+        : convertZodV3Schema(schema, path));
 }

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

@@ -9,7 +9,14 @@
  * This keeps @hypequery/serve DB-agnostic while enabling first-class builder usage.
  */
 import type { DatasetSqlDialect } from './dataset-sql-dialect.js';
-/** A chainable query builder instance (what `.table(name)` returns). */
+/**
+ * A chainable query builder instance (what `.table(name)` returns).
+ *
+ * Aliases and column arguments the datasets planner passes are SQL text as
+ * the datasets dialect spells it: generated output aliases arrive already
+ * quoted (for example `` `revenue` ``). Insert them verbatim; do not quote
+ * them again.
+ */
 export interface QueryBuilderLike {
     select(columns: string[] | string): QueryBuilderLike;
     sum(column: string, alias?: string): QueryBuilderLike;
@@ -30,7 +37,21 @@ export interface QueryBuilderLike {
     variance?(column: string, alias?: string): QueryBuilderLike;
     /** Estimated number of distinct non-NULL values of `column`. */
     approxCountDistinct?(column: string, alias?: string): QueryBuilderLike;
+    /**
+     * Finalize the aggregate states in `column` with `stateFunction`'s `-Merge`
+     * combinator (ClickHouse `uniqMerge(users)`). `stateFunction` is one of the
+     * datasets allowlist. `@hypequery/clickhouse` implements it from the release
+     * that adds `mergeState`.
+     */
+    mergeState?(stateFunction: string, column: string, alias?: string): QueryBuilderLike;
     where(column: string, operator: string, value: unknown): QueryBuilderLike;
+    /**
+     * Optional: read the table source with ClickHouse `FINAL`. Needed only for
+     * datasets declared `final: true`; querying one through a builder without
+     * it is refused rather than run without `FINAL`, which would count every
+     * unmerged row version.
+     */
+    final?(): QueryBuilderLike;
     leftJoin(table: string, leftColumn: string, rightColumn: string, alias?: string, on?: QueryBuilderJoinCondition | QueryBuilderJoinCondition[]): QueryBuilderLike;
     /**
      * Single-match LEFT JOIN (ClickHouse `LEFT ANY JOIN`). Required to query
@@ -55,6 +76,16 @@ export interface QueryBuilderLike {
         sql: string;
         parameters: unknown[];
     };
+    /**
+     * Optional: compile with each bound value written through `placeholder`,
+     * called once per value in SQL order, its result inserted verbatim. Lets
+     * the datasets planner own placeholder spelling and numbering when it
+     * embeds this statement in a larger one. Required on datasets dialects that
+     * number placeholders (such as Postgres `$n`) and only called there:
+     * positional `?` dialects keep using `toSQLWithParams`, unchanged.
+     * `@hypequery/clickhouse` implements it from 2.14.0.
+     */
+    toSQLWithPlaceholders?(placeholder: (value: unknown) => string): string;
     execute<T = Record<string, unknown>>(options?: {
         abortSignal?: AbortSignal;
     }): Promise<T[]>;

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

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

package/dist/query-planner.d.ts

@@ -1,20 +1,29 @@
 import type { AggregationSpec, AnyDatasetInstance, ExecutionContext, MeasureDefinition, MetricOrderBy, TimeGrain } from "./types.js";
 import type { QueryBuilderLike } from "./query-builder-protocol.js";
-import type { DatasetSqlDialect } from './dataset-sql-dialect.js';
+import type { DatasetSqlDialectRules } from './dataset-sql-dialect.js';
 import { type RelationshipBuilderContext } from './utils/relationship-builder-plan.js';
 type DatasetShape = AnyDatasetInstance;
 export declare function resolveDimensionExpression(ds: DatasetShape, dimensionName: string, joinCtx?: RelationshipBuilderContext): string;
 export declare function resolveFilterField(ds: DatasetShape, filterField: string, joinCtx?: RelationshipBuilderContext): string;
-export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined, joinCtx?: RelationshipBuilderContext, timezone?: string, dialect?: DatasetSqlDialect): {
+export declare function buildDimensionSelectionPlan(ds: DatasetShape, dimensions: string[], grain: TimeGrain | undefined, joinCtx: RelationshipBuilderContext | undefined, timezone: string | undefined, dialect: DatasetSqlDialectRules): {
     selectParts: string[];
     groupByParts: string[];
 };
-export declare function applyAggregationSpec(qb: QueryBuilderLike, ds: DatasetShape, spec: AggregationSpec, alias: string, joinCtx?: RelationshipBuilderContext, expressions?: {
+export declare function applyAggregationSpec(qb: QueryBuilderLike, ds: DatasetShape, spec: AggregationSpec, name: string, joinCtx: RelationshipBuilderContext | undefined, dialect: DatasetSqlDialectRules, expressions?: {
     field: string;
     arg?: string;
 }): QueryBuilderLike;
-export declare function applyMeasureDefinition(qb: QueryBuilderLike, ds: DatasetShape, name: string, definition: MeasureDefinition, joinCtx?: RelationshipBuilderContext): QueryBuilderLike;
-export declare function appendOrderLimitOffset(qb: QueryBuilderLike, orderBy: MetricOrderBy[] | undefined, grain: TimeGrain | undefined, limit?: number, offset?: number, joinCtx?: RelationshipBuilderContext, dialect?: DatasetSqlDialect): QueryBuilderLike;
+export declare function applyMeasureDefinition(qb: QueryBuilderLike, ds: DatasetShape, name: string, definition: MeasureDefinition, joinCtx: RelationshipBuilderContext | undefined, dialect: DatasetSqlDialectRules): QueryBuilderLike;
+/**
+ * Appends ORDER BY, LIMIT and OFFSET. Under joins, an order on a selected
+ * qualified dimension repeats its guarded expression (the GROUP BY key) rather
+ * than naming the alias, which the engine may resolve to the raw joined column;
+ * any other qualified order (a related measure) sorts by its quoted alias.
+ */
+export declare function appendOrderLimitOffset(qb: QueryBuilderLike, orderBy: MetricOrderBy[] | undefined, grain: TimeGrain | undefined, limit: number | undefined, offset: number | undefined, joinCtx: RelationshipBuilderContext | undefined, dialect: DatasetSqlDialectRules, selection?: {
+    ds: DatasetShape;
+    dimensions: readonly string[];
+}): QueryBuilderLike;
 export declare function resolveTenantFilterColumn(ds: DatasetShape, context?: ExecutionContext): string | undefined;
 export {};
 //# sourceMappingURL=query-planner.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"query-planner.d.ts","sourceRoot":"","sources":["../src/query-planner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAIpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAI9C,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAEvC,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAMR;AAED,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,OAAO,CAAC,EAAE,0BAA0B,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,GAAE,iBAA+C,GACvD;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAmCnD;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,0BAA0B,EACpC,WAAW,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,gBAAgB,CAqElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,EAC7B,OAAO,CAAC,EAAE,0BAA0B,GACnC,gBAAgB,CAElB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,0BAA0B,EACpC,OAAO,GAAE,iBAA+C,GACvD,gBAAgB,CAoBlB;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB"}
+{"version":3,"file":"query-planner.d.ts","sourceRoot":"","sources":["../src/query-planner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAIpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,sCAAsC,CAAC;AAK9C,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAEvC,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAUR;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CAMR;AAED,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,sBAAsB,GAC9B;IAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAkCnD;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,OAAO,EAAE,sBAAsB,EAC/B,WAAW,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,gBAAgB,CAmFlB;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,EAC7B,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,OAAO,EAAE,sBAAsB,GAC9B,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,gBAAgB,EACpB,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,SAAS,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,0BAA0B,GAAG,SAAS,EAC/C,OAAO,EAAE,sBAAsB,EAC/B,SAAS,CAAC,EAAE;IAAE,EAAE,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC9D,gBAAgB,CAsBlB;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB"}

package/dist/query-planner.js

@@ -1,17 +1,17 @@
 import { semanticOrderDirection } from './utils/semantic-query-syntax.js';
 import { queryTimeSql } from './utils/query-timezone.js';
 import { assertNoRawSqlUnderJoins } from './utils/sql-under-joins.js';
-import { GRAIN_FUNCTIONS } from "./constants.js";
+import { isSupportedTimeGrain } from "./constants.js";
 import { applyFilteredAggregationExpression } from './utils/filtered-aggregation-sql.js';
 import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
-import { clickhouseDatasetSqlDialect } from './utils/clickhouse-dataset-sql-dialect.js';
 import { isQualifiedField } from './utils/relationship-fields.js';
-import { qualifyBaseColumn, resolveQualifiedColumn, } from './utils/relationship-builder-plan.js';
+import { qualifyBaseColumn, resolveQualifiedExpression, } from './utils/relationship-builder-plan.js';
 import { measureToAggregationSpec } from './utils/dataset-normalization.js';
 import { validatePercentileLevel } from './measure.js';
+import { assertAggregateStateFunction } from './utils/aggregate-state-functions.js';
 export function resolveDimensionExpression(ds, dimensionName, joinCtx) {
     if (joinCtx && isQualifiedField(dimensionName)) {
-        return resolveQualifiedColumn(ds, dimensionName);
+        return resolveQualifiedExpression(ds, dimensionName, joinCtx);
     }
     const definition = ds.dimensions[dimensionName];
     if (definition?.sql) {
@@ -22,50 +22,51 @@ export function resolveDimensionExpression(ds, dimensionName, joinCtx) {
 }
 export function resolveFilterField(ds, filterField, joinCtx) {
     if (joinCtx && isQualifiedField(filterField)) {
-        return resolveQualifiedColumn(ds, filterField);
+        return resolveQualifiedExpression(ds, filterField, joinCtx);
     }
     const resolvedField = ds.filters[filterField]?.field ?? filterField;
     return resolveDimensionExpression(ds, resolvedField, joinCtx);
 }
-export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx, timezone, dialect = clickhouseDatasetSqlDialect) {
+export function buildDimensionSelectionPlan(ds, dimensions, grain, joinCtx, timezone, dialect) {
     const selectParts = [];
     const groupByParts = new Set();
     if (grain) {
-        const fn = GRAIN_FUNCTIONS[grain];
-        if (!fn) {
+        if (!isSupportedTimeGrain(grain)) {
             throw new Error(`Unsupported time grain "${grain}".`);
         }
         const time = resolveDimensionExpression(ds, String(ds.timeKey), joinCtx);
-        selectParts.push(`${fn}(${queryTimeSql(time, timezone)}) AS period`);
-        groupByParts.add("period");
+        const period = dialect.quoteIdentifier('period');
+        selectParts.push(`${dialect.truncateTime(queryTimeSql(dialect, time, timezone), grain)} AS ${period}`);
+        groupByParts.add(period);
     }
     for (const dimensionName of dimensions) {
         const expression = resolveDimensionExpression(ds, dimensionName, joinCtx);
-        if (joinCtx) {
-            // With joins in scope, every selection is table-qualified and aliased so
-            // grouping/ordering can reference the alias unambiguously.
-            const alias = isQualifiedField(dimensionName)
-                ? dialect.quoteIdentifier(dimensionName)
-                : dimensionName;
-            selectParts.push(`${expression} AS ${alias}`);
-            groupByParts.add(alias);
-        }
-        else if (expression === dimensionName) {
+        // Every generated alias is quoted: reserved words and engines that fold
+        // unquoted case (Postgres) must keep the semantic name. With joins in
+        // scope every selection is table-qualified, so it is always aliased.
+        if (!joinCtx && expression === dimensionName) {
             selectParts.push(dimensionName);
             groupByParts.add(dimensionName);
         }
         else {
-            selectParts.push(`${expression} AS ${dimensionName}`);
-            groupByParts.add(dimensionName);
+            const alias = dialect.quoteIdentifier(dimensionName);
+            selectParts.push(`${expression} AS ${alias}`);
+            // A qualified alias (`customer.tier`) can resolve to the physical joined
+            // column, so group on its guarded expression: the match marker stays
+            // part of the key whatever the engine's alias-resolution rules.
+            groupByParts.add(joinCtx && isQualifiedField(dimensionName) ? expression : alias);
         }
     }
     return { selectParts, groupByParts: Array.from(groupByParts) };
 }
-export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions) {
+export function applyAggregationSpec(qb, ds, spec, name, joinCtx, dialect, expressions) {
+    // The semantic name is the output alias, quoted so it survives reserved
+    // words and case folding; messages keep the unquoted name.
+    const alias = dialect.quoteIdentifier(name);
     if (spec.sql) {
-        assertNoRawSqlUnderJoins('measure', alias, spec.sql, joinCtx);
+        assertNoRawSqlUnderJoins('measure', name, spec.sql, joinCtx);
     }
-    const fieldOrExpr = expressions?.field ?? applyFilteredAggregationExpression(ds, spec, spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx), joinCtx);
+    const fieldOrExpr = expressions?.field ?? applyFilteredAggregationExpression(ds, spec, spec.sql ?? resolveDimensionExpression(ds, spec.field, joinCtx), joinCtx, dialect);
     switch (spec.aggregation) {
         case "sum":
             return qb.sum(fieldOrExpr, alias);
@@ -82,7 +83,7 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
         case "argMax":
         case "argMin": {
             if (!spec.argField) {
-                throw new Error(`Aggregation "${spec.aggregation}" for "${alias}" requires an argField ("by" column).`);
+                throw new Error(`Aggregation "${spec.aggregation}" for "${name}" requires an argField ("by" column).`);
             }
             const argExpr = expressions?.arg ?? resolveDimensionExpression(ds, spec.argField, joinCtx);
             if (spec.aggregation === "argMax") {
@@ -98,7 +99,7 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
         }
         case "percentile": {
             if (spec.level == null) {
-                throw new Error(`Aggregation "percentile" for "${alias}" requires a level.`);
+                throw new Error(`Aggregation "percentile" for "${name}" requires a level.`);
             }
             validatePercentileLevel(spec.level);
             if (!qb.quantile) {
@@ -111,6 +112,16 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
                 throw new Error('Query builder does not support approxCountDistinct aggregations.');
             }
             return qb.approxCountDistinct(fieldOrExpr, alias);
+        case "merge": {
+            assertAggregateStateFunction(spec.stateFunction, `Measure "${name}"`);
+            if (spec.filters?.length) {
+                throw new Error(`Measure filters are not supported on merge aggregations ("${name}").`);
+            }
+            if (!qb.mergeState) {
+                throw new Error('Query builder does not support merge aggregations (mergeState).');
+            }
+            return qb.mergeState(spec.stateFunction, fieldOrExpr, alias);
+        }
         case "stddev":
             if (!qb.stddev) {
                 throw new Error('Query builder does not support stddev aggregations.');
@@ -125,20 +136,28 @@ export function applyAggregationSpec(qb, ds, spec, alias, joinCtx, expressions)
             throw new Error(`Unknown aggregation type: ${spec.aggregation}`);
     }
 }
-export function applyMeasureDefinition(qb, ds, name, definition, joinCtx) {
-    return applyAggregationSpec(qb, ds, measureToAggregationSpec(name, definition), name, joinCtx);
+export function applyMeasureDefinition(qb, ds, name, definition, joinCtx, dialect) {
+    return applyAggregationSpec(qb, ds, measureToAggregationSpec(name, definition), name, joinCtx, dialect);
 }
-export function appendOrderLimitOffset(qb, orderBy, grain, limit, offset, joinCtx, dialect = clickhouseDatasetSqlDialect) {
+/**
+ * Appends ORDER BY, LIMIT and OFFSET. Under joins, an order on a selected
+ * qualified dimension repeats its guarded expression (the GROUP BY key) rather
+ * than naming the alias, which the engine may resolve to the raw joined column;
+ * any other qualified order (a related measure) sorts by its quoted alias.
+ */
+export function appendOrderLimitOffset(qb, orderBy, grain, limit, offset, joinCtx, dialect, selection) {
     if (orderBy && orderBy.length > 0) {
         for (const order of orderBy) {
-            const column = joinCtx && isQualifiedField(order.field)
-                ? dialect.quoteIdentifier(order.field)
-                : order.field;
+            // A selected related dimension orders by its guarded expression, for the
+            // same alias-resolution reason it groups by it.
+            const column = joinCtx && isQualifiedField(order.field) && selection?.dimensions.includes(order.field)
+                ? resolveDimensionExpression(selection.ds, order.field, joinCtx)
+                : dialect.quoteIdentifier(order.field);
             qb = qb.orderBy(column, semanticOrderDirection(order.direction));
         }
     }
     else if (grain) {
-        qb = qb.orderBy("period", "ASC");
+        qb = qb.orderBy(dialect.quoteIdentifier("period"), "ASC");
     }
     if (limit != null) {
         qb = qb.limit(limit);

package/dist/relationship-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-check.d.ts","sourceRoot":"","sources":["../src/relationship-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAyB,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEnG,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,YAAY,EAAE,wBAAwB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAqCnC"}
+{"version":3,"file":"relationship-check.d.ts","sourceRoot":"","sources":["../src/relationship-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAyB,KAAK,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGnG,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,YAAY,EAAE,wBAAwB,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAqCnC"}

package/dist/relationship-check.js

@@ -16,8 +16,10 @@
  * }
  * ```
  */
+import { datasetSourceBuilder } from './utils/dataset-source.js';
 import { toQueryBuilderFactory } from './query-builder-protocol.js';
 import { getRuntimeTenantPredicate, validateTenantRuntime } from './utils/tenant-runtime.js';
+import { resolveDatasetSqlDialect } from './utils/dataset-sql-dialect.js';
 import { listToOneRelationships, readCount, relationshipKeyIssue, } from './utils/relationship-key-check.js';
 const ROWS_ALIAS = '__hq_rows';
 const KEYS_ALIAS = '__hq_keys';
@@ -29,6 +31,7 @@ const KEYS_ALIAS = '__hq_keys';
  */
 export async function checkRelationships(ds, options) {
     const factory = toQueryBuilderFactory(options.queryBuilder);
+    const dialect = resolveDatasetSqlDialect(factory);
     const tenantPredicate = getRuntimeTenantPredicate(options.context);
     const entries = listToOneRelationships(ds, options.relationships);
     const issues = [];
@@ -37,10 +40,9 @@ export async function checkRelationships(ds, options) {
         if (tenantError) {
             throw new Error(`Cannot check relationship "${entry.relationship}": ${tenantError}`);
         }
-        let qb = factory
-            .table(entry.target.source)
+        let qb = datasetSourceBuilder(factory, entry.target)
             .count(entry.column, ROWS_ALIAS)
-            .countDistinct(entry.columns ? `tuple(${entry.columns.join(', ')})` : entry.column, KEYS_ALIAS);
+            .countDistinct(entry.columns ? dialect.packRow(entry.columns) : entry.column, KEYS_ALIAS);
         if (entry.columns) {
             for (const column of entry.columns)
                 qb = qb.where(column, 'isNotNull', undefined);

package/dist/schemas.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@hypequery/datasets/schemas`: Zod-backed query schemas and agent tools.
+ *
+ * Everything here builds or reads Zod schemas. It lives apart from the root
+ * entry so that defining and querying datasets never loads Zod. In 1.0 the
+ * root entry stops re-exporting these and Zod becomes an optional peer
+ * dependency needed only by this entry.
+ */
+export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
+export type { AISDKToolDefinition, DatasetToolAnalytics, DatasetToolMode, GenerateDatasetToolsOptions, JsonSchema, McpToolDefinition, OpenAIToolDefinition, SemanticToolDefinition, } from './tools.js';
+export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, buildDatasetInputProtocolSchema, buildMetricInputProtocolSchema, } from './semantic-query-schema.js';
+export type { CanonicalSemanticQuerySchemas, SemanticMetricQueryContract, SemanticQuerySchemaLimits, SemanticQuerySchemaOptions, SemanticQuerySchemaSource, } from './semantic-query-schema.js';
+export { ProtocolSchemaAdapterError, zodToProtocolSchema } from './protocol-schema-adapter.js';
+export type { AnyZodSchema } from './utils/zod-schema-version.js';
+export { buildClientContractQuerySchemas } from './client-contract/query-schema.js';
+export type { ClientContractQuerySchemas, ClientEndpointQuerySchema } from './client-contract/query-schema.js';
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,2BAA2B,EAC3B,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,kCAAkC,EAClC,oBAAoB,EACpB,oCAAoC,EACpC,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGlE,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,YAAY,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,16 @@
+/**
+ * `@hypequery/datasets/schemas`: Zod-backed query schemas and agent tools.
+ *
+ * Everything here builds or reads Zod schemas. It lives apart from the root
+ * entry so that defining and querying datasets never loads Zod. In 1.0 the
+ * root entry stops re-exporting these and Zod becomes an optional peer
+ * dependency needed only by this entry.
+ */
+// Agent/tool metadata
+export { generateDatasetTools, toOpenAITools, toAISDKTools, toMcpTools, } from './tools.js';
+// Canonical semantic query schemas shared by Serve, MCP, and agent adapters.
+export { buildDatasetInputSchema, buildMetricInputSchema, buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, DEFAULT_SEMANTIC_QUERY_SCHEMA_LIMITS, buildDatasetInputProtocolSchema, buildMetricInputProtocolSchema, } from './semantic-query-schema.js';
+// Zod to RFC 0004 protocol schemas, for Zod 3 or Zod 4 input.
+export { ProtocolSchemaAdapterError, zodToProtocolSchema } from './protocol-schema-adapter.js';
+// Client-contract query schemas.
+export { buildClientContractQuerySchemas } from './client-contract/query-schema.js';

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

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