#Analytics

$analytics gives your app a portable, aggregate-on-read analytics dataset. You declare the dimensions you group and filter by and the measures you aggregate once, and the same declaration runs unchanged on a relational database, in memory for tests, and on Cloudflare Workers Analytics Engine in production. Application code never names a backend - which one is bound is a runtime decision made by the alepha/api/analytics module.

It ships inside the alepha package as an api/* sub-module, with the retention sweep (AlephaApiAnalyticsRollup, covered below) and the admin surface (AlephaApiAnalyticsAdmin: dataset listing and validated aggregate queries at /api/admin/analytics/*, gated on admin:analytics:read) as separate opt-in modules alongside it:

1import { $analytics } from "alepha/api/analytics";

#Declaring a dataset

A dataset is index (which dimension Analytics Engine samples on), dimensions and measures (each a z.object(...), exactly like an $entity schema), slots (the wire format - see below), and an optional retention:

 1import { z } from "alepha"; 2import { $analytics } from "alepha/api/analytics"; 3  4class PageViews { 5  views = $analytics({ 6    index: "app", 7    dimensions: z.object({ app: z.text(), path: z.text(), country: z.text() }), 8    measures: z.object({ count: z.integer() }), 9    // Append only. A new dimension goes on the END of this list.10    slots: { dimensions: ["app", "path", "country"], measures: ["count"] },11    retention: { hot: "60d", rollup: "day", cold: "400d" },12  });13 14  async onPageView(app: string, path: string, country: string) {15    await this.views.record({ app, path, country, count: 1 });16  }17 18  async topPaths(app: string) {19    return this.views.query({20      since: "2026-01-01",21      where: { app },22      groupBy: ["path"],23      select: { count: "sum" },24      orderBy: { key: "count", direction: "desc" },25      limit: 20,26    });27  }28}

dimensions are the low-cardinality strings you group and filter by. measures are the numbers you aggregate. Both read exactly like an entity schema because that is the point - a dataset should not require learning a second schema language.

#Dataset names must be snake_case

A dataset defaults its storage-facing name to the property key it is declared on (views above), the same way $storage names a bucket from its property key. That name has to match /^[a-z][a-z0-9_]*$/ - lowercase letters, digits and underscores, starting with a letter - because it becomes a relational table name fragment and the Analytics Engine blob1 discriminator (Analytics Engine has no table concept, so several datasets share one binding and need something to tell their rows apart). A camelCase property key, which is the normal Alepha convention everywhere else, is rejected at onInit with a message suggesting the snake_case rename. If you want to keep the camelCase field, pass an explicit name:

1pageViews = $analytics({2  name: "page_views",3  index: "app",4  dimensions: z.object({ app: z.text() }),5  measures: z.object({ count: z.integer() }),6  slots: { dimensions: ["app"], measures: ["count"] },7});

#Reserved names

time_bucket is the reserved column name the relational backend uses to store the bucket itself, so it cannot be declared as a dimension or a measure. day, hour and minute are reserved as dimension names for the same reason - they are the pseudo-dimensions query() exposes for grouping by time (see Querying below), and a real dimension with any of those names would be permanently shadowed by them.

#Recording

1await this.views.record({ app, path, country, count: 1 });2 3// Or a batch:4await this.views.recordMany([5  { app, path, country: "FR", count: 1 },6  { app, path, country: "DE", count: 1 },7]);

Every row is placed by at, the instant it was taken in milliseconds, which defaults to DateTimeProvider's now: it decides the row's hour bucket, and it is the timestamp a last fold compares (see Folds). One timestamp, not two. You can also supply the bucket yourself ({ ...row, hour: "2026-08-09T14" }). Passing hour explicitly matters for anything batched or retried: Analytics Engine stamps its own write-time timestamp and cannot backdate a point, so a retried envelope has to carry the bucket it originally computed, or it lands in the wrong hour for reasons that have nothing to do with sampling.

Rows of one batch that share a bucket and every dimension are merged before they reach the backend, so two readings of the same device in the same bucket are one stored row, on every backend.

#Device clocks are clamped, not trusted

at usually comes from a device, and device clocks drift. Two rules apply in recordMany, each logged at debug with the dataset name and the offset:

• An at more than AnalyticsPrimitive.MAX_CLOCK_SKEW (5 minutes) ahead of the server clock is clamped to now. A clock running a day ahead would otherwise write into a bucket that does not exist yet, and pin last for every bucket it later folds into.
• An at older than the finest tier's keep (retention.hot) is dropped: the next sweep would delete it anyway. With no retention declared, it is kept.

Only at is clamped. An explicit hour is your own decision and is stored as given.

#Buffered recording

At high ingest rates (10k devices reporting every ten seconds is about a thousand readings a second), one record() per reading is one upsert statement each. A dataset can buffer its writes instead:

1readings = $analytics({2  // ...3  buffer: { maxRows: 1000, flushMs: 1000 },4});

Readings are folded in memory as they arrive, by bucket and dimensions and with every fold, so a flush writes one row per key however many readings it absorbed. A buffer flushes when it holds maxRows distinct keys, flushMs after its first row, and on shutdown (the stop hook awaits the last flush, before the database closes). Two flushes of one dataset never overlap.

• record() resolves once the reading is buffered, not stored. A crash loses at most one buffer per process. Leave buffer off where a caller needs the write to have landed when its await returns.
• A failed flush is retried (three attempts, with backoff), then its rows are dropped and logged at error with their count. They are never merged back into the live buffer, which would grow without bound during an outage.
• Several instances each keep their own buffer; the upsert merges their flushes.
• Analytics Engine ignores buffer, with an info log at boot: its writes are already fire-and-forget batches.

Measured on Postgres at 1,300 readings a second from two instances (10k devices, 10 minutes), both modes kept up; unbuffered, each record() took 4 ms at the median and 24 ms at p99 and the database ran at 25 to 50 % of a core, while { maxRows: 1000, flushMs: 1000 } brought that to about 2.5 %, with flushes of 17 ms at the median and 72 ms at p99. Buffering is a cost saving at that rate, not a requirement.

The buffer reports through hooks rather than a metrics dependency, so an app wires them into its own metrics: analytics:flush:success and analytics:flush:error carry { dataset, rows, durationMs } (plus error), and primitive.bufferDepth() returns the keys waiting. primitive.flush() writes the buffer now and waits for it.

#Querying

1const result = await this.views.query({2  since: "2026-01-01",3  where: { app: "lore", country: { inArray: ["FR", "DE"] } },4  groupBy: ["path"],5  select: { count: "sum" },6  orderBy: { key: "count", direction: "desc" },7  limit: 20,8});

A query gives exactly one of two windows. since and until (optional) are inclusive UTC days, YYYY-MM-DD. Omitting until reads up to the newest bucket; set it to compare complete days (yesterday against the day before) rather than a window that ends mid-day.

#Instant windows: from and to

A monitoring chart asks for "the last 15 minutes" or "from 08:00 to 10:30" in the operator's timezone. from and to are ISO 8601 instants with an offset; an instant without one is refused, because the server never guesses a timezone:

1await this.ticks.query({2  from: "2026-10-18T08:00:00+04:00", // Dubai3  to: "2026-10-18T10:30:00+04:00",4  groupBy: ["minute"],5  select: { validations: "sum" },6});

• to is optional (up to the newest bucket) and exclusive, so consecutive windows ([08:00, 09:00), [09:00, 10:00)) never count a bucket twice.
• from pairs with to and since with until; a query naming both forms, neither, or a crossed pair is refused.
• Each tier floors from and ceils to to its own resolution. Where a tier is coarser than a bound (the hour tier asked for 08:30), the bucket that straddles it is read whole rather than dropped, since dropping it would silently lose readings the window asked for, and the result carries coarsened: true: at least one returned bucket extends outside [from, to). A since/until query is never coarsened.

Days are UTC days. The day tier is keyed on UTC midnight, with no per-dataset offset. Instants cover any sub-day window in any timezone, but a local-day total (Dubai midnight to midnight is 20:00 to 20:00 UTC) is exact only while a tier finer than a day still holds the range. Once it has folded into days, the same from/to returns the whole UTC days it overlaps, flagged coarsened. An app that needs local-day totals over a long range keeps its hour tier that long (see Retention and rollup).

Analytics Engine answers since/until only, and refuses from/to with an error.

where supports equality and { inArray: [...] } - the same operator name the ORM's repository filters use, no ranges. groupBy takes any declared dimension, plus the pseudo-dimensions "minute", "hour" and "day" - grouping by "day" folds hour buckets into a daily timeline with no date arithmetic on the caller's side, whichever backend answers the query.

#Sub-hour resolution

A monitoring view asks for "the last 15 minutes" or "the last 6 hours by 5 minutes", which an hour bucket cannot answer. A dataset declares its finest bucket with resolution: "1m", "5m", "15m" or "1h" (the default, so existing datasets keep their keys).

1ticks = $analytics({2  index: "deviceId",3  resolution: "5m",4  dimensions: z.object({ deviceId: z.text() }),5  measures: z.object({ validations: z.integer() }),6  slots: { dimensions: ["deviceId"], measures: ["validations"] },7});

Sub-hour keys are YYYY-MM-DDTHH:MM, the minute floored to the resolution, so a coarser key is still a prefix of a finer one. groupBy: ["minute"] returns the stored key, "hour" its first 13 characters and "day" its first 10, whatever the resolution. A row that has already folded into the day tier keeps its day key under minute and hour: the resolution of old data is coarser, the totals are not. Sub-hour buckets fold straight into days.

A sub-hour dataset places each reading with at; the explicit hour override exists on "1h" datasets only, and is validated there. Analytics Engine refuses any resolution other than "1h" at boot: its forward to the relational tier and its watermark are hour-based.

#Folds: sum, min, max and last

A measure declares how its values combine, in folds. An undeclared measure folds ["sum"], which is a counter: validations per hour, page views per path. A gauge (temperature, cash level, ticket stock, battery) is meaningless as a sum and declares min, max and last instead:

 1readings = $analytics({ 2  index: "deviceId", 3  dimensions: z.object({ deviceId: z.text() }), 4  measures: z.object({ temperature: z.number(), validations: z.integer() }), 5  folds: { temperature: ["min", "max", "last"] }, 6  slots: { dimensions: ["deviceId"], measures: ["temperature", "validations"] }, 7}); 8  9await this.readings.record({10  deviceId,11  temperature: 21.5,12  validations: 3,13  at: sentAt,14});

select takes one fold or several. One fold keeps the measure's own name as the key; an array returns <measure>_<fold> keys, which is what a band chart (min and max as the band, last as the line) needs in one round trip. A fold the measure does not declare is refused.

1await this.readings.query({2  since: "2026-10-01",3  groupBy: ["hour"],4  select: { temperature: ["min", "max", "last"], validations: "sum" },5});6// [{ hour: "2026-10-01T08", temperature_min: 19, temperature_max: 23.5,7//    temperature_last: 21.5, validations: 41 }, ...]

• A missing reading is absent, never 0. A row may omit a gauge; nothing is stored for it, and a fold over buckets that hold no reading comes back null (sorted last by orderBy, in either direction). A sum-only measure keeps its old behaviour: omitted counts as 0.
• last is the reading with the latest at. Equal at keeps the larger value, on every backend, so memory and SQL agree. Arrival order does not matter: a device catching up after an outage lands in its old buckets and is folded by the next sweep like any other row.
• sum may sit beside gauge folds (["sum", "min", "max"]): with a count-as-sum measure, it gives a mean caller-side.

Storage. A sum-only measure is one column named after itself, exactly as before folds existed, so declaring folds on another measure changes no existing column. A measure with any other fold gets one nullable column per fold, <measure>_<fold>, plus <measure>_last_at (a bigint of milliseconds) when it declares last. A declared name equal to a derived column (a measure called temperature_min beside a gauge temperature) is refused at boot.

Every fold survives a rollup. When hour buckets fold into day buckets (see Retention and rollup), the total, the extremes and the last value of the day are computed from those of its hours alone, so no number the UI shows changes; only the time axis coarsens. That is the rule every fold has to pass, and the reason the set stops here:

• avg and percentiles are not folds. The mean of several means is wrong the moment the buckets differ in size, and the p75 of several distributions is not the mean of their p75s.
• min, max and last need an exact backend. Analytics Engine samples, and every stored row carries a _sample_interval: sum(x * _sample_interval) reconstructs a true total from a sampled window, but if the sampler drops the row holding the true extreme or the last reading, nothing recovers it. A dataset declaring any of them is refused at boot on Analytics Engine (AnalyticsProvider.exact is false there) rather than served silently wrong. It runs on the relational and in-memory backends.

#There is no count aggregate: declare a count measure and sum it

An earlier version of this package also accepted "count", meaning "the number of stored rows" rather than a sum of any measure. That number is not portable: relationally it was COUNT(*), and in memory it was one increment per recorded array entry - not the same number on identical writes (a relational upsert accumulates repeated writes into one row; an in-memory record pushes a new one), and it does not survive a rollup on either backend, because folding rows into a day bucket collapses the very thing a row count was measuring. Summing eight sums across a rollup boundary reproduces the pre-rollup total exactly; summing eight counts does not, because after the fold there are fewer, larger rows to count. count was removed rather than special-cased: a fold in this seam has to be correct after a rollup and identical across every backend, not merely plausible on the one you tested against.

The portable replacement is the pattern Lore's own sigil_views dataset already uses: declare a measure that is 1 per event (call it count, or anything else) and sum it. That is an ordinary sum, so it survives a rollup and a sampled backend for the same reason any other measure does:

1measures: z.object({ count: z.integer() }),

1await this.views.record({ app, path, country, count: 1 });

1select: { count: "sum" },

Two patterns cover what the missing aggregates would have given you, and both stay caller-side and obvious rather than needing a merge-rule enforcement layer inside the package:

• A mean: declare a sum measure and a count-as-sum measure (see above), and divide them yourself once the query returns.
• A percentile: see The histogram pattern below.

#What analytics cannot do

A dataset cannot answer "how many distinct visitors" - a distinct count cannot survive sampling (a sampled window drops rows, so a naive COUNT(DISTINCT ...) under-counts) or a rollup (once hour buckets fold into a day bucket, which visitor hashes contributed to which hour is gone). Lore keeps unique-visitor counts on its own table (LoreAnalyticsStore/sigil_uniques_daily) for exactly this reason - see that class's doc for the full argument. If your app needs distinct counts, they need their own storage; $analytics is not the tool for them.

#The histogram pattern

A percentile does not merge across buckets, but a histogram does - so a percentile is modelled as an ordinary dimension holding the bucket index, with count (or whatever you call the measure) as the thing you sum. This is exactly how Lore tracks Web Vitals:

 1import { z } from "alepha"; 2import { $analytics } from "alepha/api/analytics"; 3  4class WebVitals { 5  vitals = $analytics({ 6    name: "sigil_vitals", 7    index: "sigilId", 8    dimensions: z.object({ 9      sigilId: z.uuid(),10      metric: z.string(),11      path: z.string(),12      bucket: z.number(),13    }),14    measures: z.object({ samples: z.number() }),15    slots: {16      dimensions: ["sigilId", "metric", "path", "bucket"],17      measures: ["samples"],18    },19    retention: { hot: "30d", rollup: "day", cold: "400d" },20  });21}

bucket is not special machinery - it is the histogram's bucket index, declared as an ordinary z.number() dimension. Recording one vital sample means bucketing the raw value yourself (a CLS score, an LCP duration in milliseconds) into a bucket index and incrementing that bucket's samples count. To read a percentile back, query() grouped by ["metric", "bucket"] returns the whole histogram as flat (metric, bucket, samples) rows, and the caller walks it - sums samples from the bottom until the running total passes the target percentile of the overall count, and that bucket's midpoint is the estimate. The walk (and any un-scaling a particular metric's buckets need) belongs entirely to caller-side code; $analytics only ever stores and returns counts per bucket.

#Retention and rollup

retention is an ordered chain of tiers, finest first. Each tier keeps its buckets for keep, then the hourly sweep folds them into the next, coarser tier:

1retention: [2  { resolution: "1m", keep: "48h" },3  { resolution: "1h", keep: "30d" },4  { resolution: "1d", keep: "400d" },5],

A 1-minute dataset at 10k devices cannot keep minutes for 60 days; with this chain it keeps minutes for two days, hours for a month and days for a year:

Windows are written <n>m, <n>h or <n>d. The chain is checked at boot:

• the first tier's resolution is the dataset's resolution;
• each next resolution is strictly coarser than the previous one and a multiple of it (1m, 5m, 15m, 1h, 1d);
• each keep is a whole number of its tier's buckets, at least one bucket of the next tier (the sweep folds whole buckets only), and at least as long as the previous tier's keep, since a shorter one later in the chain would delete readings before they are ever folded;
• only the last tier may omit keep, and is then kept forever.

The original shape is still accepted and is the two-tier chain it always described:

1retention: { hot: "60d", rollup: "day", cold: "400d" }2// is3retention: [4  { resolution: "1h", keep: "60d" }, // the dataset's resolution5  { resolution: "1d", keep: "400d" },6]

Without hot, the dataset never folds and never prunes. cold must be at least as long as hot, by the same rule as any other keep.

Every fold collapses rather than deletes: folding a tier into the next groups by every declared dimension exactly as before and folds each measure by its own folds (see Folds) - no dimension is dropped or merged away, and no total, extreme or last value your UI shows ever changes. Only the resolution of the time axis does. Deletion only ever happens past the last tier's keep, to rows already folded into it. A query reads every tier and merges them, so a window spanning tiers comes back whole.

Storage. Each tier is a table with the same columns and unique index. The finest keeps analytics_<name>_raw and the coarsest analytics_<name>_rolled, the names every dataset already had; each tier in between is analytics_<name>_<resolution> (analytics_device_metrics_1h). Adding a tier to the middle of a chain adds a table, and renames none, so an existing dataset's data stays where it is. Its migration is an ordinary alepha db migrations create.

The sweep stays hourly, whatever the finest resolution: a minute tier can only fold whole hours into an hour tier, so a faster sweep would fold nothing more. Each sweep folds at most AnalyticsRollupJobs.MAX_BUCKETS_PER_SWEEP source buckets per tier (36), rounded down to whole buckets of the next tier but never less than one, and catches up over later sweeps: three hours of a 5-minute tier, or one day of an hour tier, per hourly sweep. The cap comes from a benchmark at 10k devices, where one 5-minute bucket of a gauge dataset with 34k keys folds in about 0.18 s.

#Analytics Engine keeps two tiers, and roughly 90 days of hours

Analytics Engine serves the original two-tier chain only: hours, then days. A longer chain is rejected at registration on that backend. Cloudflare also keeps Analytics Engine data for approximately 90 days regardless of what you declare, so a finest tier keeping longer (retention.hot over "90d") is rejected there too, at boot, rather than letting a report quietly come up short months later. The relational and memory backends honour any valid chain.

#Declaring retention does nothing on its own

This is the sharpest edge in the whole primitive, worth stating plainly: nothing in alepha/api/analytics enforces retention automatically. Registering $analytics() datasets - importing AlephaApiAnalytics - wires the provider and lets you record()/query(), full stop. The hourly sweep that actually folds and prunes rows lives in a separate module, AlephaApiAnalyticsRollup, which your app has to import explicitly alongside AlephaApiAnalytics:

1import { Alepha } from "alepha";2import {3  AlephaApiAnalytics,4  AlephaApiAnalyticsRollup,5} from "alepha/api/analytics";6 7const alepha = Alepha.create()8  .with(AlephaApiAnalytics)9  .with(AlephaApiAnalyticsRollup);

Forgetting AlephaApiAnalyticsRollup is silent in the sense that nothing throws: record() and query() keep working normally, and the raw table simply grows forever. It is not completely silent, though - a boot-time log.warn from the retention guard names every dataset that declares a window on its finest tier (retention.hot) while no rollup job was ever constructed, specifically so this mistake does not stay invisible once the app is actually running.

The split exists because AnalyticsRollupJobs is built on $job, and $job always needs a real database connection (it holds a $repository on its own job-execution table), in every environment including tests. Folding the rollup job into AlephaApiAnalytics directly would mean merely declaring one $analytics() field - the one thing this package promises works with no database at all - starts requiring a live database connection to boot.

#Result epistemics: estimated and sampleInterval

Every query() result carries more than rows:

1export interface AnalyticsResult {2  rows: Array<Record<string, string | number | null>>;3  estimated: boolean;4  coarsened?: boolean;5  sampleInterval?: number;6}

• rows hold null where a gauge fold covers buckets with no reading (see Folds).
• coarsened is set by a from/to query when a returned bucket extends outside the window (see Instant windows).
• estimated is false on the relational and memory backends - they never sample, so their numbers are exact by construction. It is true on Analytics Engine, which samples under load.
• sampleInterval is the largest _sample_interval seen in the window, when the backend samples. A value of 1 means no sampling actually occurred in that window, so the numbers are exact despite estimated being true - the common case at low traffic. A UI should not qualify the numbers ("approximate") when sampleInterval === 1; it should when it is greater.

The result carries this rather than a UI having to know which backend answered it, so ignoring estimated is a visible choice made in the reading code, not an accident of which environment happened to be running.

#Backends

The bound provider is a runtime decision the module makes, never something application code chooses:

AlephaApiAnalytics and most other Alepha modules ship a memory implementation as the substitutable default - see Unit Tests for the general shape.

#The Analytics Engine slot map is a wire format

Analytics Engine has no columns, only 20 positional blob slots and 20 positional double slots per data point - and two blob slots are reserved, so a dataset can declare at most 18 dimensions and 20 measures before AnalyticsSlotMap throws at boot.

Which name occupies which position is declared, not derived. slots is a pair of ordered name lists - the first dimension is blob3, the first measure is double1 - and it is required on every dataset, on every backend, from the first line it is written on:

1slots: {2  dimensions: ["app", "path", "country"],3  measures: ["count"],4},

Three rules follow, and they are the whole of it:

• Reordering the dimensions / measures object literal is a safe no-op. Nothing reads its key order.
• Adding is append-only. A new name goes on the END of its list and takes the next free slot. Inserting or reordering shifts every later name by a position, and since Analytics Engine addresses fields positionally and has no update or delete API, every row already written is then read under the wrong field, permanently.
• Renaming is breaking, and fails loudly. The new name is in dimensions and not in slots, so the dataset refuses to boot with a message naming both ways out - rather than reading history under a meaning it never had.

To retire a name, delete it from dimensions / measures and leave it in the list. Its slot stays reserved and nothing after it moves.

Slots are meaningless on the relational and in-memory backends, which address columns by name. They are still required there, because a check that only runs on the runtime that deploys is a check that never runs in CI.

This replaced a derivation from alphabetically sorted names, which had the first and third properties and not the second: a new dimension landed wherever it sorted and pushed every later one along. Adding a referrer dimension to a live dataset in 2026-08 moved its index dimension by three slots and made eight days of stored rows match no filter at all. They are still there, unreadable, and there is no API to repair them with.

The hourly sweep forwards Analytics Engine rows into the relational cold tier, which validates every dimension against its declared type, so a row like those is skipped there rather than refused: one log.warn per sweep names the dimension and what it held. Until that existed, one such row failed the whole forward, and with it every rollup of its dataset.

#The first sweeps catch up a few days at a time

On Analytics Engine the sweep forwards at most 2,000 rows into the cold tier per dataset per run, cut at a day boundary, and folds only the days it forwarded; the next run resumes where it stopped. A dataset that has never been rolled up, or has fallen weeks behind, therefore catches up over several hourly runs rather than one. The bound exists because Cloudflare D1 binds at most 100 values per statement and caps the statements one Worker invocation may run: a row of a ten-dimension dataset binds fourteen values, so forwarding a month of hourly rows in one run would not fit. The fold itself is a single INSERT … SELECT in the database, whatever the backlog.

#Registering the module

A real example, from Lore:

 1import { $module } from "alepha"; 2import { AlephaApiAnalyticsRollup } from "alepha/api/analytics"; 3  4import { LoreAnalytics } from "./entities/loreAnalytics.ts"; 5  6export const LoreApi = $module({ 7  name: "lore.api", 8  // `$analytics()` (used by `LoreAnalytics`) auto-wires `AlephaApiAnalytics` itself 9  // the moment a dataset is injected - the same module-tagging mechanism10  // `$repository` uses for `AlephaOrm`. The retention sweep does not auto-wire:11  // it needs its own explicit import, or retention silently does nothing.12  imports: [AlephaApiAnalyticsRollup],13  services: [LoreAnalytics /* ...the rest of the app's services */],14});

