@lotics/app-sdk 0.102.2 → 0.102.3

package/dist/index.js

@@ -23826,6 +23826,9 @@ var queryAggregateColumnSchema = zod_default.object({
   input_column: zod_default.string().optional().describe(
     "Input column to aggregate. Required for non-count operations; ignored for count."
   ),
+  filter: tableRecordFiltersSchema.optional().describe(
+    "Aggregates only the input rows that match (SQL `FILTER`). Conditions name input columns and take `{{params.x}}`; aggregates with different filters in one node read the input once."
+  ),
   separator: zod_default.string().max(8).optional().describe('string_agg only. Joins the values. Defaults to ", ".'),
   distinct: zod_default.boolean().optional().describe(
     "string_agg only. Collapses repeats \u2014 a group of containers sized 40HC/40HC/20DC aggregates to '20DC, 40HC'. Defaults to true, which is almost always what a summary column wants."

package/docs/mutations.md

@@ -531,8 +531,9 @@ every read before the request answers:
 - **Totals.** A `total`, a count per value (`total: { by }`), a group asked with `aggregate` or
   declared by the query, and a parent's count or sum rollup move by exactly what the written row adds
   or takes away; a group the last row leaves is gone, and a count per value gains the value a row
-  first holds. A mean, an extreme, a distinct count, a group by day, a group none of the read's rows
-  counted in yet, a read whose rows a search or a cap decides, or a row the app never read is left
+  first holds. A mean, an extreme, a distinct count, a group by day, an aggregate with its own
+  `filter`, a group none of the read's rows counted in yet, a read whose rows a search or a cap
+  decides, or a row the app never read is left
   as the server said it until a read asked after the write answers.
 - **A refusal takes it back**, and `result` says why, as always. A success keeps it until a read
   asked after the write settled answers — the stored value then replaces the prediction, whatever

package/docs/queries.md

@@ -277,7 +277,7 @@ came from.
 
 Full semantics in §8. `by` may be empty (a single-row aggregate); `aggregates` needs ≥ 1 entry.
 Aggregate operation × input-column type is validated at bind. Grouping collapses rows —
-addressing is dropped.
+addressing is dropped. An aggregate's `filter` limits it to the rows that match (§8).
 
 ### `window` — aggregate without collapsing
 
@@ -679,6 +679,25 @@ everything else requires an `input_column` whose type must be compatible — che
 ¹ opaque `json` columns support only the presence-counting six (`empty`/`filled`/`unique` and
 their `percent_*` forms).
 
+**`filter` — aggregate a subset.** Any aggregate, in `group` or `window`, takes a `filter` over its
+input columns — the same tree as a `filter` node, `{{params.x}}` included, with a condition on an
+omitted optional param dropped. The aggregate reads only the rows it matches (SQL `FILTER`), and
+the rest of the node is unaffected, so several figures over one table cost one read of it:
+
+```jsonc
+{ "kind": "group", "from": { "kind": "from_table", "table_id": "…" }, "by": [],
+  "aggregates": [
+    { "output": "open", "type": "number", "operation": "count",
+      "filter": { "node_type": "condition", "field_key": "closed_at", "operator": "is_empty" } },
+    { "output": "closed_today", "type": "number", "operation": "count",
+      "filter": { "node_type": "condition", "field_key": "closed_at", "operator": "on",
+                  "value": { "type": "period", "period": "day", "boundary": "start", "offset": 0 } } } ] }
+```
+
+A relative date resolves in its field's timezone while the column still names one field — over a
+`from_table`, or a `project` of one. Over a `union` of different tables it names none; count per
+table, then combine.
+
 **`string_agg` — a summary column, not a dataset.** Every other operation counts or reduces to a
 number; this one joins the values, so a child set answers "which ones?" in the parent row (the
 sizes on a shipment, the tags on a ticket) without a second query.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.102.2",
+  "version": "0.102.3",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {