@hypequery/datasets 0.17.1 → 0.19.0

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

@@ -0,0 +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;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAkCnC"}

package/dist/relationship-check.js

@@ -0,0 +1,59 @@
+/**
+ * Verifies declared to-one relationships against the data.
+ *
+ * `belongsTo` and `hasOne` are declarations: nothing at query time proves the
+ * target join column is unique. Relationship joins are single-match, so a
+ * duplicate key cannot inflate an aggregate, but the join then takes an
+ * arbitrary one of the matching rows and grouped values drift without any
+ * error. `checkRelationships` counts rows and distinct keys on each target so a
+ * mis-declaration is caught in CI or at deploy time rather than in a report.
+ *
+ * @example
+ * ```ts
+ * const result = await checkRelationships(Orders, { queryBuilder: db });
+ * if (!result.ok) {
+ *   throw new Error(result.issues.map((issue) => issue.message).join('\n'));
+ * }
+ * ```
+ */
+import { toQueryBuilderFactory } from './query-builder-protocol.js';
+import { getRuntimeTenantPredicate, validateTenantRuntime } from './utils/tenant-runtime.js';
+import { listToOneRelationships, readCount, relationshipKeyIssue, } from './utils/relationship-key-check.js';
+const ROWS_ALIAS = '__hq_rows';
+const KEYS_ALIAS = '__hq_keys';
+/**
+ * Checks that the target join column of each `belongsTo` and `hasOne`
+ * relationship on `ds` is unique. NULL keys are ignored because they never
+ * match a join. `hasMany` relationships are skipped.
+ */
+export async function checkRelationships(ds, options) {
+    const factory = toQueryBuilderFactory(options.queryBuilder);
+    const tenantPredicate = getRuntimeTenantPredicate(options.context);
+    const entries = listToOneRelationships(ds, options.relationships);
+    const issues = [];
+    for (const entry of entries) {
+        const tenantError = validateTenantRuntime(entry.target, options.context);
+        if (tenantError) {
+            throw new Error(`Cannot check relationship "${entry.relationship}": ${tenantError}`);
+        }
+        let qb = factory
+            .table(entry.target.source)
+            .count(entry.column, ROWS_ALIAS)
+            .countDistinct(entry.column, KEYS_ALIAS);
+        if (entry.target.tenantKey && tenantPredicate) {
+            qb = qb.where(entry.target.tenantKey, tenantPredicate.operator, tenantPredicate.value);
+        }
+        const [row] = await qb.execute({
+            abortSignal: options.context?.abortSignal,
+        });
+        const issue = relationshipKeyIssue(entry, readCount(row?.[ROWS_ALIAS]), readCount(row?.[KEYS_ALIAS]));
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        checked: entries.map((entry) => entry.relationship),
+        issues,
+    };
+}

package/dist/relationships.d.ts

@@ -10,15 +10,14 @@
  * is not addressable through a relationship, so there are no cross-dataset
  * metrics.
  *
- * Note that the `kind` passed here is a declaration, not something checked
- * against the data — there is no uniqueness concept in the model, so nothing
- * verifies that a `belongsTo` target column really is unique. What a
- * mis-declaration costs depends on the builder. One that implements the
- * optional `leftAnyJoin` (ClickHouse `LEFT ANY JOIN`) takes at most one target
- * row per base row, so the aggregate cannot inflate — it just silently picks an
- * arbitrary one of the matches. A builder without it falls back to `leftJoin`,
- * where duplicate target keys fan out and do inflate the aggregate. Either way
- * the declaration has to be right.
+ * Note that the `kind` passed here is a declaration, not something checked at
+ * query time. Joins are single-match (`leftAnyJoin`, ClickHouse
+ * `LEFT ANY JOIN`), so a mis-declared to-one relationship cannot inflate an
+ * aggregate, but it does make the join pick an arbitrary one of the matching
+ * target rows. Builders without `leftAnyJoin` are refused rather than
+ * downgraded to a fan-out `leftJoin`. The in-memory backend refuses duplicate
+ * target keys outright, and `checkRelationships()` reports them against a live
+ * database, so a wrong declaration can be caught before it skews results.
  *
  * @example
  * ```ts
@@ -29,7 +28,8 @@
  *     customerId: dimension.string({ column: "customer_id" }),
  *   },
  *   relationships: {
- *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
+ *     // Join keys are source columns, not dimension names.
+ *     customer: belongsTo(() => Customers, { from: "customer_id", to: "id" }),
  *   },
  * });
  *

package/dist/relationships.js

@@ -10,15 +10,14 @@
  * is not addressable through a relationship, so there are no cross-dataset
  * metrics.
  *
- * Note that the `kind` passed here is a declaration, not something checked
- * against the data — there is no uniqueness concept in the model, so nothing
- * verifies that a `belongsTo` target column really is unique. What a
- * mis-declaration costs depends on the builder. One that implements the
- * optional `leftAnyJoin` (ClickHouse `LEFT ANY JOIN`) takes at most one target
- * row per base row, so the aggregate cannot inflate — it just silently picks an
- * arbitrary one of the matches. A builder without it falls back to `leftJoin`,
- * where duplicate target keys fan out and do inflate the aggregate. Either way
- * the declaration has to be right.
+ * Note that the `kind` passed here is a declaration, not something checked at
+ * query time. Joins are single-match (`leftAnyJoin`, ClickHouse
+ * `LEFT ANY JOIN`), so a mis-declared to-one relationship cannot inflate an
+ * aggregate, but it does make the join pick an arbitrary one of the matching
+ * target rows. Builders without `leftAnyJoin` are refused rather than
+ * downgraded to a fan-out `leftJoin`. The in-memory backend refuses duplicate
+ * target keys outright, and `checkRelationships()` reports them against a live
+ * database, so a wrong declaration can be caught before it skews results.
  *
  * @example
  * ```ts
@@ -29,7 +28,8 @@
  *     customerId: dimension.string({ column: "customer_id" }),
  *   },
  *   relationships: {
- *     customer: belongsTo(() => Customers, { from: "customerId", to: "id" }),
+ *     // Join keys are source columns, not dimension names.
+ *     customer: belongsTo(() => Customers, { from: "customer_id", to: "id" }),
  *   },
  * });
  *

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

