measurr 0.6.0 → 0.7.0

package/README.md

@@ -7,8 +7,8 @@ returns shaped, typed rows.
 
 - No SQL text in definitions: datasets are built from typed expression builders, so a
   renamed column, `avg` over a string or `between` on an enum fails typecheck.
-- Database-neutral definitions: dialects plug in through the `Dialect` interface, and Postgres
-  ships today (`measurr/postgres`).
+- Database-neutral definitions: dialects plug in through the `Dialect` interface. Postgres
+  (`measurr/postgres`) and ClickHouse (`measurr/clickhouse`) ship today.
 - Tenant-scoped by construction: the engine adds the tenant filter to every statement and
   refuses to run without a tenant. A caller can be scoped to one tenant or a list of them;
   platform admins can query every tenant only through an explicit `allTenants` value that no
@@ -355,6 +355,52 @@ try {
 }
 ```
 
+## Resolved measures
+
+Some numbers one statement cannot give: sprays per employee when the employees live in another
+database, an average per day of the period, a forecast. Declare such a measure with
+`measure.resolved` and give the code to `createAnalytics`. It stays a measure like any other:
+it is in the catalog and the schema, checked for access, scoped to the tenant and cached.
+
+```ts
+const sprays = defineDataset({
+	// ...
+	measures: {
+		sprays: measure.sum(status.col('sprays'), { label: 'Sprays' }),
+		spraysPerDay: measure.resolved({ label: 'Sprays per day', result: 'number', uses: ['sprays'] })
+	}
+})
+
+createAnalytics({
+	// ...
+	resolvers: {
+		sprays: {
+			spraysPerDay: ({ rows, totals, period }) => {
+				const days = 'all' in period ? null : daysBetween(period.from, period.to)
+				const perDay = (value: number | null) =>
+					value === null || days === null ? null : value / days
+				return { rows: rows.map(({ values }) => perDay(values.sprays)), totals: perDay(totals.sprays) }
+			}
+		}
+	}
+})
+```
+
+- `uses` names the measures of the same dataset the resolver reads. The database computes them
+  for every row and for the totals, even when the query does not ask for them, and the result
+  holds only what it asked for. A measure with no `uses` still gets one value per group.
+- The resolver gets the rows in order (`dimensions` for the grouped keys, `values` for the used
+  measures), the `totals`, `groupBy`, the `filters` (open-dimension labels resolved to keys),
+  the `period`, the `tenant` scope and `ctx`. It returns one value per row and one for the
+  totals. With `compareToPrevious` it is called once per period.
+- `createAnalytics` throws when a resolved measure has no resolver, and when `resolvers` names
+  anything else. A wrong number of values fails the query; a value that is not a finite number
+  is null, and a `count` result is 0 instead.
+- A resolved measure needs the access of the measures it uses, like a ratio. It cannot be sorted
+  by (the database limits the rows before the value exists), and `ratio` and `uses` cannot name
+  one.
+- The contract kit leaves resolved measures out: they are app code, so test them with it.
+
 ## Tenants and platform admins
 
 `tenant(ctx)` decides the scope of every statement, including the lookups that resolve filter
@@ -424,7 +470,7 @@ before any statement runs; a narrower scope is never ignored. `listDatasets(ctx)
 | Concept | What it is |
 | --- | --- |
 | Dataset | One fact table: tenant column (or `null`), optional scope, time fields, default period, measures, dimensions, source. |
-| Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another) or `ratio` (one measure over another, after aggregation). Optionally restricted with `access`. |
+| Measure | `count`, `countWhere`, `countDistinct`, `sum`, `avg`, `median`, `share` (one condition over another), `ratio` (one measure over another, after aggregation) or `resolved` (computed by the app after the query runs). Optionally restricted with `access`. |
 | Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). Optionally restricted with `access`. |
 | Query | `dataset`, 1-4 `measures`, 0-2 `groupBy`, `filters`, `period`, `time`, `compareToPrevious`, `sort` (by an asked measure or grouped dimension), `limit` (1-100, default 20). |
 | Result | `{ period, rows, totals, previous?, notes, truncated }`; `period` is `{ from, to, timezone }` or `{ all: true, timezone }`. |
@@ -546,6 +592,34 @@ const main: AnalyticsSource = {
 }
 ```
 
+**`measurr/clickhouse`** `clickhouseDialect()`: typed `{pN:Type}` parameters, backquoted
+identifiers, `-If` and `-OrNull` aggregates (an empty group is null, as in Postgres), an exact
+interpolated median, `uniqExact` for distinct counts, and buckets with `toTimeZone`. Every
+statement ends with `SETTINGS join_use_nulls = 1, enable_positional_arguments = 1`, so a left
+join without a match gives null (an empty group) instead of an empty string. Pass the values
+with `toQueryParams`:
+
+```ts
+import { clickhouseDialect, toQueryParams } from 'measurr/clickhouse'
+
+const events: AnalyticsSource = {
+	dialect: clickhouseDialect(),
+	execute: async (statement) => {
+		const result = await clickhouse.query({
+			query: statement.text,
+			query_params: toQueryParams(statement),
+			format: 'JSONEachRow'
+		})
+		return result.json()
+	}
+}
+```
+
+ClickHouse cannot run correlated subqueries, so a dataset on it cannot use `exists` or filter
+by a many-to-many dimension (mark it `groupOnly`); `createAnalytics` fails at startup if it
+does. Time columns are `DateTime` or `DateTime64`, which hold instants. Tested against
+ClickHouse 24.
+
 **`measurr/postgres`** `postgresDialect({ timestamps })`: `$n` parameters (untyped,
 so Postgres infers them from the column, which keeps enum columns working), double-quoted
 identifiers, `FILTER (WHERE ...)`, `count(DISTINCT ...)`, `percentile_cont`, correlated
@@ -600,7 +674,9 @@ Kept stable for publishing: `createAnalytics` and its options (with `authorize`,
 `resultSchema`, `listDatasets`; `AnalyticsResultSchema`, `analyticsToolGuidance`,
 `AnalyticsQueryEvent`; `defineDataset` (with `defaultPeriod` and `tenantColumn: null`),
 `measure.*` and `dimension.*` (with `access`), `table` / `Table`, the expression builders; the
-`Dialect`, `SqlRenderer` and `AnalyticsSource` contracts; `postgresDialect`,
+`Dialect`, `SqlRenderer` and `AnalyticsSource` contracts; `measure.resolved` with the
+`resolvers` option (`MeasureResolver`, `ResolverInput`, `ResolverOutput`); `postgresDialect`,
+`clickhouseDialect` and `toQueryParams`,
 `checkDatasetContract` / `assertDatasetContract`; `measurr/shapes` (`toKpi`, `toTimeseries`,
 `toDistribution`, `toPivot`, `toLeaderboard`) and `measurr/handler` (`queryBatch`,
 `streamBatch`, `toHttpError`); and the types `AnalyticsQuery`, `AnalyticsResult`,
@@ -624,13 +700,14 @@ npm install measurr zod
 bun install
 bun run lint   # types and Biome
 bun test
-# With a throwaway Postgres (the integration test creates and drops its own tables):
-ANALYTICS_TEST_DATABASE_URL=postgres://... bun test
+# With a throwaway Postgres and ClickHouse (the integration tests create and drop their own tables):
+ANALYTICS_TEST_DATABASE_URL=postgres://... ANALYTICS_TEST_CLICKHOUSE_URL=http://user:password@localhost:8123 bun test
 bun run build && bun run verify:package
 ```
 
 The integration test reads `ANALYTICS_TEST_DATABASE_URL`, not `DATABASE_URL`, because Bun
-loads `.env` files and that name may point at a real database. CI runs it against Postgres 17.
+loads `.env` files and that name may point at a real database. CI runs them against Postgres 17
+and ClickHouse 24.
 
 Releases are automated with Release Please; see [docs/releasing.md](docs/releasing.md).
 