LoreAnalytics itself just declares two datasets - this is close to the real entities/loreAnalytics.ts in the Lore repository:

 1import { z } from "alepha"; 2import { $analytics } from "alepha/api/analytics"; 3import { db } from "alepha/orm"; 4  5import { sigils } from "./sigils.ts"; 6  7export class LoreAnalytics { 8  public readonly views = $analytics({ 9    name: "sigil_views",10    index: "sigilId",11    dimensions: z.object({12      // db.ref works inside a dimension exactly like inside an $entity schema:13      // the relational backend gets a real foreign key with ON DELETE CASCADE,14      // Memory and Analytics Engine are unaffected since both only ever read15      // the dimension names, never the zod metadata attached to them.16      sigilId: db.ref(z.uuid(), () => sigils.cols.id, { onDelete: "cascade" }),17      path: z.string(),18      country: z.string(),19    }),20    measures: z.object({ count: z.number() }),21    slots: {22      dimensions: ["sigilId", "path", "country"],23      measures: ["count"],24    },25    retention: { hot: "30d", rollup: "day", cold: "400d" },26  });27}

#Scoping the query builder to one tenant

AlephaApiAnalyticsAdmin serves every dataset in the container to anyone holding admin:analytics:read. To offer the same query builder to a non-admin over their own slice of the data, keep the service and write your own controller around it: both of its methods take an optional scope.

 1import { $inject, z } from "alepha"; 2import { 3  adminAnalyticsQuerySchema, 4  adminAnalyticsResultSchema, 5  AdminAnalyticsService, 6  adminDatasetSchema, 7} from "alepha/api/analytics"; 8import { $secure } from "alepha/security"; 9import { $action } from "alepha/server";10 11export class TenantAnalyticsController {12  protected service = $inject(AdminAnalyticsService);13 14  listTenantDatasets = $action({15    use: [$secure({ permissions: ["tenant:read"] })],16    method: "GET",17    path: "/tenants/:tenantId/analytics/datasets",18    schema: {19      params: z.object({ tenantId: z.uuid() }),20      response: z.array(adminDatasetSchema),21    },22    handler: async ({ params }) => {23      // Prove the caller may read THIS tenant before anything else. That check24      // is the one thing the framework cannot write for you.25      return this.service.listDatasets({ pin: { tenantId: params.tenantId } });26    },27  });28 29  queryTenantDataset = $action({30    use: [$secure({ permissions: ["tenant:read"] })],31    method: "POST",32    path: "/tenants/:tenantId/analytics/datasets/:name/query",33    schema: {34      params: z.object({ tenantId: z.uuid(), name: z.text() }),35      body: adminAnalyticsQuerySchema,36      response: adminAnalyticsResultSchema,37    },38    handler: async ({ params, body }) => {39      return this.service.queryDataset(params.name, body, {40        pin: { tenantId: params.tenantId },41      });42    },43  });44}

pin does three things, and the first is what makes a generic UI safe on a scoped surface:

• It removes the pinned dimensions from the published descriptors. A scoped caller is never told tenantId exists, so a query builder driven by those descriptors cannot offer it as a group-by key, as a filter, or as a filter value - without a single line of that UI knowing a scope is in play.
• It refuses a query that names a pinned key, in where or in groupBy, with a BadRequestError. The pin is a vocabulary restriction, not a default the caller may override. Silently overwriting would be worse than refusing: the caller believes it filtered, and it did not.
• It hides datasets it cannot narrow. A dataset that does not declare every pinned dimension is absent from listDatasets and answers NotFoundError from queryDataset, because the alternative is serving it whole to a scoped caller - exactly the moment the scope mattered most.

That last point makes the allowlist derived rather than written: a new dataset carrying tenantId appears with no change to the controller, and one without it can never appear at all.

The scope is not a UI concern. Anyone can post the request body themselves, so a control the page hides protects nothing. pin is enforced in the service, behind your own authorization check, which is why the two live together in the handler above.

On the client, @alepha/ui's AdminAnalytics takes an optional transport so the same panel can point at this controller instead of the admin one:

1<AdminAnalytics2  transport={{3    listDatasets: () => client.listTenantDatasets({ params }),4    queryDataset: (dataset, body) =>5      client.queryTenantDataset({ params: { ...params, name: dataset }, body }),6    path: (dataset) =>7      `/api/tenants/${tenantId}/analytics/datasets/${dataset}/query`,8  }}9/>

Memoise that object: it is an effect dependency inside the panel, so a fresh one per render re-fires every query forever.

#Testing

MemoryAnalyticsProvider is bound automatically under alepha.isTest() - no substitution needed, and no sampling to account for in assertions:

 1import { Alepha, z } from "alepha"; 2import { $analytics, AlephaApiAnalytics } from "alepha/api/analytics"; 3  4class Stats { 5  views = $analytics({ 6    index: "app", 7    dimensions: z.object({ app: z.text() }), 8    measures: z.object({ count: z.integer() }), 9    slots: { dimensions: ["app"], measures: ["count"] },10  });11}12 13const alepha = Alepha.create().with(AlephaApiAnalytics);14const stats = alepha.inject(Stats);15await alepha.start();16 17await stats.views.record({ app: "lore", count: 1 });18const result = await stats.views.query({19  since: "2026-01-01",20  select: { count: "sum" },21});22 23expect(result.estimated).toBe(false);24expect(result.rows[0].count).toBe(1);