measurr 0.2.0 → 0.3.0

package/README.md

@@ -10,8 +10,9 @@ returns shaped, typed rows.
 - Database-neutral definitions: dialects plug in through the `Dialect` interface, and Postgres
   ships today (`measurr/postgres`).
 - Tenant-scoped by construction: the engine adds the tenant filter to every statement and
-  refuses to run without a tenant. Platform admins can query every tenant only through an
-  explicit `allTenants` value that no query input can carry.
+  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
+  query input can carry.
 - The query schema is generated with Zod, so it doubles as an LLM tool schema
   (`z.toJSONSchema`) and as the request validator. It can be built per caller, offering only
   the datasets they may query.
@@ -154,9 +155,21 @@ What the hook throws or rejects with is swallowed; it cannot fail a query.
 ## Tenants and platform admins
 
 `tenant(ctx)` decides the scope of every statement, including the lookups that resolve filter
-labels. It returns a tenant id, or `allTenants` to drop the tenant filter for a caller allowed
-to see every tenant. Anything else (null, undefined, `''`, any other value) is refused with
-`AnalyticsError('missing_tenant')`, so a missing organization never widens a query.
+labels. It returns a tenant id (`TenantId`, a non-empty string or a finite number), a readonly
+list of them, or `allTenants` to drop the tenant filter for a caller allowed to see every
+tenant. Anything else is refused with `AnalyticsError('missing_tenant')`: null, undefined,
+`''`, a list containing one of those or `allTenants`, or any other value. A missing
+organization never widens a query.
+
+A list compiles to `tenantColumn IN (...)` with one parameter per id; a one-element list is
+the same statement as its id. An empty list is a scope that matches no rows: a reseller with
+no connected organizations sees zeros, never everything. Lists are for callers scoped to a set
+of organizations, such as an organization-group admin, a reseller, or either narrowed to a
+region:
+
+```ts
+tenant: (ctx: Ctx) => ctx.visibleOrganizationIds // readonly OrganizationId[]
+```
 
 The scope comes only from `ctx`, which your server builds from the session. `allTenants` is a
 symbol, so a query (JSON, a model's tool call) cannot carry it. A discriminated context keeps
@@ -187,11 +200,11 @@ name.
 
 | Concept | What it is |
 | --- | --- |
-| Dataset | One fact table: tenant column, optional scope, time fields, measures, dimensions, source. |
+| Dataset | One fact table: tenant column, 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). |
 | Dimension | `enum`, `computed` (closed value sets), `relation` (to-one), `manyToMany`, `number`, `timeBucket` (day, ISO week, month), `timePart` (ISO weekday, hour). |
 | 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 }`. |
+| Result | `{ period, rows, totals, previous?, notes, truncated }`; `period` is `{ from, to, timezone }` or `{ all: true, timezone }`. |
 
 **Operators per dimension kind.** Closed and open dimensions take `in`, `notIn`, `isEmpty`
 and `isNotEmpty`; numeric and time dimensions take `between`, `isEmpty` and `isNotEmpty`. The
@@ -222,6 +235,21 @@ try {
 The previous period has the same length and ends the day before. Time buckets use the same
 timezone. `time` picks the time field the period applies to; a time dimension names its own.
 
+`{ all: true }` drops the time filter: every row counts, and time buckets and parts still group
+by the time field. It has no previous period, so `compareToPrevious` with it is an
+`invalid_query`. The result's `period` is then `{ all: true, timezone }` instead of
+`{ from, to, timezone }`; `previous.period` is always a range. The type follows the query. A
+query that names a range, or names no period on a dataset whose default is a range, gets
+`{ from, to, timezone }`, so `result.period.from` needs no narrowing. A query typed only as
+`AnalyticsQuery` (parsed from the schema) gets the `ResultPeriod` union; narrow it with
+`'all' in result.period`.
+
+A query that names no period (or sends null) gets the dataset's `defaultPeriod`, the last 30
+days unless the dataset says otherwise. A dataset that describes current state (units,
+organizations) sets `defaultPeriod: { all: true }`, so "how many units per status" counts
+every unit. The generated schema states each dataset's default, so a model knows what leaving
+`period` out means.
+
 **Totals are a separate, ungrouped statement**, so a many-to-many grouping (an order with
 two tags appears in two rows) never inflates them. Filters on many-to-many dimensions compile
 to `EXISTS`, so they never multiply rows either.
@@ -315,8 +343,8 @@ await assertDatasetContract({ dataset: orders, source, tenant: seededTenantId })
 It checks that every measure runs and returns a number or null, every grouping runs and its
 groups add up to the total (except many-to-many), `isEmpty` plus `isNotEmpty` equals the total,
 open dimensions filter by label to their group's count, closed dimensions filter by value, an
-empty tenant sees nothing (tenant isolation), and day buckets in a far-from-UTC timezone
-(default `Pacific/Auckland`) agree with single-day periods.
+empty tenant and an empty tenant list see nothing (tenant isolation), and day buckets in a
+far-from-UTC timezone (default `Pacific/Auckland`) agree with single-day periods.
 
 ## Extending
 
@@ -336,11 +364,11 @@ empty tenant sees nothing (tenant isolation), and day buckets in a far-from-UTC
 
 Kept stable for publishing: `createAnalytics` and its options, `allTenants`, `analytics.query`,
 `explain`, `querySchema`, `resultSchema`, `listDatasets`; `AnalyticsResultSchema`,
-`analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset`, `measure.*`,
-`dimension.*`, `table` / `Table`, the expression builders; the `Dialect`, `SqlRenderer` and
-`AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
-`assertDatasetContract`; and the types
-`AnalyticsQuery`, `AnalyticsResult`, `Ratio`, `AnalyticsError` codes and their details
+`analyticsToolGuidance`, `AnalyticsQueryEvent`; `defineDataset` (with `defaultPeriod`),
+`measure.*`, `dimension.*`, `table` / `Table`, the expression builders; the `Dialect`,
+`SqlRenderer` and `AnalyticsSource` contracts; `postgresDialect`, `checkDatasetContract` /
+`assertDatasetContract`; and the types `AnalyticsQuery`, `AnalyticsResult`, `ResultPeriod`,
+`PeriodInput`, `Tenant`, `TenantId`, `Ratio`, `AnalyticsError` codes and their details
 (`isAnalyticsError`). `ExprNode` and `SelectStatement` are
 exported for dialect authors and may grow new node kinds.
 

package/dist/analytics.d.ts