package/dist/analytics.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 import type { CompiledStatement, Dialect } from './compile.js';
-import type { AnyDataset, AnyDimension, Dataset } from './dataset.js';
-import { type Tenant } from './plan.js';
-import { type DatasetQuery, type QueryResult, type ResultOf } from './query.js';
+import type { AnyDataset, AnyDimension, Dataset, DimensionValue, MeasureValue, ResolvedMeasure } from './dataset.js';
+import { type NormalizedFilter, type Tenant } from './plan.js';
+import { type DatasetQuery, type QueryResult, type ResultOf, type ResultPeriod } from './query.js';
 export type Row = Record<string, unknown>;
 /** A database: a dialect to compile with and a function that runs the compiled SQL. */
 export type AnalyticsSource = {
@@ -59,6 +59,51 @@ export type AnalyticsQueryEvent = {
 export type FieldKey<D> = D extends Dataset<string, infer M, infer Dm> ? keyof (M & Dm) & string : never;
 /** The access keys a dataset's measures and dimensions are marked with. */
 export type AccessKey<D> = D extends Dataset<string, infer M, infer Dm> ? NonNullable<(M & Dm)[keyof (M & Dm)]['access']> : never;
+/** The resolved measures of a dataset. */
+export type ResolvedKey<D> = D extends Dataset<string, infer M> ? {
+    [K in keyof M & string]: M[K] extends {
+        kind: 'resolved';
+    } ? K : never;
+}[keyof M & string] : never;
+/** The values of the measures resolved measure `K` uses. */
+type UsedValues<D, K> = D extends Dataset<string, infer M> ? M[K & keyof M] extends ResolvedMeasure<MeasureResult, infer U> ? {
+    [Used in U & keyof M]: MeasureValue<M[Used]>;
+} : never : never;
+type MeasureResult = ResolvedMeasure['result'];
+/** What a resolver gets for one period of one query. */
+export type ResolverInput<D, K, Ctx> = D extends Dataset<string, infer _M, infer Dm> ? {
+    /**
+     * The result rows in order: their grouped dimensions and the measures `K` uses. One
+     * row when the query has no `groupBy`.
+     */
+    rows: readonly {
+        dimensions: {
+            [G in keyof Dm]?: DimensionValue<Dm[G]>;
+        };
+        values: UsedValues<D, K>;
+    }[];
+    /** The used measures over every row of the period, ungrouped. */
+    totals: UsedValues<D, K>;
+    groupBy: readonly (keyof Dm & string)[];
+    /** The query's filters, open-dimension labels already resolved to keys. */
+    filters: readonly NormalizedFilter[];
+    /** The period being resolved: the query's, or its previous one. */
+    period: ResultPeriod;
+    tenant: Tenant;
+    ctx: Ctx;
+} : never;
+/** One value per row, in the same order, and one for the totals. */
+export type ResolverOutput = {
+    rows: readonly (number | null)[];
+    totals: number | null;
+};
+export type MeasureResolver<D, K, Ctx> = (input: ResolverInput<D, K, Ctx>) => ResolverOutput | Promise<ResolverOutput>;
+/** The code for every resolved measure, by dataset and measure. */
+export type AnalyticsResolvers<DS extends readonly AnyDataset[], Ctx> = {
+    [D in DS[number] as [ResolvedKey<D>] extends [never] ? never : D['key']]: {
+        [K in ResolvedKey<D>]: MeasureResolver<D, K, Ctx>;
+    };
+};
 export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
     datasets: DS;
     /** Databases by name; a dataset's `source` picks one, or the only one is used. */
@@ -97,6 +142,13 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
      * swallowed: a failing cache is a miss, never a failed query.
      */
     cache?: AnalyticsCache<Ctx, DS[number]['key']> | undefined;
+    /**
+     * The code for `measure.resolved` measures, by dataset and measure key: called once per
+     * period with the result rows and the values of the measures each one uses. Required for
+     * every resolved measure (`createAnalytics` throws otherwise). What it throws fails the
+     * query; a value that is not a finite number counts as null.
+     */
+    resolvers?: NoInfer<AnalyticsResolvers<DS, Ctx>> | undefined;
 };
 /**
  * A store for finished results, such as Redis. Keys name the dataset and hash everything that
@@ -185,3 +237,4 @@ export type Analytics<DS extends readonly AnyDataset[], Ctx> = {
 export type AnalyticsQuery<A> = A extends Analytics<infer DS, never> ? DatasetQuery<DS[number]> : never;
 export type AnalyticsResult<A, Q> = A extends Analytics<infer DS, never> ? ResultOf<DS[number], Q> : never;
 export declare function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(options: AnalyticsOptions<DS, Ctx>): Analytics<DS, Ctx>;
+export {};

package/dist/dataset.d.ts

@@ -53,7 +53,21 @@ export type RatioMeasure<A extends string = string, B extends string = string> =
     readonly numerator: A;
     readonly denominator: B;
 };
-export type AnyMeasure = AggregateMeasure | ShareMeasure | RatioMeasure;
+/**
+ * A value the app computes after the query runs, from the measures it `uses` in each row and
+ * from anything else it can reach (another database, a forecast). The `resolvers` option of
+ * `createAnalytics` supplies the code.
+ */
+export type ResolvedMeasure<R extends MeasureResult = MeasureResult, U extends string = string> = {
+    readonly kind: 'resolved';
+    readonly result: R;
+    readonly label: string;
+    readonly description: string | undefined;
+    /** A resolved measure also needs the access of the measures it uses. */
+    readonly access: string | undefined;
+    readonly uses: readonly U[];
+};
+export type AnyMeasure = AggregateMeasure | ShareMeasure | RatioMeasure | ResolvedMeasure;
 /** The TypeScript type of a measure's value in a result row. */
 export type MeasureValue<M> = M extends {
     result: 'count';
@@ -86,7 +100,23 @@ export declare const measure: {
      * measures of the same dataset; `defineDataset` checks them.
      */
     ratio<const A extends string, const B extends string, Access extends string = never>(numerator: A, denominator: B, options: Described<Access>): RatioMeasure<A, B> & Marked<NoInfer<Access>>;
+    resolved: typeof resolved;
 };
+/**
+ * A value the app computes after the query runs, for numbers one statement cannot give:
+ * another database, a forecast, a per-day average. `uses` names the measures of this dataset
+ * the resolver reads from each row; they are fetched even when the query does not ask for
+ * them. The code goes in `createAnalytics({ resolvers })`. Queries cannot sort by it, since
+ * the database limits the rows before the value exists.
+ */
+declare function resolved<R extends MeasureResult, Access extends string = never>(options: Described<Access> & {
+    result: R;
+    uses?: undefined;
+}): ResolvedMeasure<R, never> & Marked<NoInfer<Access>>;
+declare function resolved<R extends MeasureResult, const U extends string, Access extends string = never>(options: Described<Access> & {
+    result: R;
+    uses: readonly U[];
+}): ResolvedMeasure<R, U> & Marked<NoInfer<Access>>;
 /**
  * How a dimension filters:
  * - `closed`: a fixed set of keys (enum, computed) - `in`, `notIn`, `isEmpty`, `isNotEmpty`;
@@ -274,13 +304,26 @@ export type Dataset<K extends string = string, M extends Record<string, AnyMeasu
     readonly dimensions: Dm;
 };
 export type AnyDataset = Dataset<string, any, any, string>;
-/** Ratio measures may only name other measures of the same dataset. */
+/** Measures the database computes: everything but resolved measures. */
+export type SqlMeasureKey<M> = {
+    [Key in keyof M & string]: M[Key] extends {
+        kind: 'resolved';
+    } ? never : Key;
+}[keyof M & string];
+/**
+ * Ratio measures may only name other SQL measures of the same dataset, and resolved measures
+ * may only use SQL measures.
+ */
 type CheckMeasures<M> = {
     [Key in keyof M]: M[Key] extends {
         kind: 'ratio';
     } ? {
-        numerator: Exclude<keyof M & string, Key>;
-        denominator: Exclude<keyof M & string, Key>;
+        numerator: Exclude<SqlMeasureKey<M>, Key>;
+        denominator: Exclude<SqlMeasureKey<M>, Key>;
+    } : M[Key] extends {
+        kind: 'resolved';
+    } ? {
+        uses: readonly SqlMeasureKey<M>[];
     } : unknown;
 };
 /** Time dimensions may only name declared time fields. */

package/dist/dialects/clickhouse.d.ts

@@ -0,0 +1,26 @@
+import { type CompiledStatement, type Dialect } from '../compile.js';
+/**
+ * ClickHouse: typed `{pN:Type}` parameters (pass them with `toQueryParams`), backquoted
+ * identifiers, `-If` and `-OrNull` aggregates, and buckets in the tenant's timezone. Time
+ * columns are `DateTime` or `DateTime64`, which hold an instant, so no timestamp option is
+ * needed.
+ *
+ * Correlated subqueries are not supported, so `exists` and filters on many-to-many dimensions
+ * (mark them `groupOnly`) fail when `createAnalytics` compiles the dataset.
+ */
+export declare function clickhouseDialect(): Dialect;
+/**
+ * The compiled values as the `query_params` the ClickHouse client takes: `{ p1, p2, ... }`.
+ *
+ * ```ts
+ * execute: async (statement) => {
+ *   const result = await clickhouse.query({
+ *     query: statement.text,
+ *     query_params: toQueryParams(statement),
+ *     format: 'JSONEachRow'
+ *   })
+ *   return result.json()
+ * }
+ * ```
+ */
+export declare function toQueryParams(statement: CompiledStatement): Record<string, unknown>;

package/dist/dialects/clickhouse.js

@@ -0,0 +1,101 @@
+import {
+  CompileError2,
+  decodeNumber2,
+  renderStatement2
+} from "../index-nrjdssft.js";
+import {
+  walk
+} from "../index-e6k30sfp.js";
+
+// src/dialects/clickhouse.ts
+var SETTINGS = "SETTINGS join_use_nulls = 1, enable_positional_arguments = 1";
+function clickhouseDialect() {
+  const zone = (expr, timezone) => `toTimeZone(${expr}, '${timezone.replaceAll("'", "\\'")}')`;
+  const renderer = {
+    name: "clickhouse",
+    quote: (identifier) => `\`${identifier.replaceAll("\\", "\\\\").replaceAll("`", "\\`")}\``,
+    param(value, index) {
+      const { type, bound } = typedParam(value);
+      return { placeholder: `{p${index}:${type}}`, value: bound };
+    },
+    aggregate(fn, arg, where) {
+      switch (fn) {
+        case "count":
+          return where ? `countIf(${where})` : "count()";
+        case "countDistinct":
+          return where ? `uniqExactIf(${arg}, ${where})` : `uniqExact(${arg})`;
+        case "sum":
+        case "avg": {
+          const args = where ? `${arg}, ${where}` : arg;
+          return `${fn}${where ? "If" : ""}OrNull(${args})`;
+        }
+        case "median":
+          return where ? `quantileExactInclusiveIfOrNull(0.5)(${arg}, ${where})` : `quantileExactInclusiveOrNull(0.5)(${arg})`;
+      }
+    },
+    divide: (left, right) => `(toFloat64(${left}) / nullIf(${right}, 0))`,
+    toText: (expr) => `toString(${expr})`,
+    timeBucket(unit, expr, timezone) {
+      const local = zone(expr, timezone);
+      switch (unit) {
+        case "day":
+          return `toString(toDate(${local}))`;
+        case "week":
+          return `toString(toMonday(${local}))`;
+        case "month":
+          return `toString(toStartOfMonth(${local}))`;
+      }
+    },
+    timePart: (part, expr, timezone) => part === "isodow" ? `toDayOfWeek(${zone(expr, timezone)})` : `toHour(${zone(expr, timezone)})`
+  };
+  return {
+    name: "clickhouse",
+    compile(statement) {
+      rejectCorrelatedSubqueries(statement);
+      const compiled = renderStatement2(statement, renderer);
+      return { ...compiled, text: `${compiled.text}
+${SETTINGS}` };
+    },
+    decodeNumber: decodeNumber2
+  };
+}
+function toQueryParams(statement) {
+  return Object.fromEntries(statement.values.map((value, index) => [`p${index + 1}`, value]));
+}
+function typedParam(value) {
+  if (value === null)
+    return { type: "Nullable(String)", bound: null };
+  if (value instanceof Date) {
+    const utc = value.toISOString().replace("T", " ").replace("Z", "");
+    return { type: "DateTime64(3, 'UTC')", bound: utc };
+  }
+  switch (typeof value) {
+    case "string":
+      return { type: "String", bound: value };
+    case "boolean":
+      return { type: "Bool", bound: value };
+    case "number":
+      return {
+        type: Number.isSafeInteger(value) ? "Int64" : "Float64",
+        bound: value
+      };
+  }
+}
+function rejectCorrelatedSubqueries(statement) {
+  const nodes = [
+    ...statement.select.map((item) => item.node),
+    ...statement.where,
+    ...statement.virtualJoins.map((join) => join.on)
+  ];
+  for (const node of nodes) {
+    walk(node, (inner) => {
+      if (inner.kind === "exists") {
+        throw new CompileError2(`ClickHouse cannot run the correlated EXISTS that ${inner.table.name} needs: avoid exists() and mark many-to-many dimensions groupOnly`);
+      }
+    });
+  }
+}
+export {
+  clickhouseDialect,
+  toQueryParams
+};

package/dist/handler.js

@@ -2,8 +2,8 @@ import {
   queryBatch2,
   streamBatch2,
   toHttpError2
-} from "./index-xf6qpmgy.js";
-import"./index-z5xv3ffk.js";
+} from "./index-psw9s799.js";
+import"./index-g0ah4ehn.js";
 export {
   queryBatch2 as queryBatch,
   streamBatch2 as streamBatch,

package/dist/{index-z5xv3ffk.js → index-g0ah4ehn.js}

@@ -108,7 +108,8 @@ function datasetQuerySchema(dataset) {
     throw new Error(`Dataset ${dataset.key} has no measures`);
   const groupKeys = nonEmpty(groupable.map(([key]) => key));
   const timeKeys = nonEmpty(Object.keys(dataset.time));
-  const sortKeys = nonEmpty([...measureKeys, ...groupKeys ?? []]) ?? measureKeys;
+  const sqlMeasureKeys = measures.filter(([, entry]) => entry.kind !== "resolved").map(([key]) => key);
+  const sortKeys = nonEmpty([...sqlMeasureKeys, ...groupKeys ?? []]) ?? measureKeys;
   const notes = groupable.filter(([, dim]) => dim.kind === "manyToMany" && dim.note).map(([key, dim]) => `${key}: ${dim.kind === "manyToMany" ? dim.note : ""}`);
   const [firstFilter, ...otherFilters] = filterable.map(([key, dim]) => filterSchema(key, dim));
   return z.object({
@@ -142,6 +143,14 @@ function datasetQuerySchema(dataset) {
         message: `Sort by one of the asked measures or grouped dimensions: ${returned.join(", ")}`
       });
     }
+    const sortMeasure = by === undefined ? undefined : dataset.measures[by];
+    if (sortMeasure?.kind === "resolved") {
+      context.addIssue({
+        code: "custom",
+        path: ["sort", "by"],
+        message: `${by} is computed after the query runs and cannot be sorted by`
+      });
+    }
     const period = query.period ?? dataset.defaultPeriod;
     if (query.compareToPrevious && "all" in period) {
       context.addIssue({
@@ -256,7 +265,22 @@ function measureNode(dataset, key) {
         left: measureNode(dataset, entry.numerator),
         right: measureNode(dataset, entry.denominator)
       };
+    case "resolved":
+      throw new Error(`Dataset ${dataset.key}: measure ${key} is resolved by the app, not the database`);
+  }
+}
+function sqlMeasures(dataset, keys) {
+  const result = new Set;
+  for (const key of keys) {
+    const entry = measureOf(dataset, key);
+    if (entry.kind === "resolved") {
+      for (const used of entry.uses)
+        result.add(used);
+    } else {
+      result.add(key);
+    }
   }
+  return [...result];
 }
 function dimensionNodes(dataset, key, timezone) {
   const entry = dimensionOf(dataset, key);
@@ -410,12 +434,19 @@ function planQuery(dataset, query, context, grouped) {
       select.push({ alias: columnAlias.groupLabel(key), node: nodes.label });
     }
   }
-  for (const key of query.measures) {
+  const measureKeys = sqlMeasures(dataset, query.measures);
+  for (const key of measureKeys) {
     select.push({
       alias: columnAlias.measure(key),
       node: measureNode(dataset, key)
     });
   }
+  if (select.length === 0) {
+    select.push({
+      alias: "row_count",
+      node: { kind: "aggregate", fn: "count", arg: null, where: null }
+    });
+  }
   const where = [
     ...baseWhere(dataset, context.tenant, context.period && {
       time: query.time,
@@ -442,7 +473,10 @@ function orderBy(dataset, query, select) {
     const kind = dimensionOf(dataset, key).kind;
     return kind === "timeBucket" || kind === "timePart";
   });
-  const sort = query.sort ?? (timeKey ? { by: timeKey, direction: "asc" } : { by: query.measures[0] ?? "", direction: "desc" });
+  const sort = query.sort ?? (timeKey ? { by: timeKey, direction: "asc" } : {
+    by: sqlMeasures(dataset, query.measures)[0] ?? "",
+    direction: "desc"
+  });
   const sortIndex = sort.by in dataset.measures ? indexOf(columnAlias.measure(sort.by)) : indexOf(columnAlias.groupKey(sort.by));
   if (sortIndex >= 0)
     order.push({ index: sortIndex, direction: sort.direction });
@@ -546,8 +580,11 @@ function labelOf(dimension, key, rawLabel) {
 function shapeMeasures(dataset, measures, raw, dialect) {
   const values = {};
   for (const key of measures) {
+    const entry = measureOf(dataset, key);
+    if (entry.kind === "resolved")
+      continue;
     const value = dialect.decodeNumber(raw[columnAlias.measure(key)]);
-    values[key] = measureOf(dataset, key).result === "count" ? value ?? 0 : value;
+    values[key] = entry.result === "count" ? value ?? 0 : value;
   }
   return values;
 }
@@ -566,7 +603,7 @@ function shapeRows(dataset, query, rawRows, dialect) {
     }
     return { ...row, ...shapeMeasures(dataset, query.measures, raw, dialect) };
   });
-  return { rows, truncated };
+  return { rows, kept, truncated };
 }
 function resultNotes(dataset, query) {
   const notes = [];
@@ -613,6 +650,25 @@ function createAnalytics2(options) {
     }
     restrictedOf.set(dataset.key, restricted);
   }
+  const resolvers = options.resolvers ?? {};
+  for (const [datasetKey, entries] of Object.entries(resolvers)) {
+    const dataset = byKey.get(datasetKey);
+    if (!dataset)
+      throw new Error(`Resolvers name unknown dataset ${datasetKey}`);
+    for (const key of Object.keys(entries ?? {})) {
+      const entry = dataset.measures[key];
+      if (entry?.kind !== "resolved") {
+        throw new Error(`Resolvers name ${datasetKey}.${key}, which is not a resolved measure`);
+      }
+    }
+  }
+  for (const dataset of datasets) {
+    for (const [key, entry] of Object.entries(dataset.measures)) {
+      if (entry.kind === "resolved" && !resolvers[dataset.key]?.[key]) {
+        throw new Error(`Dataset ${dataset.key} resolves ${key} in the app, but createAnalytics has no resolver for it`);
+      }
+    }
+  }
   const now = options.now ?? (() => new Date);
   const querySchemas = new Map;
   const resultSchemas = new Map;
@@ -733,12 +789,13 @@ function createAnalytics2(options) {
     const previous = query.compareToPrevious && period ? previousPeriod(period) : null;
     return { dataset, query, tenant, timezone, period, previous, now: at };
   };
-  const runQuery = async (prepared) => {
+  const runQuery = async (prepared, ctx) => {
     const { dataset, query, tenant, timezone, period, previous, now } = prepared;
     const source = sourceFor(dataset);
     const { dialect } = source;
     const run = (statement) => source.execute(dialect.compile(statement));
     const resolvedValues = await resolveOpenValues(dataset, query, tenant, now, run, dialect);
+    const range = ({ from, to }) => ({ from, to, timezone });
     const runPeriod = async (target) => {
       const statements = periodStatements(dataset, query, {
         tenant,
@@ -751,12 +808,46 @@ function createAnalytics2(options) {
         run(statements.rows),
         statements.totals ? run(statements.totals) : null
       ]);
-      const { rows, truncated } = shapeRows(dataset, query, rawRows, dialect);
+      const { rows, kept, truncated } = shapeRows(dataset, query, rawRows, dialect);
       const totalsRow = (rawTotals ?? rawRows)[0] ?? {};
       const totals = shapeMeasures(dataset, query.measures, totalsRow, dialect);
+      for (const key of query.measures) {
+        const entry = dataset.measures[key];
+        if (entry?.kind !== "resolved")
+          continue;
+        const used = (raw) => shapeMeasures(dataset, entry.uses, raw, dialect);
+        const resolver = resolvers[dataset.key]?.[key];
+        if (!resolver)
+          throw new Error(`No resolver for ${dataset.key}.${key}`);
+        const output = await resolver({
+          rows: kept.map((raw, index) => ({
+            dimensions: Object.fromEntries(query.groupBy.map((group) => [group, rows[index]?.[group]])),
+            values: used(raw)
+          })),
+          totals: used(totalsRow),
+          groupBy: query.groupBy,
+          filters: query.filters.map((filter) => {
+            const resolved = resolvedValues.get(filter.dimension);
+            return resolved && "values" in filter ? { ...filter, values: [...resolved] } : filter;
+          }),
+          period: target ? range(target) : { all: true, timezone },
+          tenant,
+          ctx
+        });
+        if (output.rows.length !== rows.length) {
+          throw new Error(`The resolver for ${dataset.key}.${key} returned ${output.rows.length} values for ${rows.length} rows`);
+        }
+        const value = (raw) => {
+          const finite = typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+          return entry.result === "count" ? finite ?? 0 : finite;
+        };
+        rows.forEach((row, index) => {
+          row[key] = value(output.rows[index]);
+        });
+        totals[key] = value(output.totals);
+      }
       return { rows, totals, truncated };
     };
-    const range = ({ from, to }) => ({ from, to, timezone });
     const [current, before] = await Promise.all([
       runPeriod(period),
       previous && runPeriod(previous).then(({ rows, totals }) => ({
@@ -814,7 +905,7 @@ function createAnalytics2(options) {
       if (key)
         cache = result ? "hit" : "miss";
       if (!result) {
-        result = await runQuery(prepared);
+        result = await runQuery(prepared, ctx);
         if (key)
           store(key, result, entry);
       }
@@ -983,7 +1074,18 @@ function restrictedFields(dataset) {
     if (!entry)
       return [];
     const own = entry.access === undefined ? [] : [entry.access];
-    return entry.kind === "ratio" ? [...own, ...accessOf(entry.numerator), ...accessOf(entry.denominator)] : own;
+    switch (entry.kind) {
+      case "ratio":
+        return [
+          ...own,
+          ...accessOf(entry.numerator),
+          ...accessOf(entry.denominator)
+        ];
+      case "resolved":
+        return [...own, ...entry.uses.flatMap(accessOf)];
+      default:
+        return own;
+    }
   };
   return [
     ...Object.keys(measures).map((key) => ({

package/dist/{index-xf6qpmgy.js → index-psw9s799.js}

@@ -1,6 +1,6 @@
 import {
   AnalyticsError2
-} from "./index-z5xv3ffk.js";
+} from "./index-g0ah4ehn.js";
 
 // src/handler.ts
 async function queryBatch2(analytics, queries, ctx) {