@@ -1 +1 @@
-{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AACA,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;AAyL5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAgBV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAYV"}
+{"version":3,"file":"semantic-planner.d.ts","sourceRoot":"","sources":["../src/semantic-planner.ts"],"names":[],"mappings":"AACA,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;AA6L5B,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,kBAAkB,EACtB,KAAK,GAAE,YAAiB,EACxB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAgBV;AA2FD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,GAAG,gBAAgB,EACpC,KAAK,GAAE,WAAgB,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,QAAQ,CAYV"}

package/dist/semantic-planner.js

@@ -4,6 +4,7 @@ import { validateDatasetQuery } from './dataset-query.js';
 import { isSupportedTimeGrain } from './constants.js';
 import { getRuntimeTenantPredicate } from './utils/tenant-runtime.js';
 import { isQualifiedField, resolveQualifiedField } from './utils/relationship-fields.js';
+import { segmentFilters } from './utils/segments.js';
 function resolveField(ds, field) {
     const dimension = ds.dimensions[field];
     if (dimension?.sql) {
@@ -135,7 +136,10 @@ function aggregatePlan(ds, query, aggregations, context) {
         source: ds.source,
         dimensions: dimensionsForQuery(ds, query.dimensions),
         aggregations,
-        filters: normalizeFilters(ds, query.filters),
+        filters: [
+            ...normalizeFilters(ds, query.filters),
+            ...segmentFilters(ds, query.segments).map(filter => ({ ...filter, field: resolveField(ds, filter.field) })),
+        ],
         grain: grainForQuery(ds, query.by),
         orderBy: query.orderBy,
         limit: query.limit,

package/dist/semantic-query-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-query-schema.d.ts","sourceRoot":"","sources":["../src/semantic-query-schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,iFAAiF;IACjF,UAAU,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IAC5B,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,gGAAgG;AAChG,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,kBAAkB,EAClB,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAC9C,CAAC;AAEF,eAAO,MAAM,oCAAoC;;;;;;;EAO/C,CAAC;AAEH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,UAAU,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AAyK9E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,GACvC,UAAU,CASZ;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,GAC3C,UAAU,CAcZ;AAsBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,UAAU,CAMZ;AAyBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACnD,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CAgD/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,EACxC,IAAI,SAAkB,GACrB,cAAc,CAEhB;AAED,kEAAkE;AAClE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,EAC5C,IAAI,SAAiB,GACpB,cAAc,CAKhB"}
+{"version":3,"file":"semantic-query-schema.d.ts","sourceRoot":"","sources":["../src/semantic-query-schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAK,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,WAAW,yBAAyB;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA2B,SAAQ,yBAAyB;IAC3E,iFAAiF;IACjF,UAAU,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;IAC5B,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,gGAAgG;AAChG,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,kBAAkB,EAClB,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAC9C,CAAC;AAEF,eAAO,MAAM,oCAAoC;;;;;;;EAO/C,CAAC;AAEH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,UAAU,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oFAAoF;AACpF,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AA8K9E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,GACvC,UAAU,CASZ;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,GAC3C,UAAU,CAcZ;AAsBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,UAAU,CAMZ;AAyBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EACnD,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CAgD/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,yBAAyB,EAClC,OAAO,GAAE,0BAA+B,EACxC,IAAI,SAAkB,GACrB,cAAc,CAEhB;AAED,kEAAkE;AAClE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,EACxC,cAAc,CAAC,EAAE,2BAA2B,EAC5C,IAAI,SAAiB,GACpB,cAAc,CAKhB"}

package/dist/semantic-query-schema.js

@@ -138,6 +138,11 @@ function queryShape(catalog, metricName, options, relationshipOperators, metric,
             measures: boundedArray(fieldEnum([...Object.keys(catalog.measures), ...Object.keys(catalog.derivedMeasures ?? {})]), lowerLimit(catalog.limits?.maxMeasures, limits.maxMeasures)),
         }),
         filters: boundedArray(filterSchema(catalog, filterFields, relationshipOperators), lowerLimit(catalog.limits?.maxFilters, limits.maxFilters)),
+        // Only datasets that declare segments accept the field, so every other
+        // schema, including hosted catalogs, is unchanged.
+        ...(Object.keys(catalog.segments ?? {}).length > 0 ? {
+            segments: boundedArray(fieldEnum(uniqueSorted(Object.keys(catalog.segments ?? {})))),
+        } : {}),
         orderBy: boundedArray(z.object({
             field: fieldEnum(orderable),
             direction: z.enum(['asc', 'desc']),

package/dist/sql-portability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql-portability.d.ts","sourceRoot":"","sources":["../src/sql-portability.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AAEH,MAAM,MAAM,uBAAuB,GAC/B,oBAAoB,GACpB,kCAAkC,GAClC,kCAAkC,GAClC,iCAAiC,GACjC,gCAAgC,GAChC,yBAAyB,GACzB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACjD;AAED,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEjF,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,oBAAoB,CAKtE,CAAC;AAouBL;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAyBtB"}
+{"version":3,"file":"sql-portability.d.ts","sourceRoot":"","sources":["../src/sql-portability.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AAEH,MAAM,MAAM,uBAAuB,GAC/B,oBAAoB,GACpB,kCAAkC,GAClC,kCAAkC,GAClC,iCAAiC,GACjC,gCAAgC,GAChC,yBAAyB,GACzB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACjD;AAED,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEjF,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,oBAAoB,CAKtE,CAAC;AAi0BL;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAyBtB"}

package/dist/sql-portability.js

@@ -141,6 +141,20 @@ function tokenize(sql) {
                 if (current === '\\') {
                     fail('HQ_SQL_PORT_UNSUPPORTED_LITERAL', 'Backslash escapes are not portable; double the quote instead.', index, index + 1);
                 }
+                const code = current.charCodeAt(0);
+                if ((code <= 0x1f && code !== 0x09 && code !== 0x0a && code !== 0x0d)
+                    || (code >= 0x7f && code <= 0x9f)) {
+                    fail('HQ_SQL_PORT_UNSUPPORTED_LITERAL', 'String literals cannot contain control characters.', index, index + 1);
+                }
+                if (code >= 0xd800 && code <= 0xdfff) {
+                    const low = sql.charCodeAt(index + 1);
+                    if (code > 0xdbff || !(low >= 0xdc00 && low <= 0xdfff)) {
+                        fail('HQ_SQL_PORT_UNSUPPORTED_LITERAL', 'String literals must be well-formed Unicode.', index, index + 1);
+                    }
+                    value += current + sql[index + 1];
+                    index += 2;
+                    continue;
+                }
                 value += current;
                 index += 1;
             }
@@ -222,7 +236,9 @@ function tokenize(sql) {
             }
             continue;
         }
-        fail('HQ_SQL_PORT_UNSUPPORTED_SYNTAX', `Unexpected character "${char}".`, start, start + 1);
+        // Report a whole code point: an astral character is two UTF-16 code units.
+        const unexpected = String.fromCodePoint(sql.codePointAt(index));
+        fail('HQ_SQL_PORT_UNSUPPORTED_SYNTAX', `Unexpected character "${unexpected}".`, start, start + unexpected.length);
     }
     return tokens;
 }
@@ -260,12 +276,32 @@ const COMPARISON_OPERATORS = Object.freeze({
 function node(expression) {
     return Object.freeze(expression);
 }
+/**
+ * RFC 0003 caps the operands of one AND/OR node at the expression validator's
+ * collection limit.
+ */
+const MAX_LOGICAL_OPERANDS = 100;
+function childExpressions(expression) {
+    switch (expression.kind) {
+        case 'binary':
+        case 'comparison':
+            return [expression.left, expression.right];
+        case 'logical':
+            return 'operands' in expression ? expression.operands : [expression.operand];
+        case 'call':
+            return expression.args;
+        default:
+            return [];
+    }
+}
 class Parser {
     tokens;
     limits;
     position = 0;
     nodes = 0;
     dependencies = new Set();
+    /** Tree levels beneath each composite node, counting it; leaves are 1. */
+    levels = new WeakMap();
     constructor(tokens, limits) {
         this.tokens = tokens;
         this.limits = limits;
@@ -303,38 +339,67 @@ class Parser {
             fail('HQ_SQL_PORT_TOO_COMPLEX', 'The expression exceeds its depth limit.', token.start, token.end);
         }
     }
+    /**
+     * Freeze a composite node, rejecting it once its tree has more levels than
+     * the depth limit (RFC 0003 counts the root as depth 1). Parse depth alone
+     * undercounts left-associative chains such as `a + b + c`, whose left spine
+     * grows with every operator.
+     */
+    build(expression, token) {
+        let levels = 1;
+        for (const child of childExpressions(expression)) {
+            levels = Math.max(levels, (this.levels.get(child) ?? 1) + 1);
+        }
+        if (levels > this.limits.maxDepth) {
+            fail('HQ_SQL_PORT_TOO_COMPLEX', 'The expression exceeds its depth limit.', token.start, token.end);
+        }
+        const frozen = node(expression);
+        this.levels.set(frozen, levels);
+        return frozen;
+    }
+    /** Called after consuming AND/OR, before parsing the operand it introduces. */
+    rejectExtraOperand(operands) {
+        if (operands.length >= MAX_LOGICAL_OPERANDS) {
+            const token = this.tokens[this.position - 1];
+            fail('HQ_SQL_PORT_TOO_COMPLEX', 'The expression exceeds its operand limit.', token.start, token.end);
+        }
+    }
     parseOr(depth) {
         const operands = [this.parseAnd(depth)];
         while (this.peek()?.type === 'keyword' && this.peek().value === 'or') {
             this.next();
+            this.rejectExtraOperand(operands);
             operands.push(this.parseAnd(depth));
         }
         if (operands.length === 1)
             return operands[0];
-        this.enter(depth, this.tokens[this.position - 1]);
-        return node({ kind: 'logical', operator: 'or', operands: Object.freeze(operands) });
+        const token = this.tokens[this.position - 1];
+        this.enter(depth, token);
+        return this.build({ kind: 'logical', operator: 'or', operands: Object.freeze(operands) }, token);
     }
     parseAnd(depth) {
         const operands = [this.parseNot(depth)];
         while (this.peek()?.type === 'keyword' && this.peek().value === 'and') {
             this.next();
+            this.rejectExtraOperand(operands);
             operands.push(this.parseNot(depth));
         }
         if (operands.length === 1)
             return operands[0];
-        this.enter(depth, this.tokens[this.position - 1]);
-        return node({ kind: 'logical', operator: 'and', operands: Object.freeze(operands) });
+        const token = this.tokens[this.position - 1];
+        this.enter(depth, token);
+        return this.build({ kind: 'logical', operator: 'and', operands: Object.freeze(operands) }, token);
     }
     parseNot(depth) {
         const token = this.peek();
         if (token?.type === 'keyword' && token.value === 'not') {
             this.next();
             this.enter(depth + 1, token);
-            return node({
+            return this.build({
                 kind: 'logical',
                 operator: 'not',
                 operand: this.parseNot(depth + 1),
-            });
+            }, token);
         }
         return this.parseComparison(depth);
     }
@@ -349,14 +414,17 @@ class Parser {
             const right = this.parseAdditive(depth);
             this.enter(depth + 1, token);
             this.rejectChained();
-            return node({ kind: 'comparison', operator, left, right });
+            return this.build({ kind: 'comparison', operator, left, right }, token);
         }
         if (token.type === 'keyword' && token.value === 'like') {
             this.next();
             const right = this.parseAdditive(depth);
             this.enter(depth + 1, token);
             this.rejectChained();
-            return node({ kind: 'comparison', operator: 'like', left, right });
+            if (right.kind !== 'literal' || typeof right.value !== 'string') {
+                fail('HQ_SQL_PORT_UNSUPPORTED_SYNTAX', 'LIKE patterns must be string literals.', token.start, token.end);
+            }
+            return this.build({ kind: 'comparison', operator: 'like', left, right }, token);
         }
         if (token.type === 'keyword' && token.value === 'between') {
             this.next();
@@ -369,12 +437,12 @@ class Parser {
             const upper = this.parseAdditive(depth);
             this.enter(depth + 1, token);
             this.rejectChained();
-            return node({
+            return this.build({
                 kind: 'comparison',
                 operator: 'between',
                 left,
                 right: this.tupleLiteral(lower, upper, token),
-            });
+            }, token);
         }
         if (token.type === 'keyword' && (token.value === 'in' || token.value === 'not')) {
             this.next();
@@ -449,7 +517,7 @@ class Parser {
         }
         this.enter(depth + 1, token);
         this.rejectChained();
-        return node({
+        return this.build({
             kind: 'comparison',
             operator,
             left,
@@ -463,7 +531,7 @@ class Parser {
                     },
                 },
             },
-        });
+        }, token);
     }
     parseAdditive(depth) {
         let left = this.parseMultiplicative(depth);
@@ -474,12 +542,12 @@ class Parser {
             this.next();
             const right = this.parseMultiplicative(depth + 1);
             this.enter(depth + 1, token);
-            left = node({
+            left = this.build({
                 kind: 'binary',
                 operator: BINARY_OPERATORS[token.value],
                 left,
                 right,
-            });
+            }, token);
         }
         return left;
     }
@@ -492,12 +560,12 @@ class Parser {
             this.next();
             const right = this.parseUnary(depth + 1);
             this.enter(depth + 1, token);
-            left = node({
+            left = this.build({
                 kind: 'binary',
                 operator: BINARY_OPERATORS[token.value],
                 left,
                 right,
-            });
+            }, token);
         }
         return left;
     }
@@ -514,6 +582,7 @@ class Parser {
                 fail('HQ_SQL_PORT_UNSUPPORTED_OPERATOR', 'Negation is only portable on numeric literals.', token.start, token.end);
             }
             this.next();
+            this.enter(depth, operand);
             return this.numericLiteral(operand, true);
         }
         return this.parsePrimary(depth);
@@ -595,11 +664,11 @@ class Parser {
         if (args.length < arity[0] || args.length > arity[1]) {
             fail('HQ_SQL_PORT_SYNTAX', `Function "${canonical}" expects ${arity[0] === arity[1] ? arity[0] : `${arity[0]} to ${arity[1]}`} arguments.`, name.start, close.end);
         }
-        return node({
+        return this.build({
             kind: 'call',
             function: canonical,
             args: Object.freeze(args),
-        });
+        }, name);
     }
     numericLiteral(token, negated) {
         const value = Number(token.value) * (negated ? -1 : 1);

package/dist/types.d.ts

@@ -59,7 +59,9 @@ export interface RelationshipDefinition<TTarget extends {
     from: string;
     to: string;
 }
-export type AggregationType = 'sum' | 'count' | 'countDistinct' | 'avg' | 'min' | 'max' | 'argMax' | 'argMin' | 'percentile' | 'stddev' | 'variance';
+export type AggregationType = 'sum' | 'count' | 'countDistinct' | 'avg' | 'min' | 'max' | 'argMax' | 'argMin' | 'percentile' | 'stddev' | 'variance'
+/** Estimated distinct count (ClickHouse `uniq`); results carry `approximate`. */
+ | 'approxCountDistinct';
 export type MeasureAggregation = AggregationType;
 export interface AggregationSpec {
     __type: 'aggregation_spec';
@@ -176,7 +178,7 @@ export interface GrainedMetricRef<TDatasetName extends string = string, TMetricN
     contract(): MetricContract;
 }
 export type MetricHandle<TDatasetName extends string = string, TMetricName extends string = string, TSpec extends AggregationSpec | DerivedMetricSpec<TDatasetName> = AggregationSpec | DerivedMetricSpec<TDatasetName>, TDataset extends DatasetInstance<any, any, any, TDatasetName> = DefaultMetricDataset<TDatasetName>> = MetricRef<TDatasetName, TMetricName, TSpec, TDataset> | GrainedMetricRef<TDatasetName, TMetricName, TSpec, TDataset>;
-export type TimeGrain = 'day' | 'week' | 'month' | 'quarter' | 'year';
+export type TimeGrain = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 export interface MetricContract {
     kind: 'metric' | 'derived_metric' | 'grained_metric';
     name: string;
@@ -208,9 +210,18 @@ export interface MetricOrderBy<TField extends string = string> {
     field: TField;
     direction: 'asc' | 'desc';
 }
+/** A named row filter declared on a dataset; see `DatasetConfig.segments`. */
+export interface SegmentDefinition {
+    /** Comparisons over the dataset's own dimensions, combined with AND. */
+    filters: MetricFilter[];
+    label?: string;
+    description?: string;
+}
 export interface MetricQuery {
     dimensions?: string[];
     filters?: MetricFilter[];
+    /** Segment names declared on the dataset, combined with `filters` by AND. */
+    segments?: string[];
     orderBy?: MetricOrderBy[];
     limit?: number;
     offset?: number;
@@ -220,6 +231,8 @@ export interface DatasetQuery {
     dimensions?: string[];
     measures?: string[];
     filters?: MetricFilter[];
+    /** Segment names declared on the dataset, combined with `filters` by AND. */
+    segments?: string[];
     orderBy?: MetricOrderBy[];
     limit?: number;
     offset?: number;
@@ -336,7 +349,7 @@ export interface DerivedMetricConfig<TDatasetName extends string = string> exten
     label?: string;
     description?: string;
 }
-export interface DatasetConfig<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, DatasetMeasureDefinition> = Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>> extends SemanticMetadata {
+export interface DatasetConfig<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, DatasetMeasureDefinition> = Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>, TSegments extends Record<string, SegmentDefinition> = Record<string, SegmentDefinition>> extends SemanticMetadata {
     source: string;
     description?: string;
     freshness?: DatasetFreshness;
@@ -344,14 +357,26 @@ export interface DatasetConfig<TDimensions extends Record<string, DimensionDefin
     defaults?: DatasetDefaults;
     tenantKey?: string;
     timeKey?: string;
+    /**
+     * Restricts the time grains this dataset supports. Defaults to every grain
+     * the planner can bucket on. Use it, for example, to refuse `minute` and
+     * `hour` when `timeKey` is a `Date` column without a time of day.
+     */
+    timeGrains?: readonly TimeGrain[];
     dimensions: TDimensions;
     measures?: TMeasures & CheckedDatasetMeasures<TMeasures>;
     filters?: SemanticFiltersDefinition;
     relationships?: TRelationships;
     limits?: DatasetLimits;
     cache?: DatasetCachePolicy;
+    /**
+     * Named, author-defined row filters that a query selects by name (RFC 0015).
+     * Each is an AND of comparisons over this dataset's own dimensions, and it
+     * may use dimensions that are not exposed as filters.
+     */
+    segments?: TSegments;
 }
-export interface DatasetInstance<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>, TDatasetName extends string = string, TDerivedMeasures extends Record<string, DerivedMeasureDefinition> = Record<string, DerivedMeasureDefinition>> {
+export interface DatasetInstance<TDimensions extends Record<string, DimensionDefinition> = Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition> = Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition> = Record<string, never>, TDatasetName extends string = string, TDerivedMeasures extends Record<string, DerivedMeasureDefinition> = Record<string, DerivedMeasureDefinition>, TSegments extends Record<string, SegmentDefinition> = Record<string, SegmentDefinition>> {
     __type: 'dataset';
     name: TDatasetName;
     source: string;
@@ -368,6 +393,7 @@ export interface DatasetInstance<TDimensions extends Record<string, DimensionDef
     defaults?: DatasetDefaults;
     tenantKey?: string;
     timeKey?: string;
+    timeGrains?: readonly TimeGrain[];
     dimensions: TDimensions;
     measures: TMeasures;
     derivedMeasures: TDerivedMeasures;
@@ -375,8 +401,9 @@ export interface DatasetInstance<TDimensions extends Record<string, DimensionDef
     relationships: TRelationships;
     limits?: DatasetLimits;
     cache?: DatasetCachePolicy;
-    metric<TName extends string>(metricName: TName, metricConfig: BaseMetricConfig<TMeasures>): BaseMetricRef<TDatasetName, TName, DatasetInstance<TDimensions, TMeasures, TRelationships, TDatasetName, TDerivedMeasures>>;
-    metric<TName extends string>(metricName: TName, metricConfig: DerivedMetricConfig<TDatasetName>): DerivedMetricRef<TDatasetName, TName, DatasetInstance<TDimensions, TMeasures, TRelationships, TDatasetName, TDerivedMeasures>>;
+    segments: TSegments;
+    metric<TName extends string>(metricName: TName, metricConfig: BaseMetricConfig<TMeasures>): BaseMetricRef<TDatasetName, TName, DatasetInstance<TDimensions, TMeasures, TRelationships, TDatasetName, TDerivedMeasures, TSegments>>;
+    metric<TName extends string>(metricName: TName, metricConfig: DerivedMetricConfig<TDatasetName>): DerivedMetricRef<TDatasetName, TName, DatasetInstance<TDimensions, TMeasures, TRelationships, TDatasetName, TDerivedMeasures, TSegments>>;
 }
 export interface DatasetRegistryInstance {
     register(ds: DatasetInstance): void;
@@ -413,6 +440,8 @@ export type DatasetQueryableDimensions<TDataset extends DatasetInstance<any, any
 export type DatasetFieldNames<TDataset extends DatasetInstance<any, any, any, any>> = DatasetDimensionNames<TDataset>;
 /** Measure names declared by a dataset. */
 export type DatasetMeasureNames<TDataset extends DatasetInstance<any, any, any, any>> = KnownStringKeysOrFallback<TDataset['measures']> | KnownStringKeys<TDataset['derivedMeasures']>;
+/** Segment names declared by a dataset. */
+export type DatasetSegmentNames<TDataset extends DatasetInstance<any, any, any, any>> = keyof TDataset['segments'] & string;
 /**
  * Fields a result can be ordered by. This is the selection-independent superset
  * (every dimension + measure, plus the synthetic `period` column for grained
@@ -424,6 +453,8 @@ export interface DatasetQueryFor<TDataset extends DatasetInstance<any, any, any,
     dimensions?: readonly DatasetDimensionNames<TDataset>[];
     measures?: readonly DatasetMeasureNames<TDataset>[];
     filters?: readonly MetricFilter[];
+    /** Segment names declared on the dataset. */
+    segments?: readonly DatasetSegmentNames<TDataset>[];
     orderBy?: readonly MetricOrderBy<DatasetOrderableNames<TDataset>>[];
     limit?: number;
     offset?: number;
@@ -463,6 +494,8 @@ export interface DatasetQueryResultFor<TDataset extends DatasetInstance<any, any
 export interface MetricQueryFor<TDataset extends DatasetInstance<any, any, any, any>, TMetricName extends string> {
     dimensions?: readonly DatasetDimensionNames<TDataset>[];
     filters?: readonly MetricFilter[];
+    /** Segment names declared on the dataset. */
+    segments?: readonly DatasetSegmentNames<TDataset>[];
     orderBy?: readonly MetricOrderBy<DatasetDimensionNames<TDataset> | TMetricName | 'period'>[];
     limit?: number;
     offset?: number;