@@ -58,9 +58,10 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
     /** Databases by name; a dataset's `source` picks one, or the only one is used. */
     sources: Record<string, AnalyticsSource>;
     /**
-     * The tenant every query is scoped to. Queries without one (null, undefined, '') are
-     * refused. Return `allTenants` to drop the tenant filter, only for callers allowed to see
-     * every tenant's rows.
+     * The tenant every query is scoped to, or a list of them (an empty list matches no rows).
+     * Queries without one (null, undefined, '', a list holding one of those) are refused.
+     * Return `allTenants` to drop the tenant filter, only for callers allowed to see every
+     * tenant's rows.
      */
     tenant: (ctx: Ctx) => Tenant | null | undefined;
     /**

package/dist/dataset.d.ts

@@ -1,4 +1,5 @@
 import { type Expr, type ExprNode, type SqlType, type Table, type TableRef, type TimeBucketUnit, type TimePartName } from './expr.js';
+import { DEFAULT_PERIOD, type PeriodInput } from './period.js';
 declare const ratioBrand: unique symbol;
 /** A share or ratio between 0 and 1. Branded so nobody renders 0.42 as "0.42%". */
 export type Ratio = number & {
@@ -241,7 +242,7 @@ export type TimeField = {
     readonly column: ExprNode;
     readonly label: string;
 };
-export type Dataset<K extends string = string, M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>, T extends string = string> = {
+export type Dataset<K extends string = string, M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>, T extends string = string, P extends PeriodInput = PeriodInput> = {
     readonly key: K;
     readonly label: string;
     readonly description: string;
@@ -251,6 +252,8 @@ export type Dataset<K extends string = string, M extends Record<string, AnyMeasu
     readonly scope: ExprNode | null;
     readonly time: Readonly<Record<T, TimeField>>;
     readonly defaultTime: T;
+    /** Kept as a type, so results know whether a query without a period covers all time. */
+    readonly defaultPeriod: P;
     readonly measures: M;
     readonly dimensions: Dm;
 };
@@ -272,7 +275,7 @@ type CheckDimensions<Dm, T extends string> = {
         time: T;
     } : unknown;
 };
-export type DatasetDefinition<K extends string, M extends Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension>, T extends string> = {
+export type DatasetDefinition<K extends string, M extends Record<string, AnyMeasure>, Dm extends Record<string, AnyDimension>, T extends string, P extends PeriodInput> = {
     key: K;
     label: string;
     /** Tells a reader (and a model) what one row of the dataset is. */
@@ -292,6 +295,11 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
     }>;
     /** The time field periods apply to when a query names none; the first one by default. */
     defaultTime?: NoInfer<T> | undefined;
+    /**
+     * The period of a query that names none; the last 30 days by default. A dataset of current
+     * state (units, organizations) sets `{ all: true }`.
+     */
+    defaultPeriod?: P | undefined;
     measures: M & CheckMeasures<M>;
     dimensions: Dm & CheckDimensions<Dm, NoInfer<T>>;
 };
@@ -299,5 +307,5 @@ export type DatasetDefinition<K extends string, M extends Record<string, AnyMeas
  * Declares a dataset: one fact table with its tenant column, time fields, measures and
  * dimensions. Keys stay literal types, so queries and result rows are typed from it.
  */
-export declare function defineDataset<const K extends string, const M extends Record<string, AnyMeasure>, const Dm extends Record<string, AnyDimension>, const T extends string>(definition: DatasetDefinition<K, M, Dm, T>): Dataset<K, M, Dm, T>;
+export declare function defineDataset<const K extends string, const M extends Record<string, AnyMeasure>, const Dm extends Record<string, AnyDimension>, const T extends string, const P extends PeriodInput = typeof DEFAULT_PERIOD>(definition: DatasetDefinition<K, M, Dm, T, P>): Dataset<K, M, Dm, T, P>;
 export {};

package/dist/guidance.d.ts

@@ -2,4 +2,4 @@
  * How a model should use an analytics query tool, as markdown bullets for its instructions.
  * It does not name the tool, so add a line that does.
  */
-export declare const analyticsToolGuidance = "- Answer every \"how many\", \"how much\", \"per week\" or \"split by\" question with the analytics tool. Never count by hand from lists or pages.\n- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.\n- Say which period and filters the numbers cover, using the dates in the result (\"1-30 September\").\n- Compare with the previous period (compareToPrevious) when the change is the point, such as \"is it going up\".\n- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.\n- Ask one short question only when the period is genuinely ambiguous (\"this season\") and someone can answer; otherwise take the natural reading and state it.";
+export declare const analyticsToolGuidance = "- Answer every \"how many\", \"how much\", \"per week\" or \"split by\" question with the analytics tool. Never count by hand from lists or pages.\n- Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.\n- Say which period and filters the numbers cover, using the dates in the result (\"1-30 September\", or \"all time\").\n- Compare with the previous period (compareToPrevious) when the change is the point, such as \"is it going up\".\n- When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.\n- Ask one short question only when the period is genuinely ambiguous (\"this season\") and someone can answer; otherwise take the natural reading and state it.";

package/dist/{index-dj3369zz.js → index-wrr67sxq.js}

@@ -8,7 +8,9 @@ import { z } from "zod";
 
 // src/period.ts
 var MAX_PERIOD_DAYS = 731;
-var DEFAULT_PERIOD = { last: { days: 30 } };
+var DEFAULT_PERIOD = {
+  last: { days: 30 }
+};
 var DAY_MS = 86400000;
 var formatterCache = new Map;
 function formatter(timezone) {
@@ -165,8 +167,18 @@ var periodSchema = z.union([
     })
   }),
   z.object({ from: isoDate, to: isoDate.describe("Last day, inclusive.") }),
-  z.object({ preset: z.enum(PERIOD_PRESETS) })
-]).describe("Which days to count, in the organization timezone. Defaults to the last 30 days. At most two years.");
+  z.object({ preset: z.enum(PERIOD_PRESETS) }),
+  z.object({ all: z.literal(true) }).describe("Every row, with no time filter.")
+]);
+function describePeriod(period) {
+  if ("all" in period)
+    return "all time (no time filter)";
+  if ("last" in period)
+    return `the last ${period.last.days} days`;
+  if ("from" in period)
+    return `${period.from} to ${period.to}`;
+  return period.preset;
+}
 function describeList(entries) {
   return entries.map(([key, entry]) => `${key}: ${entry.label}${entry.description ? ` (${entry.description})` : ""}`).join(" · ");
 }
