@effect-app/infra 4.0.0-beta.229 → 4.0.0-beta.230

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-app/infra",
-  "version": "4.0.0-beta.229",
+  "version": "4.0.0-beta.230",
   "license": "MIT",
   "type": "module",
   "dependencies": {
@@ -13,7 +13,7 @@
     "proper-lockfile": "^4.1.2",
     "pure-rand": "8.4.0",
     "query-string": "^9.3.1",
-    "effect-app": "4.0.0-beta.229"
+    "effect-app": "4.0.0-beta.230"
   },
   "devDependencies": {
     "@azure/cosmos": "^4.9.3",

package/src/Model/Repository/internal/internal.ts

@@ -333,10 +333,28 @@ export function makeRepoInternal<
           } = (<A, R, EncodedRefined extends Encoded = Encoded>(q: Q.QAll<Encoded, EncodedRefined, A, R>) => {
             const a = Q.toFilter(q, schema)
             // Mode dispatch — see `Q.project` JSDoc for the contract:
+            //   aggregate: GROUP BY + aggregate functions at DB level; decode raw rows with schema; SchemaError surfaces.
             //   project  : decode raw encoded rows with schema; no PM reverse-mapping; SchemaError surfaces.
             //   collect  : same as project, but schema yields Option and None rows are dropped.
             //   transform: PM reverse-map (re-inject _etag/PM state from cms cache) then decode; orDie.
-            const eff = a.mode === "project"
+            const eff = a.mode === "aggregate"
+              ? store
+                // `a.select` contains `{ key, aggregate }` items not expressible in FilterFunc<Encoded, U>'s
+                // `U extends keyof Encoded` generic. Cast is unavoidable until FilterFunc supports aggregate mode.
+                .filter(a as any)
+                // Decode raw aggregate rows directly — no PM reverse-mapping, no id/_etag needed.
+                .pipe(
+                  Effect.andThen(
+                    flow(
+                      S.decodeEffectConcurrently(S.Array(a.schema ?? schema)),
+                      provideRctx,
+                      Effect.withSpan("parseMany", {
+                        attributes: { "app.entity": name, "app.query.mode": "aggregate" }
+                      })
+                    )
+                  )
+                )
+              : a.mode === "project"
               ? filter(a)
                 // TODO: mapFrom but need to support per field and dependencies
                 .pipe(

package/src/Model/query/dsl.ts

@@ -184,6 +184,37 @@ export type ComputedProjectionExpression =
     readonly path: string
   }
 
+/**
+ * An expression that aggregates values across documents (for use with {@link aggregate}).
+ * `agg-field` references a document field to group by; other tags are aggregate functions.
+ */
+export type AggregateExpression =
+  | {
+    readonly _tag: "agg-field"
+    readonly path: string
+  }
+  | {
+    readonly _tag: "agg-count"
+  }
+  | {
+    readonly _tag: "agg-count-when"
+    readonly operation: ComputedProjectionOperation
+  }
+  | {
+    readonly _tag: "agg-sum"
+    readonly field: string
+  }
+  | {
+    readonly _tag: "agg-min"
+    readonly field: string
+  }
+  | {
+    readonly _tag: "agg-max"
+    readonly field: string
+  }
+
+export type AggregateMap = Readonly<Record<string, AggregateExpression>>
+
 export type ComputedProjectionMap = Readonly<Record<string, ComputedProjectionExpression>>
 export type Q<TFieldValues extends FieldValues> =
   | Initial<TFieldValues>
@@ -298,8 +329,9 @@ export class Project<A, TFieldValues extends FieldValues, R, TType extends "one"
   extends Data.TaggedClass("project")<{
     current: Query<TFieldValues> | QueryWhere<any, TFieldValues> | QueryEnd<TFieldValues, TType>
     schema: S.Codec<A, TFieldValues, R>
-    mode: "collect" | "project" | "transform"
+    mode: "collect" | "project" | "transform" | "aggregate"
     computed?: ComputedProjectionMap
+    aggregateMap?: AggregateMap
   }>
   implements QueryProjection<TFieldValues, A, R>
 {
@@ -698,6 +730,68 @@ export const projectComputed: {
 } = (schema: any, computedProjection: ComputedProjectionMap, mode = "project") => (current: any) =>
   new Project({ current, schema, mode, computed: computedProjection } as any)
 
+/**
+ * DSL helpers for building aggregate expressions used with {@link aggregate}.
+ *
+ * - `agg.field(path)` — references a document field for GROUP BY (with optional output alias)
+ * - `agg.count()` — COUNT(*) across all rows in the group
+ * - `agg.countWhen(op)` — COUNT of rows matching the filter operation
+ * - `agg.sum(field)` — SUM of a numeric document field
+ * - `agg.min(field)` / `agg.max(field)` — MIN/MAX of a document field
+ */
+export const agg = {
+  field: (path: string): AggregateExpression => ({ _tag: "agg-field", path }),
+  count: (): AggregateExpression => ({ _tag: "agg-count" }),
+  countWhen: (operation: ComputedProjectionOperation): AggregateExpression => ({
+    _tag: "agg-count-when",
+    operation
+  }),
+  sum: (field: string): AggregateExpression => ({ _tag: "agg-sum", field }),
+  min: (field: string): AggregateExpression => ({ _tag: "agg-min", field }),
+  max: (field: string): AggregateExpression => ({ _tag: "agg-max", field })
+} as const
+
+/**
+ * Attach an aggregate projection to a query, performing GROUP BY + aggregate functions at the
+ * database level instead of fetching all rows and grouping in memory.
+ *
+ * The `aggregateMap` maps each output field name to either:
+ * - `agg.field(path)` — a group-by field (document path → output alias)
+ * - `agg.count()` / `agg.countWhen(op)` / `agg.sum(f)` / `agg.min(f)` / `agg.max(f)` — an aggregate
+ *
+ * The output is decoded directly with `schema` (no PM reverse-mapping, no etag tracking).
+ * Decode failures surface as `S.SchemaError`.
+ *
+ * @example
+ * ```ts
+ * repo.query(
+ *   where("status", "active"),
+ *   aggregate(
+ *     S.Struct({ city: S.String, count: S.Number }),
+ *     {
+ *       city: agg.field("address.city"),
+ *       count: agg.countWhen((q) => q.pipe(where("active", true)))
+ *     }
+ *   )
+ * )
+ * ```
+ */
+export const aggregate: {
+  <
+    Q extends Query<any> | QueryWhere<any, any, any> | QueryEnd<any, "one" | "many", any>,
+    I extends Record<string, unknown>,
+    A = ExtractFieldValuesRefined<Q>,
+    R = never,
+    E extends boolean = ExtractExclusiveness<Q>
+  >(
+    schema: S.Codec<A, I, R>,
+    aggregateMap: AggregateMap
+  ): (
+    current: Q
+  ) => QueryProjection<ExtractFieldValuesRefined<Q>, A, R, ExtractTType<Q>, E>
+} = (schema: any, aggregateMap: AggregateMap) => (current: any) =>
+  new Project({ current, schema, mode: "aggregate", aggregateMap } as any)
+
 type GetArV<T> = T extends readonly (infer R)[] ? R : never
 
 export type FilterContinuations<IsCurrentInitial extends boolean = false> = {

package/src/Model/query/new-kid-interpreter.ts

@@ -13,6 +13,17 @@ import type { FieldValues } from "../filter/types.js"
 import type { FieldPath } from "../filter/types/path/eager.js"
 import { make, type Q, type QAll } from "../query/dsl.js"
 
+export type AggregateIrExpression =
+  | { readonly _tag: "agg-count" }
+  | { readonly _tag: "agg-count-when"; readonly filter: readonly FilterResult[] }
+  | { readonly _tag: "agg-sum"; readonly field: string }
+  | { readonly _tag: "agg-min"; readonly field: string }
+  | { readonly _tag: "agg-max"; readonly field: string }
+
+export type AggregateIrItem =
+  | AggregateIrExpression
+  | { readonly _tag: "agg-field"; readonly path: string }
+
 export type ComputedProjectionMathIrExpression =
   | {
     readonly _tag: "field"
@@ -100,8 +111,9 @@ type Result<TFieldValues extends FieldValues, A = TFieldValues, R = never> = {
   skip: number | undefined
   order: { key: FieldPath<TFieldValues>; direction: "ASC" | "DESC" }[]
   ttype: "one" | "many" | "count" | undefined
-  mode: "collect" | "project" | "transform" | undefined
+  mode: "collect" | "project" | "transform" | "aggregate" | undefined
   computed: Record<string, ComputedProjectionIrExpression> | undefined
+  aggregateMap: Record<string, AggregateIrItem> | undefined
 }
 
 const interpret = <
@@ -120,7 +132,8 @@ const interpret = <
     order: [],
     ttype: undefined,
     mode: undefined,
-    computed: undefined
+    computed: undefined,
+    aggregateMap: undefined
   }
 
   const upd = (
@@ -134,6 +147,7 @@ const interpret = <
     if (v.schema !== undefined) data.schema = v.schema
     if (v.mode !== undefined) data.mode = v.mode
     if (v.computed !== undefined) data.computed = v.computed
+    if (v.aggregateMap !== undefined) data.aggregateMap = v.aggregateMap
   }
 
   const applyPath = (path: string) => (_: FilterResult): FilterResult =>
@@ -223,6 +237,31 @@ const interpret = <
       },
       project: (v) => {
         upd(interpret(v.current))
+        if (v.mode === "aggregate" && v.aggregateMap) {
+          data.schema = v.schema
+          data.mode = "aggregate"
+          data.aggregateMap = Object.fromEntries(
+            Object.entries(v.aggregateMap).map(([key, expression]) => {
+              switch (expression._tag) {
+                case "agg-field":
+                  return [key, { _tag: "agg-field" as const, path: expression.path }]
+                case "agg-count":
+                  return [key, { _tag: "agg-count" as const }]
+                case "agg-count-when": {
+                  const filter = interpret(expression.operation(make())).filter
+                  return [key, { _tag: "agg-count-when" as const, filter }]
+                }
+                case "agg-sum":
+                  return [key, { _tag: "agg-sum" as const, field: expression.field }]
+                case "agg-min":
+                  return [key, { _tag: "agg-min" as const, field: expression.field }]
+                case "agg-max":
+                  return [key, { _tag: "agg-max" as const, field: expression.field }]
+              }
+            })
+          )
+          return
+        }
         if (v.computed && v.mode === "transform") {
           throw new Error("Computed projections require mode 'project' or 'collect', not 'transform'")
         }
@@ -329,6 +368,29 @@ export const toFilter = <
 ) => {
   // TODO: Native interpreter for each db adapter, instead of the intermediate "new-kid" format
   const a = interpret(q)
+
+  // Aggregate mode: build select entirely from aggregateMap (no schema-driven field list)
+  if (a.mode === "aggregate" && a.aggregateMap) {
+    const aggSelect = Object.entries(a.aggregateMap).map(([key, item]) => {
+      if (item._tag === "agg-field") {
+        return { key, path: item.path }
+      }
+      return { key, aggregate: item }
+    })
+    return dropUndefinedT({
+      t: null as unknown as TFieldValues,
+      limit: a.limit,
+      skip: a.skip,
+      select: Option.getOrUndefined(toNonEmptyArray(aggSelect)) as any,
+      schema: a.schema,
+      computed: undefined,
+      order: Option.getOrUndefined(toNonEmptyArray(a.order)),
+      ttype: a.ttype,
+      mode: "aggregate" as const,
+      filter: a.filter.length ? a.filter : undefined
+    })
+  }
+
   const schema = a.schema
   let select: (keyof TFieldValues | { key: string; subKeys: string[] } | {
     key: string

package/src/Store/Cosmos/query.ts

@@ -6,7 +6,7 @@ import * as Effect from "effect-app/Effect"
 import { assertUnreachable } from "effect-app/utils"
 import { InfraLogger } from "../../logger.js"
 import type { FilterR, FilterResult, Ops } from "../../Model/filter/filterApi.js"
-import type { ComputedProjectionIrExpression, ComputedProjectionMathIrExpression } from "../../Model/query.js"
+import type { AggregateIrExpression, ComputedProjectionIrExpression, ComputedProjectionMathIrExpression } from "../../Model/query.js"
 import { isRelationCheck } from "../codeFilter.js"
 import type { SupportedValues } from "../service.js"
 
@@ -50,6 +50,12 @@ export function buildWhereCosmosQuery3(
     } | {
       key: string
       computed: ComputedProjectionIrExpression
+    } | {
+      key: string
+      path: string
+    } | {
+      key: string
+      aggregate: AggregateIrExpression
     }
   >,
   order?: NonEmptyReadonlyArray<{ key: string; direction: "ASC" | "DESC" }>,
@@ -293,7 +299,43 @@ export function buildWhereCosmosQuery3(
       typeof _ === "object" && "computed" in _ && "filter" in _.computed ? getValues(_.computed.filter) : []
     )
     : []
-  const values = [...computedFilters, ...getValues(filter)]
+  const aggregateFilters = select
+    ? select.flatMap((_) =>
+      typeof _ === "object" && "aggregate" in _ && "filter" in _.aggregate ? getValues(_.aggregate.filter) : []
+    )
+    : []
+  const values = [...computedFilters, ...aggregateFilters, ...getValues(filter)]
+
+  const hasAggregates = select
+    ? select.some((s) => typeof s === "object" && s !== null && "aggregate" in s)
+    : false
+
+  const aggregateSelectExpr = (key: string, agg: AggregateIrExpression): string => {
+    switch (agg._tag) {
+      case "agg-count":
+        return `COUNT(1) AS ${key}`
+      case "agg-count-when": {
+        if (agg.filter.length === 0) return `COUNT(1) AS ${key}`
+        const cond = print(agg.filter, null, false)
+        // Cosmos supports SUM(IIF(cond, 1, 0)) as a conditional count
+        return `SUM(IIF(${cond}, 1, 0)) AS ${key}`
+      }
+      case "agg-sum": {
+        const fieldRef = dottedToAccess(`f.${agg.field}`)
+        return `SUM(${fieldRef}) AS ${key}`
+      }
+      case "agg-min": {
+        const fieldRef = dottedToAccess(`f.${agg.field}`)
+        return `MIN(${fieldRef}) AS ${key}`
+      }
+      case "agg-max": {
+        const fieldRef = dottedToAccess(`f.${agg.field}`)
+        return `MAX(${fieldRef}) AS ${key}`
+      }
+      default:
+        return assertUnreachable(agg)
+    }
+  }
 
   const computedSelectExpr = (key: string, computed: ComputedProjectionIrExpression) => {
     const relationPath = computed.path
@@ -378,28 +420,47 @@ export function buildWhereCosmosQuery3(
       }
     }
   }
+
+  const buildSelectList = (): string => {
+    if (!select) return "f"
+    return select
+      .map((s) => {
+        if (typeof s === "string") {
+          return dottedToAccess(s === idKey ? "f.id" : `f.${s}`)
+        }
+        if ("computed" in s) return computedSelectExpr(s.key, s.computed)
+        if ("aggregate" in s) return aggregateSelectExpr(s.key, s.aggregate)
+        if ("path" in s) return `${dottedToAccess(`f.${s.path}`)} AS ${s.key}`
+        // subKeys
+        return `ARRAY (SELECT ${s.subKeys.map((_) => dottedToAccess(`t.${_}`)).join(",")}
+                FROM t in ${dottedToAccess(`f.${s.key}`)}) AS ${s.key}`
+      })
+      .join(", ")
+  }
+
+  const groupByClause = hasAggregates && select
+    ? (() => {
+      const groupByExprs = select
+        .filter((s): s is { key: string; path: string } =>
+          typeof s === "object" && s !== null && "path" in s && !("aggregate" in s)
+        )
+        .map((s) => dottedToAccess(`f.${s.path}`))
+      return groupByExprs.length > 0 ? `GROUP BY ${groupByExprs.join(", ")}` : ""
+    })()
+    : ""
+
+  const orderExpr = (key: string) => hasAggregates ? key : dottedToAccess(`f.${key}`)
+
   // with joins, you should use DISTINCT
   // or you can end up with duplicates
   return {
     query: `
-    SELECT ${
-      select
-        ? select
-          .map((s) =>
-            typeof s === "string"
-              ? dottedToAccess(s === idKey ? "f.id" : `f.${s}`) // x["y"} vs x.y, helps with reserved keywords like "value"
-              : "computed" in s
-              ? computedSelectExpr(s.key, s.computed)
-              : `ARRAY (SELECT ${s.subKeys.map((_) => dottedToAccess(`t.${_}`)).join(",")}
-                FROM t in ${dottedToAccess(`f.${s.key}`)}) AS ${s.key}`
-          )
-          .join(", ")
-        : "f"
-    }
+    SELECT ${buildSelectList()}
     FROM ${name} f
 
     ${filter.length ? `WHERE (${print(filter, null, false)})` : ""}
-    ${order ? `ORDER BY ${order.map((_) => `${dottedToAccess(`f.${_.key}`)} ${_.direction}`).join(", ")}` : ""}
+    ${groupByClause}
+    ${order ? `ORDER BY ${order.map((_) => `${orderExpr(_.key)} ${_.direction}`).join(", ")}` : ""}
     ${skip !== undefined || limit !== undefined ? `OFFSET ${skip ?? 0} LIMIT ${limit ?? 999999}` : ""}`,
     parameters: values
       .flatMap((x, i) =>

package/src/Store/Memory.ts

@@ -16,7 +16,7 @@ import * as Struct from "effect/Struct"
 import { InfraLogger } from "../logger.js"
 import type { FilterResult } from "../Model/filter/filterApi.js"
 import type { FieldValues } from "../Model/filter/types.js"
-import type { ComputedProjectionIrExpression, ComputedProjectionMathIrExpression } from "../Model/query.js"
+import type { AggregateIrExpression, ComputedProjectionIrExpression, ComputedProjectionMathIrExpression } from "../Model/query.js"
 import { annotateDb } from "../otel.js"
 import { codeFilter, codeFilter3_ } from "./codeFilter.js"
 import { type FilterArgs, type PersistenceModelType, type Store, type StoreConfig, StoreMaker } from "./service.js"
@@ -174,12 +174,76 @@ const computeProjectionValue = (
   }
 }
 
+const computeAggregateValue = <T extends FieldValues>(rows: readonly T[], agg: AggregateIrExpression): unknown => {
+  switch (agg._tag) {
+    case "agg-count":
+      return rows.length
+    case "agg-count-when": {
+      const filter = agg.filter
+      const matches = filter.length === 0 ? () => true : (row: unknown) => codeFilter3_(filter, row)
+      return rows.filter((row) => matches(row)).length
+    }
+    case "agg-sum":
+      return rows.reduce<number>((acc, row) => {
+        const v = get(row, agg.field)
+        return acc + (typeof v === "number" ? v : Number(v) || 0)
+      }, 0)
+    case "agg-min": {
+      let min: unknown = undefined
+      for (const row of rows) {
+        const v = get(row, agg.field)
+        if (v == null) continue
+        if (min === undefined || v < (min as any)) min = v
+      }
+      return min ?? null
+    }
+    case "agg-max": {
+      let max: unknown = undefined
+      for (const row of rows) {
+        const v = get(row, agg.field)
+        if (v == null) continue
+        if (max === undefined || v > (max as any)) max = v
+      }
+      return max ?? null
+    }
+    default:
+      return assertUnreachable(agg)
+  }
+}
+
 export function memFilter<T extends FieldValues, U extends keyof T = never>(f: FilterArgs<T, U>) {
   type M = U extends undefined ? T : Pick<T, U>
   return ((c: T[]): M[] => {
-    const select = (r: T[]): M[] => {
-      const sel = f.select
+    const sel = f.select
+
+    const selectPerRow = (r: T[]): M[] => {
       if (!sel) return r as M[]
+
+      // Detect aggregate mode: any select item has `aggregate` key
+      const hasAggregates = sel.some((s) => typeof s === "object" && s !== null && "aggregate" in s)
+      if (hasAggregates) {
+        // GROUP BY + aggregate
+        const fieldItems = sel.filter((s): s is { key: string; path: string } =>
+          typeof s === "object" && s !== null && "path" in s && !("aggregate" in s)
+        )
+        const aggregateItems = sel.filter((s): s is { key: string; aggregate: AggregateIrExpression } =>
+          typeof s === "object" && s !== null && "aggregate" in s
+        )
+        const groups = new Map<string, T[]>()
+        for (const row of r) {
+          const key = fieldItems.map((fi) => JSON.stringify(get(row, fi.path))).join("\0")
+          const existing = groups.get(key) ?? []
+          existing.push(row)
+          groups.set(key, existing)
+        }
+        return [...groups.values()].map((rows) => {
+          const result: Record<string, unknown> = {}
+          for (const fi of fieldItems) result[fi.key] = get(rows[0]!, fi.path)
+          for (const ai of aggregateItems) result[ai.key] = computeAggregateValue(rows, ai.aggregate)
+          return result as M
+        })
+      }
+
       return r.map((i) => {
         const [keys, entries] = pipe(
           sel,
@@ -192,6 +256,9 @@ export function memFilter<T extends FieldValues, U extends keyof T = never>(f: F
           key: string
           computed: ComputedProjectionIrExpression
         } => typeof entry === "object" && entry !== null && "computed" in entry)
+        const pathKeys = entries.filter((entry): entry is { key: string; path: string } =>
+          typeof entry === "object" && entry !== null && "path" in entry && !("aggregate" in entry)
+        )
         const n = Struct.pick(i, keys)
         subKeys.forEach((subKey) => {
           n[subKey.key] = i[subKey.key]!.map(Struct.pick(subKey.subKeys as never[]))
@@ -199,9 +266,13 @@ export function memFilter<T extends FieldValues, U extends keyof T = never>(f: F
         computedKeys.forEach((entry) => {
           ;(n as Record<string, unknown>)[entry.key] = computeProjectionValue(i, entry.computed)
         })
+        pathKeys.forEach((entry) => {
+          ;(n as Record<string, unknown>)[entry.key] = get(i, entry.path)
+        })
         return n as M
       })
     }
+
     const skip = f?.skip
     const limit = f?.limit
     const ords = Option.map(Option.fromNullishOr(f.order), (_) =>
@@ -223,7 +294,7 @@ export function memFilter<T extends FieldValues, U extends keyof T = never>(f: F
       c = Array.sortBy(...ords.value)(c)
     }
     if (!skip && limit === 1) {
-      return select(
+      return selectPerRow(
         Array.findFirst(c, f.filter ? codeFilter(f.filter) : (_) => Option.some(_)).pipe(
           Option.map(Array.make),
           Option.getOrElse(
@@ -240,7 +311,7 @@ export function memFilter<T extends FieldValues, U extends keyof T = never>(f: F
       r = Array.take(r, limit)
     }
 
-    return select(r)
+    return selectPerRow(r)
   })
 }
 

package/src/Store/SQL/query.ts

@@ -4,7 +4,7 @@ import * as Effect from "effect-app/Effect"
 import { assertUnreachable } from "effect-app/utils"
 import { InfraLogger } from "../../logger.js"
 import type { FilterR, FilterResult } from "../../Model/filter/filterApi.js"
-import type { ComputedProjectionIrExpression, ComputedProjectionMathIrExpression } from "../../Model/query.js"
+import type { AggregateIrExpression, ComputedProjectionIrExpression, ComputedProjectionMathIrExpression } from "../../Model/query.js"
 import { isRelationCheck } from "../codeFilter.js"
 
 export interface SQLDialect {
@@ -164,6 +164,12 @@ export function buildWhereSQLQuery(
     } | {
       key: string
       computed: ComputedProjectionIrExpression
+    } | {
+      key: string
+      path: string
+    } | {
+      key: string
+      aggregate: AggregateIrExpression
     }
   >,
   order?: NonEmptyReadonlyArray<{ key: string; direction: "ASC" | "DESC" }>,
@@ -497,6 +503,30 @@ export function buildWhereSQLQuery(
     }
   }
 
+  const aggregateSelectExpr = (key: string, agg: AggregateIrExpression): string => {
+    switch (agg._tag) {
+      case "agg-count":
+        return `COUNT(1) AS "${key}"`
+      case "agg-count-when": {
+        if (agg.filter.length === 0) return `COUNT(1) AS "${key}"`
+        const cond = print([{ t: "where-scope", result: agg.filter, relation: "some" }], null, false)
+        return `COUNT(CASE WHEN ${cond} THEN 1 END) AS "${key}"`
+      }
+      case "agg-sum":
+        return `COALESCE(SUM(${fieldExpr(agg.field)}), 0) AS "${key}"`
+      case "agg-min":
+        return `MIN(${fieldExpr(agg.field)}) AS "${key}"`
+      case "agg-max":
+        return `MAX(${fieldExpr(agg.field)}) AS "${key}"`
+      default:
+        return assertUnreachable(agg)
+    }
+  }
+
+  const hasAggregates = select
+    ? select.some((s) => typeof s === "object" && s !== null && "aggregate" in s)
+    : false
+
   const getSelectExpr = (): string => {
     if (!select) return "id, _etag, data"
     const fields = select.map((s) => {
@@ -508,6 +538,13 @@ export function buildWhereSQLQuery(
       if ("computed" in s) {
         return computedSelectExpr(s.key, s.computed)
       }
+      if ("aggregate" in s) {
+        return aggregateSelectExpr(s.key, s.aggregate)
+      }
+      if ("path" in s) {
+        // Group-by fields: extract as scalar (not JSON-encoded) so grouping works and values compare as plain strings/numbers
+        return `${fieldExpr(dottedToJsonPath(s.path))} AS "${s.key}"`
+      }
       return `${dialect.jsonExtractJson(s.key)} AS "${s.key}"`
     })
     return fields.join(", ")
@@ -531,15 +568,36 @@ export function buildWhereSQLQuery(
     ? `WHERE ${userWhere}`
     : ""
 
+  const groupByClause = hasAggregates && select
+    ? (() => {
+      const groupByExprs = select
+        .filter((s): s is string | { key: string; path: string } =>
+          typeof s === "string" || (typeof s === "object" && s !== null && "path" in s)
+        )
+        .map((s) => typeof s === "string" ? fieldExpr(s) : fieldExpr(dottedToJsonPath(s.path)))
+      return groupByExprs.length > 0 ? `GROUP BY ${groupByExprs.join(", ")}` : ""
+    })()
+    : ""
+
   const orderClause = order
-    ? `ORDER BY ${order.map((_) => `${fieldExpr(_.key)} ${_.direction}`).join(", ")}`
+    ? `ORDER BY ${
+      order
+        .map((_) =>
+          hasAggregates
+            ? `"${_.key}" ${_.direction}`
+            : `${fieldExpr(_.key)} ${_.direction}`
+        )
+        .join(", ")
+    }`
     : ""
 
   const limitClause = limit !== undefined || skip !== undefined
     ? `LIMIT ${addParam(limit ?? 999999)} OFFSET ${addParam(skip ?? 0)}`
     : ""
 
-  const sql = `SELECT ${selectExpr} FROM "${tableName}" ${whereClause} ${orderClause} ${limitClause}`.trim()
+  const sql = `SELECT ${selectExpr} FROM "${tableName}" ${whereClause} ${groupByClause} ${orderClause} ${limitClause}`
+    .replace(/\s+/g, " ")
+    .trim()
 
   return { sql, params }
 }

package/src/Store/service.ts

@@ -10,7 +10,7 @@ import type { OptimisticConcurrencyException } from "../errors.js"
 import type { FilterResult } from "../Model/filter/filterApi.js"
 import type { FieldValues } from "../Model/filter/types.js"
 import type { FieldPath } from "../Model/filter/types/path/index.js"
-import type { ComputedProjectionIrExpression, RawQuery } from "../Model/query.js"
+import type { AggregateIrExpression, ComputedProjectionIrExpression, RawQuery } from "../Model/query.js"
 
 export interface StoreConfig<E> {
   partitionValue: (e?: E) => string
@@ -70,6 +70,12 @@ export interface FilterArgs<Encoded extends FieldValues, U extends keyof Encoded
       U | { key: string; subKeys: readonly string[] } | {
         key: string
         computed: ComputedProjectionIrExpression
+      } | {
+        key: string
+        path: string
+      } | {
+        key: string
+        aggregate: AggregateIrExpression
       }
     >
     | undefined