@segmentstream-cloud/app 0.13.2 → 0.14.0

package/README.md

@@ -446,17 +446,17 @@ reach. Look at or change records through `find` and actions; count, sum or compa
 
 ```ts
 const { fields, rows, execution } = await segmentstream.ontology.aggregate({
-  measures: ["trendtoysSales.revenue", "trendtoysStock.onHand"],
-  dimensions: ["trendtoysProduct.assortmentStatus"],
+  measures: ["acmeSales.revenue", "acmeStock.onHand"],
+  dimensions: ["acmeProduct.assortmentStatus"],
   filters: [
     {
-      dimension: "trendtoysSales.orderDate",
+      dimension: "acmeSales.orderDate",
       operator: "between",
       values: ["2026-09-01", "2026-09-30"],
     },
-    { dimension: "trendtoysSales.currency", operator: "equals", value: "RUB" },
+    { dimension: "acmeSales.currency", operator: "equals", value: "RUB" },
   ],
-  orderBy: [{ measure: "trendtoysSales.revenue", direction: "desc" }],
+  orderBy: [{ measure: "acmeSales.revenue", direction: "desc" }],
 });
 ```
 
@@ -465,8 +465,8 @@ const { fields, rows, execution } = await segmentstream.ontology.aggregate({
   `sales_2025.revenue`. This differs from the per-entity call and records, which drop it. Fields
   and rows are keyed by these names.
 - When an entity reaches a property's entity in more than one way, write a route from it:
-  `trendtoysSales.returnedProduct.brand`. Its column is still keyed by the property's own name,
-  `trendtoysProduct.brand`.
+  `acmeSales.returnedProduct.brand`. Its column is still keyed by the property's own name,
+  `acmeProduct.brand`.
 - It posts to the ontology service's `/api/ontology/aggregate` as the signed-in user, who needs
   read permission on every entity the request reaches. Previews and local development answer
   `aggregate_unavailable`.
@@ -486,13 +486,13 @@ Since 0.13.0, both aggregates take more conditions, buckets and a timezone:
 
 ```ts
 const { rows, execution } = await segmentstream.ontology.aggregate({
-  measures: ["trendtoysSales.wonOrders"],
-  dimensions: ["trendtoysSales.orderDate"],
+  measures: ["acmeSales.wonOrders"],
+  dimensions: ["acmeSales.orderDate"],
   granularity: "week",
-  granularityOf: "trendtoysSales.orderDate",
+  granularityOf: "acmeSales.orderDate",
   filters: [
-    { dimension: "trendtoysSales.orderDate", operator: "inPeriod", value: "last 4 weeks" },
-    { dimension: "trendtoysProduct.brand", operator: "notIn", values: ["Unknown", "Test"] },
+    { dimension: "acmeSales.orderDate", operator: "inPeriod", value: "last 4 weeks" },
+    { dimension: "acmeProduct.brand", operator: "notIn", values: ["Unknown", "Test"] },
   ],
   timezone: "Europe/Moscow",
 });
@@ -519,6 +519,40 @@ const { rows, execution } = await segmentstream.ontology.aggregate({
   `@segmentstream-cloud/ontology` 0.17.0 or later, whose service accepts them; earlier
   versions refuse them. See [Upgrading to 0.13](#upgrading-to-013).
 
+Since 0.14.0, the model-level call also takes the measures of the model, which the ontology
+declares in `defineOntology({ measures })` over measures of several entities, by their bare
+names beside `entity.measure` names:
+
+```ts
+const { fields, rows } = await segmentstream.ontology.aggregate({
+  measures: ["planAttainment", "acmeSales.ordered"],
+  dimensions: ["acmeSales.orderDate"],
+  granularity: "month",
+  granularityOf: "acmeSales.orderDate",
+  filters: [
+    { dimension: "acmeSales.orderDate", operator: "inPeriod", value: "this year to date" },
+  ],
+  orderBy: [{ measure: "planAttainment", direction: "desc" }],
+});
+// fields[1]: { name: "planAttainment", label: "Plan attainment", unit: "ratio", additive: false,
+//   filters: [...], inputs: ["acmeSales.ordered", "acmePlans.plannedUnits"] }
+```
+
+- A measure of the model is requested by the camelCase name the ontology declares, typed from
+  `typeof ontology`. The platform names it in snake_case, `plan_attainment`; its field and row
+  key are the camelCase form, `planAttainment`, as for entity measures.
+- Its field carries `inputs`, the entity measures it reads, as `entity.measure` in camelCase per
+  segment, like other names. They are computed whether or not you request them; request one to
+  get its column too.
+- Its `filters` lists the filters that applied to every input. A filter on a property the
+  measure aligns applies to each entity through its own property; a filter that reaches some of
+  its entities and not others is refused with `invalid_aggregate_query`.
+- A group one of its entities has no rows for, or a zero denominator, gives `null`.
+- The caller needs read permission on every entity it reads.
+- These requests need the workspace's ontology deployed with `@segmentstream-cloud/ontology`
+  0.23.0 or later, which declares and serves measures of the model; earlier versions refuse
+  them. Requests that name none work as before, and their fields carry no `inputs`.
+
 ## How requests are handled
 
 - Page navigations without a session are redirected to `/sign-in?returnTo=<path>` and
@@ -629,3 +663,10 @@ Replace segmentstream.semantic with typed warehouse-backed entity aggregates. Se
 - The new operators, `inPeriod`, granularities and `timezone` need the workspace's ontology
   deployed with `@segmentstream-cloud/ontology` 0.17.0 or later. Requests that use none of
   them work as before.
+
+## Upgrading to 0.14
+
+- `segmentstream.ontology.aggregate()` accepts the measures of the model by their bare names, typed
+  from an ontology that declares them with `defineOntology({ measures })`. Ontologies without them
+  type the same names as before.
+- `AggregateField` gains `inputs`, which only fields of measures of the model carry.

package/dist/data.d.ts

@@ -115,7 +115,8 @@ export type ModelAggregateFilter<Dimension extends string = string> = {
     readonly values?: undefined;
 };
 /**
- * A model-level aggregate: measures of one or more entities, as `entity.measure`, grouped by
+ * A model-level aggregate: measures of one or more entities, as `entity.measure`, and measures of
+ * the model, declared in `defineOntology({ measures })`, by their bare names, grouped by
  * `entity.property` dimensions. A dimension may instead be a route from a measure's entity,
  * `entity.relationship.property`, which picks the way that entity reaches the property. Date bounds
  * are `between` or `inPeriod` filters.
@@ -156,6 +157,12 @@ export interface AggregateField {
      * rows snapshot. The request groups by it or filters it to one day.
      */
     readonly balanceOver?: string;
+    /**
+     * On a measure of the model: the entity measures it reads, as `entity.measure`, in declaration
+     * order. They are computed whether or not the request names them, and come back as columns only
+     * when it does. Its `filters` are the filters that applied to every one of them.
+     */
+    readonly inputs?: readonly string[];
 }
 export interface AggregateResult<Row = Record<string, string | boolean | null>> {
     readonly deploymentId: string | null;

package/dist/ontology.d.ts

@@ -252,7 +252,16 @@ type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
  */
 type CamelCase<S extends string> = S extends `${infer Head}_${infer Tail}` ? Tail extends `${Digit}${string}` ? `${Head}_${CamelCase<Tail>}` : `${Head}${Capitalize<CamelCase<Tail>>}` : S;
 /** `entity.measure` for every measure of every entity, warehouse-backed or stored. */
-type ModelMeasuresOf<E> = E extends unknown ? `${CamelCase<NameOf<E>>}.${MeasuresOf<E>}` : never;
+type EntityMeasuresOf<E> = E extends unknown ? `${CamelCase<NameOf<E>>}.${MeasuresOf<E>}` : never;
+/**
+ * The measures of the model, `defineOntology({ measures })`, by their bare declared names. An
+ * ontology SDK without them, or a definition typed as any record of measures, names none.
+ */
+type ModelMeasuresOf<O> = O extends {
+    readonly config: {
+        readonly measures?: infer M;
+    };
+} ? DeclaredNames<NonNullable<M>> : never;
 /** A route picks how an entity with measures reaches a property, so only such entities start one. */
 type RoutesOf<E, O> = [MeasuresOf<E>] extends [never] ? never : PathsOf<E, O>;
 /**
@@ -275,7 +284,7 @@ type TypedOntologyClient<O> = {
     readonly [N in NameOf<EntitiesOf<O>>]: ClientOf<Extract<EntitiesOf<O>, {
         readonly name: N;
     }>, O>;
-} & ModelAggregateClient<ModelMeasuresOf<EntitiesOf<O>>, ModelDimensionsOf<EntitiesOf<O>, O>>;
+} & ModelAggregateClient<EntityMeasuresOf<EntitiesOf<O>> | ModelMeasuresOf<O>, ModelDimensionsOf<EntitiesOf<O>, O>>;
 /** A client for any entity, when the app passes no ontology type. */
 export type UntypedOntologyClient = ModelAggregateClient & {
     readonly [entity: string]: EntityClient<JsonRecord, {

package/dist/ontology.js

@@ -247,8 +247,8 @@ function aggregateToWire(request) {
     };
 }
 /**
- * Field names, the filters each measure applied, a balance's dimension and row keys come back
- * camelCase per segment; `execution` is passed on as sent.
+ * Field names, the filters each measure applied, a balance's dimension, a model measure's inputs
+ * and row keys come back camelCase per segment; `execution` is passed on as sent.
  */
 function aggregateResultFromWire(result, decodeName) {
     return {
@@ -258,6 +258,7 @@ function aggregateResultFromWire(result, decodeName) {
             name: decodeName(field.name),
             ...(field.filters === undefined ? {} : { filters: field.filters.map(decodeName) }),
             ...(field.balanceOver === undefined ? {} : { balanceOver: decodeName(field.balanceOver) }),
+            ...(field.inputs === undefined ? {} : { inputs: field.inputs.map(decodeName) }),
         })),
         rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).map(([name, value]) => [decodeName(name), value]))),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",