@@ -247,11 +259,11 @@ function datasetQuerySchema(dataset) {
     ...firstFilter && {
       filters: z.array(z.discriminatedUnion("dimension", [firstFilter, ...otherFilters])).optional().describe("Every filter must match.")
     },
-    period: periodSchema.nullish(),
+    period: periodSchema.describe(`Which days to count, in the organization timezone. Defaults to ${describePeriod(dataset.defaultPeriod)}. A range covers at most two years.`).nullish(),
     ...timeKeys && {
       time: z.enum(timeKeys).optional().describe(`Which time field the period applies to; time dimensions name their own. Defaults to ${dataset.defaultTime}. ${describeList(Object.entries(dataset.time))}`)
     },
-    compareToPrevious: z.boolean().optional().describe("Also return the previous period of the same length."),
+    compareToPrevious: z.boolean().optional().describe("Also return the previous period of the same length. Not for all-time periods."),
     sort: z.object({
       by: z.enum(sortKeys),
       direction: z.enum(["asc", "desc"]).optional()
@@ -268,6 +280,14 @@ function datasetQuerySchema(dataset) {
         message: `Sort by one of the asked measures or grouped dimensions: ${returned.join(", ")}`
       });
     }
+    const period = query.period ?? dataset.defaultPeriod;
+    if (query.compareToPrevious && "all" in period) {
+      context.addIssue({
+        code: "custom",
+        path: ["compareToPrevious"],
+        message: "An all-time period has no previous period to compare with"
+      });
+    }
   });
 }
 function buildQuerySchema(datasets) {
@@ -276,11 +296,15 @@ function buildQuerySchema(datasets) {
     throw new Error("querySchema needs at least one dataset");
   return z.discriminatedUnion("dataset", [first, ...rest]);
 }
-var periodOutput = z.object({
+var rangeOutput = z.object({
   from: z.string(),
   to: z.string(),
   timezone: z.string()
 });
+var periodOutput = z.union([
+  rangeOutput,
+  z.object({ all: z.literal(true), timezone: z.string() })
+]);
 var measureValue = z.number().nullable();
 var dimensionValue = z.object({
   key: z.union([z.string(), z.number()]).nullable(),
@@ -291,7 +315,7 @@ function resultSchemaOf(row, totals) {
     period: periodOutput,
     rows: z.array(row),
     totals,
-    previous: z.object({ period: periodOutput, rows: z.array(row), totals }).optional(),
+    previous: z.object({ period: rangeOutput, rows: z.array(row), totals }).optional(),
     notes: z.array(z.string()),
     truncated: z.boolean()
   });
@@ -317,7 +341,7 @@ function normalizeQuery(dataset, parsed) {
     measures: [...new Set(parsed.measures)],
     groupBy: [...new Set(parsed.groupBy ?? [])],
     filters,
-    period: parsed.period ?? DEFAULT_PERIOD,
+    period: parsed.period ?? dataset.defaultPeriod,
     time: parsed.time ?? dataset.defaultTime,
     compareToPrevious: parsed.compareToPrevious ?? false,
     sort: parsed.sort ? { by: parsed.sort.by, direction: parsed.sort.direction ?? "desc" } : null,
@@ -411,14 +435,22 @@ function dimensionNodes(dataset, key, timezone) {
   }
 }
 function baseWhere(dataset, tenant, period) {
-  const where = tenant === allTenants2 ? [] : [
-    {
+  const where = [];
+  if (tenant !== allTenants2) {
+    const ids = typeof tenant === "object" ? [...new Set(tenant)] : [tenant];
+    const [only] = ids;
+    where.push(ids.length === 1 && only !== undefined ? {
       kind: "compare",
       op: "=",
       left: dataset.tenantColumn,
-      right: param(tenant)
-    }
-  ];
+      right: param(only)
+    } : {
+      kind: "in",
+      item: dataset.tenantColumn,
+      values: ids.map(param),
+      negated: false
+    });
+  }
   if (dataset.scope)
     where.push(dataset.scope);
   if (period) {
@@ -520,7 +552,7 @@ function planQuery(dataset, query, context, grouped) {
     });
   }
   const where = [
-    ...baseWhere(dataset, context.tenant, {
+    ...baseWhere(dataset, context.tenant, context.period && {
       time: query.time,
       start: context.period.start,
       end: context.period.end
@@ -778,14 +810,14 @@ function createAnalytics2(options) {
     const at = now();
     let period;
     try {
-      period = resolvePeriod(query.period, timezone, at);
+      period = "all" in query.period ? null : resolvePeriod(query.period, timezone, at);
     } catch (error) {
       if (error instanceof PeriodError) {
         throw new AnalyticsError2("invalid_period", error.message);
       }
       throw error;
     }
-    const previous = query.compareToPrevious ? previousPeriod(period) : null;
+    const previous = query.compareToPrevious && period ? previousPeriod(period) : null;
     return { dataset, query, tenant, timezone, period, previous, now: at };
   };
   const runQuery = async (input, ctx) => {
@@ -809,24 +841,22 @@ function createAnalytics2(options) {
       const { rows, truncated } = shapeRows(dataset, query, rawRows, dialect);
       const totalsRow = (rawTotals ?? rawRows)[0] ?? {};
       const totals = shapeMeasures(dataset, query.measures, totalsRow, dialect);
-      const periodOut = { from: target.from, to: target.to, timezone };
-      return { period: periodOut, rows, totals, truncated };
+      return { rows, totals, truncated };
     };
+    const range = ({ from, to }) => ({ from, to, timezone });
     const [current, before] = await Promise.all([
       runPeriod(period),
-      previous ? runPeriod(previous) : null
+      previous && runPeriod(previous).then(({ rows, totals }) => ({
+        period: range(previous),
+        rows,
+        totals
+      }))
     ]);
     return {
-      period: current.period,
+      period: period ? range(period) : { all: true, timezone },
       rows: current.rows,
       totals: current.totals,
-      ...before && {
-        previous: {
-          period: before.period,
-          rows: before.rows,
-          totals: before.totals
-        }
-      },
+      ...before && { previous: before },
       notes: resultNotes(dataset, query),
       truncated: current.truncated
     };
@@ -888,7 +918,10 @@ function createAnalytics2(options) {
   };
 }
 function isTenant(value) {
-  return value === allTenants2 || typeof value === "string" && value !== "" || typeof value === "number" && Number.isFinite(value);
+  return value === allTenants2 || isTenantId(value) || Array.isArray(value) && value.every(isTenantId);
+}
+function isTenantId(value) {
+  return typeof value === "string" && value !== "" || typeof value === "number" && Number.isFinite(value);
 }
 function periodStatements(dataset, query, context) {
   const grouped = query.groupBy.length > 0;
@@ -1177,6 +1210,7 @@ function defineDataset2(definition) {
     scope: definition.scope?.node ?? null,
     time,
     defaultTime: definition.defaultTime ?? firstTime[0],
+    defaultPeriod: definition.defaultPeriod ?? DEFAULT_PERIOD,
     measures: definition.measures,
     dimensions: definition.dimensions
   };

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { type AnyDataset, type AnyDimension, type AnyMeasure, type Dataset, type
 export { and, caseWhen, coalesce, type ColumnKey, eq, Expr, type ExprNode, exists, gt, gte, inList, isNotNull, isNull, literal, lt, lte, minutesAgo, ne, not, or, type SqlType, Table, type TableRef, table, toText } from './expr.js';
 export { analyticsToolGuidance } from './guidance.js';
 export type { PeriodInput, PeriodPreset } from './period.js';
-export { allTenants, type Tenant } from './plan.js';
-export { AnalyticsResultSchema, type DatasetFilter, type DatasetQuery, type QueryResult, type ResultOf } from './query.js';
+export { allTenants, type Tenant, type TenantId } from './plan.js';
+export { AnalyticsResultSchema, type DatasetFilter, type DatasetQuery, type QueryResult, type ResultOf, type ResultPeriod } from './query.js';

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   measure2,
   dimension2,
   defineDataset2
-} from "./index-dj3369zz.js";
+} from "./index-wrr67sxq.js";
 import {
   CompileError2,
   decodeNumber2,
@@ -39,7 +39,7 @@ import {
 // src/guidance.ts
 var analyticsToolGuidance = `- Answer every "how many", "how much", "per week" or "split by" question with the analytics tool. Never count by hand from lists or pages.
 - Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.
-- Say which period and filters the numbers cover, using the dates in the result ("1-30 September").
+- Say which period and filters the numbers cover, using the dates in the result ("1-30 September", or "all time").
 - Compare with the previous period (compareToPrevious) when the change is the point, such as "is it going up".
 - When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.
 - Ask one short question only when the period is genuinely ambiguous ("this season") and someone can answer; otherwise take the natural reading and state it.`;

package/dist/period.d.ts

@@ -4,7 +4,8 @@
  * database compares plain timestamps and can use its time index.
  */
 export type PeriodPreset = 'today' | 'yesterday' | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'thisYear';
-export type PeriodInput = {
+/** A range of days: what `resolvePeriod` turns into instants. */
+export type PeriodRange = {
     last: {
         days: number;
     };
@@ -14,6 +15,10 @@ export type PeriodInput = {
 } | {
     preset: PeriodPreset;
 };
+/** A range of days, or `{ all: true }` for no time filter. */
+export type PeriodInput = PeriodRange | {
+    all: true;
+};
 export type ResolvedPeriod = {
     /** First local day, `YYYY-MM-DD`. */
     from: string;
@@ -27,7 +32,11 @@ export type ResolvedPeriod = {
     days: number;
 };
 export declare const MAX_PERIOD_DAYS = 731;
-export declare const DEFAULT_PERIOD: PeriodInput;
+export declare const DEFAULT_PERIOD: {
+    readonly last: {
+        readonly days: 30;
+    };
+};
 /** True for an IANA name the runtime knows. Names are also inlined in SQL, so be strict. */
 export declare function isValidTimezone(timezone: string): boolean;
 /** The local calendar date of `instant` in `timezone`, as `YYYY-MM-DD`. */
@@ -39,6 +48,6 @@ export declare class PeriodError extends Error {
     readonly name = "PeriodError";
 }
 /** Resolves a period input to local days and instants in `timezone`. */
-export declare function resolvePeriod(input: PeriodInput, timezone: string, now: Date): ResolvedPeriod;
+export declare function resolvePeriod(input: PeriodRange, timezone: string, now: Date): ResolvedPeriod;
 /** The period of equal length that ends the day before `period` starts. */
 export declare function previousPeriod(period: ResolvedPeriod): ResolvedPeriod;

package/dist/plan.d.ts

@@ -1,6 +1,6 @@
 import type { Dialect, SelectStatement } from './compile.js';
 import type { AnyDataset } from './dataset.js';
-import { type PeriodInput, type ResolvedPeriod } from './period.js';
+import type { PeriodInput, ResolvedPeriod } from './period.js';
 /** A parsed query with every default filled in and duplicates removed. */
 export type NormalizedQuery = {
     dataset: string;
@@ -50,13 +50,15 @@ export declare function normalizeQuery(dataset: AnyDataset, parsed: ParsedQuery)
  * symbol, so no query input (JSON, a model's tool call) can ever carry it.
  */
 export declare const allTenants: unique symbol;
-/** One tenant's id, or `allTenants`. */
-export type Tenant = string | number | typeof allTenants;
+export type TenantId = string | number;
+/** One tenant's id, a list of them (an empty list matches no rows), or `allTenants`. */
+export type Tenant = TenantId | readonly TenantId[] | typeof allTenants;
 /** What the planner needs besides the query: values from the hooks and resolved labels. */
 export type PlanContext = {
     tenant: Tenant;
     timezone: string;
-    period: ResolvedPeriod;
+    /** Null for an all-time period: no time filter. */
+    period: ResolvedPeriod | null;
     /** The moment the query runs. */
     now: Date;
     /** Keys for filters on open dimensions, after label resolution, by dimension. */

package/dist/query.d.ts

@@ -80,14 +80,30 @@ export type ResultRow<M, Dm, MeasureKey extends string, GroupKey extends string>
 export type ResultTotals<M, MeasureKey extends string> = Simplify<{
     [Key in MeasureKey & keyof M]: MeasureValue<M[Key]>;
 }>;
-export type QueryResult<Row, Totals> = {
-    period: {
-        from: string;
-        to: string;
-        timezone: string;
-    };
+/** The days a result covers: local days `from` to `to` (inclusive), or all time. */
+export type ResultPeriod = {
+    from: string;
+    to: string;
+    timezone: string;
+} | {
+    all: true;
+    timezone: string;
+};
+/** The period query `Q` names; null or none means the dataset's `Default`. */
+type QueryPeriod<Q, Default> = Q extends unknown ? 'period' extends keyof Q ? OrDefault<Q['period' & keyof Q], Default> : Default : never;
+type OrDefault<P, Default> = P extends null | undefined ? Default : P;
+type PeriodShape<P> = P extends {
+    all: true;
+} ? Extract<ResultPeriod, {
+    all: true;
+}> : Exclude<ResultPeriod, {
+    all: true;
+}>;
+export type QueryResult<Row, Totals, Period extends ResultPeriod = ResultPeriod> = {
+    period: Period;
     rows: Row[];
     totals: Totals;
+    /** Only for a range: an all-time period has no previous period. */
     previous?: {
         period: {
             from: string;
@@ -101,28 +117,10 @@ export type QueryResult<Row, Totals> = {
     truncated: boolean;
 };
 /** The typed result of query `Q` against the datasets `DS`. */
-export type ResultOf<DS, Q> = DS extends Dataset<infer K, infer M, infer Dm, string> ? Q extends {
+export type ResultOf<DS, Q> = DS extends Dataset<infer K, infer M, infer Dm, string, infer P> ? Q extends {
     dataset: K;
     measures: readonly (infer Mk extends string)[];
-} ? QueryResult<ResultRow<M, Dm, Mk, GroupKeys<Q>>, ResultTotals<M, Mk>> : never : never;
-export declare const periodSchema: z.ZodUnion<readonly [z.ZodObject<{
-    last: z.ZodObject<{
-        days: z.ZodNumber;
-    }, z.core.$strip>;
-}, z.core.$strip>, z.ZodObject<{
-    from: z.ZodISODate;
-    to: z.ZodISODate;
-}, z.core.$strip>, z.ZodObject<{
-    preset: z.ZodEnum<{
-        lastMonth: "lastMonth";
-        lastWeek: "lastWeek";
-        thisMonth: "thisMonth";
-        thisWeek: "thisWeek";
-        thisYear: "thisYear";
-        today: "today";
-        yesterday: "yesterday";
-    }>;
-}, z.core.$strip>]>;
+} ? QueryResult<ResultRow<M, Dm, Mk, GroupKeys<Q>>, ResultTotals<M, Mk>, PeriodShape<QueryPeriod<Q, P>>> : never : never;
 /** The input schema branch for one dataset. */
 export declare function datasetQuerySchema(dataset: AnyDataset): z.ZodObject<{
     dataset: z.ZodLiteral<string>;
@@ -250,6 +248,8 @@ export declare function datasetQuerySchema(dataset: AnyDataset): z.ZodObject<{
             today: "today";
             yesterday: "yesterday";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
     time?: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
@@ -393,6 +393,8 @@ export declare function buildQuerySchema(datasets: readonly AnyDataset[]): z.Zod
             today: "today";
             yesterday: "yesterday";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
     time?: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
@@ -534,6 +536,8 @@ export declare function buildQuerySchema(datasets: readonly AnyDataset[]): z.Zod
             today: "today";
             yesterday: "yesterday";
         }>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
     time?: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
@@ -552,11 +556,14 @@ export declare function buildQuerySchema(datasets: readonly AnyDataset[]): z.Zod
 }, z.core.$strip>[]], "dataset">;
 /** The result schema for one dataset. Row fields exist only for grouped dimensions. */
 export declare function datasetResultSchema(dataset: AnyDataset): z.ZodObject<{
-    period: z.ZodObject<{
+    period: z.ZodUnion<readonly [z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         timezone: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
+        timezone: z.ZodString;
+    }, z.core.$strip>]>;
     rows: z.ZodArray<z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodNullable<z.ZodNumber>> | z.ZodOptional<z.ZodObject<{
             key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
@@ -591,11 +598,14 @@ export declare function datasetResultSchema(dataset: AnyDataset): z.ZodObject<{
  * For contracts that must not depend on the dataset list, such as an LLM tool's output.
  */
 export declare const AnalyticsResultSchema: z.ZodObject<{
-    period: z.ZodObject<{
+    period: z.ZodUnion<readonly [z.ZodObject<{
         from: z.ZodString;
         to: z.ZodString;
         timezone: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        all: z.ZodLiteral<true>;
+        timezone: z.ZodString;
+    }, z.core.$strip>]>;
     rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         key: z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
         label: z.ZodString;

package/dist/testing.js

@@ -3,7 +3,7 @@ import {
   createAnalytics2,
   measure2,
   dimension2
-} from "./index-dj3369zz.js";
+} from "./index-wrr67sxq.js";
 
 // src/testing.ts
 var COUNT = "__contractCount";
@@ -128,26 +128,31 @@ async function checkDatasetContract(options) {
       });
     }
   }
-  await check("tenant isolation", async () => {
-    const measures = Object.keys(probe.measures);
-    const leaked = [];
-    for (let start = 0;start < measures.length; start += MAX_MEASURES) {
-      const batch = measures.slice(start, start + MAX_MEASURES);
-      const other = await run({ measures: batch }, emptyTenant);
-      leaked.push(...Object.entries(other.totals).filter(([, value]) => value !== 0 && value !== null));
-    }
-    if (leaked.length > 0) {
-      return `an empty tenant sees ${leaked.map(([key, value]) => `${key}=${value}`).join(", ")}`;
-    }
-    for (const [key, entry] of dimensions) {
-      if (!entry.groupable)
-        continue;
-      const grouped = await run({ measures: [COUNT], groupBy: [key] }, emptyTenant);
-      if (grouped.rows.length > 0)
-        return `an empty tenant sees ${grouped.rows.length} ${key} groups`;
-    }
-    return;
-  });
+  for (const [name, tenant] of [
+    ["an empty tenant", emptyTenant],
+    ["an empty tenant list", []]
+  ]) {
+    await check(`tenant isolation: ${name}`, async () => {
+      const measures = Object.keys(probe.measures);
+      const leaked = [];
+      for (let start = 0;start < measures.length; start += MAX_MEASURES) {
+        const batch = measures.slice(start, start + MAX_MEASURES);
+        const result = await run({ measures: batch }, tenant);
+        leaked.push(...Object.entries(result.totals).filter(([, value]) => value !== 0 && value !== null));
+      }
+      if (leaked.length > 0) {
+        return `${name} sees ${leaked.map(([key, value]) => `${key}=${value}`).join(", ")}`;
+      }
+      for (const [key, entry] of dimensions) {
+        if (!entry.groupable)
+          continue;
+        const grouped = await run({ measures: [COUNT], groupBy: [key] }, tenant);
+        if (grouped.rows.length > 0)
+          return `${name} sees ${grouped.rows.length} ${key} groups`;
+      }
+      return;
+    });
+  }
   for (const time of Object.keys(dataset.time)) {
     await check(`day buckets of ${time} in ${timezone}`, async () => {
       const days = await run({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "measurr",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "A small typed semantic layer: datasets of measures and dimensions compiled to one SQL statement per dialect.",
 	"type": "module",
 	"module": "./dist/index.js",

package/src/analytics.ts

@@ -6,6 +6,7 @@ import {
 	type ParsedQuery,
 	type PlanContext,
 	type Tenant,
+	type TenantId,
 	allTenants,
 	normalizeQuery,
 	planLookup,
@@ -115,9 +116,10 @@ export type AnalyticsOptions<DS extends readonly AnyDataset[], Ctx> = {
 	/** Databases by name; a dataset's `source` picks one, or the only one is used. */
 	sources: Record<string, AnalyticsSource>
 	/**
-	 * The tenant every query is scoped to. Queries without one (null, undefined, '') are
-	 * refused. Return `allTenants` to drop the tenant filter, only for callers allowed to see
-	 * every tenant's rows.
+	 * The tenant every query is scoped to, or a list of them (an empty list matches no rows).
+	 * Queries without one (null, undefined, '', a list holding one of those) are refused.
+	 * Return `allTenants` to drop the tenant filter, only for callers allowed to see every
+	 * tenant's rows.
 	 */
 	tenant: (ctx: Ctx) => Tenant | null | undefined
 	/**
@@ -207,7 +209,8 @@ type Prepared = {
 	query: NormalizedQuery
 	tenant: Tenant
 	timezone: string
-	period: ResolvedPeriod
+	/** Null for all time. */
+	period: ResolvedPeriod | null
 	previous: ResolvedPeriod | null
 	now: Date
 }
@@ -326,16 +329,19 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 
 		const query = normalizeQuery(dataset, parsed.data as ParsedQuery)
 		const at = now()
-		let period: ResolvedPeriod
+		let period: ResolvedPeriod | null
 		try {
-			period = resolvePeriod(query.period, timezone, at)
+			period =
+				'all' in query.period ? null : resolvePeriod(query.period, timezone, at)
 		} catch (error) {
 			if (error instanceof PeriodError) {
 				throw new AnalyticsError('invalid_period', error.message)
 			}
 			throw error
 		}
-		const previous = query.compareToPrevious ? previousPeriod(period) : null
+		// The schema refuses compareToPrevious with an all-time period.
+		const previous =
+			query.compareToPrevious && period ? previousPeriod(period) : null
 
 		return { dataset, query, tenant, timezone, period, previous, now: at }
 	}
@@ -357,7 +363,7 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			dialect
 		)
 
-		const runPeriod = async (target: ResolvedPeriod) => {
+		const runPeriod = async (target: ResolvedPeriod | null) => {
 			const statements = periodStatements(dataset, query, {
 				tenant,
 				timezone,
@@ -373,27 +379,26 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 			const { rows, truncated } = shapeRows(dataset, query, rawRows, dialect)
 			const totalsRow = (rawTotals ?? rawRows)[0] ?? {}
 			const totals = shapeMeasures(dataset, query.measures, totalsRow, dialect)
-			const periodOut = { from: target.from, to: target.to, timezone }
 
-			return { period: periodOut, rows, totals, truncated }
+			return { rows, totals, truncated }
 		}
 
+		const range = ({ from, to }: ResolvedPeriod) => ({ from, to, timezone })
 		const [current, before] = await Promise.all([
 			runPeriod(period),
-			previous ? runPeriod(previous) : null
+			previous &&
+				runPeriod(previous).then(({ rows, totals }) => ({
+					period: range(previous),
+					rows,
+					totals
+				}))
 		])
 
 		return {
-			period: current.period,
+			period: period ? range(period) : { all: true, timezone },
 			rows: current.rows,
 			totals: current.totals,
-			...(before && {
-				previous: {
-					period: before.period,
-					rows: before.rows,
-					totals: before.totals
-				}
-			}),
+			...(before && { previous: before }),
 			notes: resultNotes(dataset, query),
 			truncated: current.truncated
 		}
@@ -487,12 +492,20 @@ export function createAnalytics<const DS extends readonly AnyDataset[], Ctx>(
 }
 
 /**
- * Fails closed: only a non-empty string, a finite number or `allTenants` scopes a query, even
- * when a JavaScript caller's hook returns something its type does not allow.
+ * Fails closed: only a non-empty string, a finite number, a list of those or `allTenants`
+ * scopes a query, even when a JavaScript caller's hook returns something its type does not
+ * allow.
  */
 function isTenant(value: unknown): value is Tenant {
 	return (
 		value === allTenants ||
+		isTenantId(value) ||
+		(Array.isArray(value) && value.every(isTenantId))
+	)
+}
+
+function isTenantId(value: unknown): value is TenantId {
+	return (
 		(typeof value === 'string' && value !== '') ||
 		(typeof value === 'number' && Number.isFinite(value))
 	)

package/src/dataset.ts

@@ -9,6 +9,7 @@ import {
 	directChildren,
 	rootOf
 } from './expr.js'
+import { DEFAULT_PERIOD, type PeriodInput } from './period.js'
 
 declare const ratioBrand: unique symbol
 
@@ -532,7 +533,8 @@ export type Dataset<
 	K extends string = string,
 	M extends Record<string, AnyMeasure> = Record<string, AnyMeasure>,
 	Dm extends Record<string, AnyDimension> = Record<string, AnyDimension>,
-	T extends string = string
+	T extends string = string,
+	P extends PeriodInput = PeriodInput
 > = {
 	readonly key: K
 	readonly label: string
@@ -543,6 +545,8 @@ export type Dataset<
 	readonly scope: ExprNode | null
 	readonly time: Readonly<Record<T, TimeField>>
 	readonly defaultTime: T
+	/** Kept as a type, so results know whether a query without a period covers all time. */
+	readonly defaultPeriod: P
 	readonly measures: M
 	readonly dimensions: Dm
 }
@@ -571,7 +575,8 @@ export type DatasetDefinition<
 	K extends string,
 	M extends Record<string, AnyMeasure>,
 	Dm extends Record<string, AnyDimension>,
-	T extends string
+	T extends string,
+	P extends PeriodInput
 > = {
 	key: K
 	label: string
@@ -587,6 +592,11 @@ export type DatasetDefinition<
 	time: Record<T, { column: Expr<'timestamp'>; label: string }>
 	/** The time field periods apply to when a query names none; the first one by default. */
 	defaultTime?: NoInfer<T> | undefined
+	/**
+	 * The period of a query that names none; the last 30 days by default. A dataset of current
+	 * state (units, organizations) sets `{ all: true }`.
+	 */
+	defaultPeriod?: P | undefined
 	measures: M & CheckMeasures<M>
 	dimensions: Dm & CheckDimensions<Dm, NoInfer<T>>
 }
@@ -599,8 +609,9 @@ export function defineDataset<
 	const K extends string,
 	const M extends Record<string, AnyMeasure>,
 	const Dm extends Record<string, AnyDimension>,
-	const T extends string
->(definition: DatasetDefinition<K, M, Dm, T>): Dataset<K, M, Dm, T> {
+	const T extends string,
+	const P extends PeriodInput = typeof DEFAULT_PERIOD
+>(definition: DatasetDefinition<K, M, Dm, T, P>): Dataset<K, M, Dm, T, P> {
 	const timeEntries = Object.entries<{
 		column: Expr<'timestamp'>
 		label: string
@@ -619,7 +630,7 @@ export function defineDataset<
 		])
 	) as Record<T, TimeField>
 
-	const dataset: Dataset<K, M, Dm, T> = {
+	const dataset: Dataset<K, M, Dm, T, P> = {
 		key: definition.key,
 		label: definition.label,
 		description: definition.description,
@@ -629,6 +640,8 @@ export function defineDataset<
 		scope: definition.scope?.node ?? null,
 		time,
 		defaultTime: definition.defaultTime ?? (firstTime[0] as T),
+		// P is DEFAULT_PERIOD's type when the definition names no period.
+		defaultPeriod: definition.defaultPeriod ?? (DEFAULT_PERIOD as P),
 		measures: definition.measures,
 		dimensions: definition.dimensions
 	}

package/src/guidance.ts

@@ -4,7 +4,7 @@
  */
 export const analyticsToolGuidance = `- Answer every "how many", "how much", "per week" or "split by" question with the analytics tool. Never count by hand from lists or pages.
 - Pick the dataset whose description matches the question, the fewest measures that answer it and at most two groupings.
-- Say which period and filters the numbers cover, using the dates in the result ("1-30 September").
+- Say which period and filters the numbers cover, using the dates in the result ("1-30 September", or "all time").
 - Compare with the previous period (compareToPrevious) when the change is the point, such as "is it going up".
 - When the result has notes (overlapping rows, such as a record counted once per tag), say so in a few words.
 - Ask one short question only when the period is genuinely ambiguous ("this season") and someone can answer; otherwise take the natural reading and state it.`

package/src/index.ts

@@ -65,11 +65,12 @@ export {
 } from './expr.js'
 export { analyticsToolGuidance } from './guidance.js'
 export type { PeriodInput, PeriodPreset } from './period.js'
-export { allTenants, type Tenant } from './plan.js'
+export { allTenants, type Tenant, type TenantId } from './plan.js'
 export {
 	AnalyticsResultSchema,
 	type DatasetFilter,
 	type DatasetQuery,
 	type QueryResult,
-	type ResultOf
+	type ResultOf,
+	type ResultPeriod
 } from './query.js'

package/src/period.ts

@@ -13,11 +13,15 @@ export type PeriodPreset =
 	| 'lastMonth'
 	| 'thisYear'
 
-export type PeriodInput =
+/** A range of days: what `resolvePeriod` turns into instants. */
+export type PeriodRange =
 	| { last: { days: number } }
 	| { from: string; to: string }
 	| { preset: PeriodPreset }
 
+/** A range of days, or `{ all: true }` for no time filter. */
+export type PeriodInput = PeriodRange | { all: true }
+
 export type ResolvedPeriod = {
 	/** First local day, `YYYY-MM-DD`. */
 	from: string
@@ -32,7 +36,9 @@ export type ResolvedPeriod = {
 }
 
 export const MAX_PERIOD_DAYS = 731
-export const DEFAULT_PERIOD: PeriodInput = { last: { days: 30 } }
+export const DEFAULT_PERIOD = {
+	last: { days: 30 }
+} as const satisfies PeriodInput
 
 const DAY_MS = 86_400_000
 
@@ -140,7 +146,7 @@ export class PeriodError extends Error {
 
 /** Resolves a period input to local days and instants in `timezone`. */
 export function resolvePeriod(
-	input: PeriodInput,
+	input: PeriodRange,
 	timezone: string,
 	now: Date
 ): ResolvedPeriod {
@@ -154,7 +160,7 @@ export function resolvePeriod(
 	return periodFromDays(from, to, timezone)
 }
 
-function periodDays(input: PeriodInput, today: string): [string, string] {
+function periodDays(input: PeriodRange, today: string): [string, string] {
 	if ('last' in input) return [addDays(today, -(input.last.days - 1)), today]
 	if ('from' in input) return [input.from, input.to]
 

package/src/plan.ts

@@ -6,11 +6,7 @@ import type {
 } from './compile.js'
 import type { AnyDataset, AnyDimension, AnyMeasure } from './dataset.js'
 import type { ExprNode, ParamValue } from './expr.js'
-import {
-	DEFAULT_PERIOD,
-	type PeriodInput,
-	type ResolvedPeriod
-} from './period.js'
+import type { PeriodInput, ResolvedPeriod } from './period.js'
 import { DEFAULT_LIMIT } from './query.js'
 
 /** A parsed query with every default filled in and duplicates removed. */
@@ -65,7 +61,7 @@ export function normalizeQuery(
 		// Order matters: the first grouped dimension leads the rows.
 		groupBy: [...new Set(parsed.groupBy ?? [])],
 		filters,
-		period: parsed.period ?? DEFAULT_PERIOD,
+		period: parsed.period ?? dataset.defaultPeriod,
 		time: parsed.time ?? dataset.defaultTime,
 		compareToPrevious: parsed.compareToPrevious ?? false,
 		sort: parsed.sort
@@ -81,14 +77,17 @@ export function normalizeQuery(
  */
 export const allTenants: unique symbol = Symbol('measurr.allTenants')
 
-/** One tenant's id, or `allTenants`. */
-export type Tenant = string | number | typeof allTenants
+export type TenantId = string | number
+
+/** One tenant's id, a list of them (an empty list matches no rows), or `allTenants`. */
+export type Tenant = TenantId | readonly TenantId[] | typeof allTenants
 
 /** What the planner needs besides the query: values from the hooks and resolved labels. */
 export type PlanContext = {
 	tenant: Tenant
 	timezone: string
-	period: ResolvedPeriod
+	/** Null for an all-time period: no time filter. */
+	period: ResolvedPeriod | null
 	/** The moment the query runs. */
 	now: Date
 	/** Keys for filters on open dimensions, after label resolution, by dimension. */
@@ -215,17 +214,27 @@ function baseWhere(
 	tenant: Tenant,
 	period: { time: string; start: Date; end: Date } | null
 ): ExprNode[] {
-	const where: ExprNode[] =
-		tenant === allTenants
-			? []
-			: [
-					{
+	const where: ExprNode[] = []
+	if (tenant !== allTenants) {
+		const ids = typeof tenant === 'object' ? [...new Set(tenant)] : [tenant]
+		const [only] = ids
+		// One id compiles exactly like the scalar; an empty list renders as a false condition.
+		where.push(
+			ids.length === 1 && only !== undefined
+				? {
 						kind: 'compare',
 						op: '=',
 						left: dataset.tenantColumn,
-						right: param(tenant)
+						right: param(only)
+					}
+				: {
+						kind: 'in',
+						item: dataset.tenantColumn,
+						values: ids.map(param),
+						negated: false
 					}
-				]
+		)
+	}
 	if (dataset.scope) where.push(dataset.scope)
 
 	if (period) {
@@ -357,11 +366,15 @@ export function planQuery(
 	}
 
 	const where = [
-		...baseWhere(dataset, context.tenant, {
-			time: query.time,
-			start: context.period.start,
-			end: context.period.end
-		}),
+		...baseWhere(
+			dataset,
+			context.tenant,
+			context.period && {
+				time: query.time,
+				start: context.period.start,
+				end: context.period.end
+			}
+		),
 		...query.filters.map((filter) => filterNode(dataset, filter, context))
 	]
 

package/src/query.ts

@@ -109,10 +109,31 @@ export type ResultTotals<M, MeasureKey extends string> = Simplify<{
 	[Key in MeasureKey & keyof M]: MeasureValue<M[Key]>
 }>
 
-export type QueryResult<Row, Totals> = {
-	period: { from: string; to: string; timezone: string }
+/** The days a result covers: local days `from` to `to` (inclusive), or all time. */
+export type ResultPeriod =
+	| { from: string; to: string; timezone: string }
+	| { all: true; timezone: string }
+
+/** The period query `Q` names; null or none means the dataset's `Default`. */
+type QueryPeriod<Q, Default> = Q extends unknown
+	? 'period' extends keyof Q
+		? OrDefault<Q['period' & keyof Q], Default>
+		: Default
+	: never
+type OrDefault<P, Default> = P extends null | undefined ? Default : P
+type PeriodShape<P> = P extends { all: true }
+	? Extract<ResultPeriod, { all: true }>
+	: Exclude<ResultPeriod, { all: true }>
+
+export type QueryResult<
+	Row,
+	Totals,
+	Period extends ResultPeriod = ResultPeriod
+> = {
+	period: Period
 	rows: Row[]
 	totals: Totals
+	/** Only for a range: an all-time period has no previous period. */
 	previous?: {
 		period: { from: string; to: string; timezone: string }
 		rows: Row[]
@@ -124,9 +145,13 @@ export type QueryResult<Row, Totals> = {
 
 /** The typed result of query `Q` against the datasets `DS`. */
 export type ResultOf<DS, Q> =
-	DS extends Dataset<infer K, infer M, infer Dm, string>
+	DS extends Dataset<infer K, infer M, infer Dm, string, infer P>
 		? Q extends { dataset: K; measures: readonly (infer Mk extends string)[] }
-			? QueryResult<ResultRow<M, Dm, Mk, GroupKeys<Q>>, ResultTotals<M, Mk>>
+			? QueryResult<
+					ResultRow<M, Dm, Mk, GroupKeys<Q>>,
+					ResultTotals<M, Mk>,
+					PeriodShape<QueryPeriod<Q, P>>
+				>
 			: never
 		: never
 
@@ -135,24 +160,29 @@ export type ResultOf<DS, Q> =
 
 const isoDate = z.iso.date().describe('A date, YYYY-MM-DD.')
 
-export const periodSchema = z
-	.union([
-		z.object({
-			last: z.object({
-				days: z
-					.number()
-					.int()
-					.min(1)
-					.max(MAX_PERIOD_DAYS)
-					.describe('Number of days, ending today.')
-			})
-		}),
-		z.object({ from: isoDate, to: isoDate.describe('Last day, inclusive.') }),
-		z.object({ preset: z.enum(PERIOD_PRESETS) })
-	])
-	.describe(
-		'Which days to count, in the organization timezone. Defaults to the last 30 days. At most two years.'
-	)
+const periodSchema = z.union([
+	z.object({
+		last: z.object({
+			days: z
+				.number()
+				.int()
+				.min(1)
+				.max(MAX_PERIOD_DAYS)
+				.describe('Number of days, ending today.')
+		})
+	}),
+	z.object({ from: isoDate, to: isoDate.describe('Last day, inclusive.') }),
+	z.object({ preset: z.enum(PERIOD_PRESETS) }),
+	z.object({ all: z.literal(true) }).describe('Every row, with no time filter.')
+])
+
+/** How the schema names a dataset's default period, so a model knows what omitting it means. */
+function describePeriod(period: PeriodInput): string {
+	if ('all' in period) return 'all time (no time filter)'
+	if ('last' in period) return `the last ${period.last.days} days`
+	if ('from' in period) return `${period.from} to ${period.to}`
+	return period.preset
+}
 
 function describeList(
 	entries: [string, { label: string; description?: string | undefined }][]
@@ -285,7 +315,11 @@ export function datasetQuerySchema(dataset: AnyDataset) {
 					.describe('Every filter must match.')
 			}),
 			// Nullable as well: LLM tool callers send null for a field they leave out.
-			period: periodSchema.nullish(),
+			period: periodSchema
+				.describe(
+					`Which days to count, in the organization timezone. Defaults to ${describePeriod(dataset.defaultPeriod)}. A range covers at most two years.`
+				)
+				.nullish(),
 			...(timeKeys && {
 				time: z
 					.enum(timeKeys)
@@ -297,7 +331,9 @@ export function datasetQuerySchema(dataset: AnyDataset) {
 			compareToPrevious: z
 				.boolean()
 				.optional()
-				.describe('Also return the previous period of the same length.'),
+				.describe(
+					'Also return the previous period of the same length. Not for all-time periods.'
+				),
 			sort: z
 				.object({
 					by: z.enum(sortKeys),
@@ -328,6 +364,15 @@ export function datasetQuerySchema(dataset: AnyDataset) {
 					message: `Sort by one of the asked measures or grouped dimensions: ${returned.join(', ')}`
 				})
 			}
+
+			const period = query.period ?? dataset.defaultPeriod
+			if (query.compareToPrevious && 'all' in period) {
+				context.addIssue({
+					code: 'custom',
+					path: ['compareToPrevious'],
+					message: 'An all-time period has no previous period to compare with'
+				})
+			}
 		})
 }
 
@@ -339,11 +384,15 @@ export function buildQuerySchema(datasets: readonly AnyDataset[]) {
 	return z.discriminatedUnion('dataset', [first, ...rest])
 }
 
-const periodOutput = z.object({
+const rangeOutput = z.object({
 	from: z.string(),
 	to: z.string(),
 	timezone: z.string()
 })
+const periodOutput = z.union([
+	rangeOutput,
+	z.object({ all: z.literal(true), timezone: z.string() })
+])
 const measureValue = z.number().nullable()
 const dimensionValue = z.object({
 	key: z.union([z.string(), z.number()]).nullable(),
@@ -360,7 +409,7 @@ function resultSchemaOf<Row extends z.ZodType, Totals extends z.ZodType>(
 		rows: z.array(row),
 		totals,
 		previous: z
-			.object({ period: periodOutput, rows: z.array(row), totals })
+			.object({ period: rangeOutput, rows: z.array(row), totals })
 			.optional(),
 		notes: z.array(z.string()),
 		truncated: z.boolean()

package/src/testing.ts

@@ -11,6 +11,7 @@ import {
 	measure
 } from './dataset.js'
 import type { PeriodInput } from './period.js'
+import type { TenantId } from './plan.js'
 import { MAX_MEASURES } from './query.js'
 
 export type ContractCheck = {
@@ -78,14 +79,14 @@ export async function checkDatasetContract(
 	const analytics = createAnalytics({
 		datasets: [probe],
 		sources: { main: options.source },
-		tenant: (ctx: { tenant: string | number }) => ctx.tenant,
+		tenant: (ctx: { tenant: TenantId | readonly TenantId[] }) => ctx.tenant,
 		timezone: () => timezone,
 		...(options.now && { now: options.now })
 	})
 
 	const run = async (
 		query: Record<string, unknown>,
-		tenant: string | number = options.tenant
+		tenant: TenantId | readonly TenantId[] = options.tenant
 	): Promise<ProbeResult> => {
 		const input = { dataset: dataset.key, period, limit: 100, ...query }
 		return (await analytics.query(input as never, {
@@ -204,33 +205,36 @@ export async function checkDatasetContract(
 		}
 	}
 
-	await check('tenant isolation', async () => {
-		const measures = Object.keys(probe.measures)
-		const leaked: [string, number | null][] = []
-		for (let start = 0; start < measures.length; start += MAX_MEASURES) {
-			const batch = measures.slice(start, start + MAX_MEASURES)
-			const other = await run({ measures: batch }, emptyTenant)
-			leaked.push(
-				...Object.entries(other.totals).filter(
-					([, value]) => value !== 0 && value !== null
+	// An empty tenant list is a scope that matches nothing, never a missing filter.
+	for (const [name, tenant] of [
+		['an empty tenant', emptyTenant],
+		['an empty tenant list', []]
+	] as const) {
+		await check(`tenant isolation: ${name}`, async () => {
+			const measures = Object.keys(probe.measures)
+			const leaked: [string, number | null][] = []
+			for (let start = 0; start < measures.length; start += MAX_MEASURES) {
+				const batch = measures.slice(start, start + MAX_MEASURES)
+				const result = await run({ measures: batch }, tenant)
+				leaked.push(
+					...Object.entries(result.totals).filter(
+						([, value]) => value !== 0 && value !== null
+					)
 				)
-			)
-		}
-		if (leaked.length > 0) {
-			return `an empty tenant sees ${leaked.map(([key, value]) => `${key}=${value}`).join(', ')}`
-		}
+			}
+			if (leaked.length > 0) {
+				return `${name} sees ${leaked.map(([key, value]) => `${key}=${value}`).join(', ')}`
+			}
 
-		for (const [key, entry] of dimensions) {
-			if (!entry.groupable) continue
-			const grouped = await run(
-				{ measures: [COUNT], groupBy: [key] },
-				emptyTenant
-			)
-			if (grouped.rows.length > 0)
-				return `an empty tenant sees ${grouped.rows.length} ${key} groups`
-		}
-		return undefined
-	})
+			for (const [key, entry] of dimensions) {
+				if (!entry.groupable) continue
+				const grouped = await run({ measures: [COUNT], groupBy: [key] }, tenant)
+				if (grouped.rows.length > 0)
+					return `${name} sees ${grouped.rows.length} ${key} groups`
+			}
+			return undefined
+		})
+	}
 
 	for (const time of Object.keys(dataset.time)) {
 		await check(`day buckets of ${time} in ${timezone}`, async () => {