[arv]

Do not merge before Zero 1.12 is released. Aggregates, distinct() and groupBy() are not in a released Zero version yet. Keep this a draft until then.

Re-lands #328, which merged too early and was reverted in #331. The change to contents/docs/zql.mdx is identical to #328.

Adds an Aggregates section to the ZQL page covering count(), sum(), avg(), min(), and max() on queries and relationships:

• A top-level aggregate returns a single value. On a relationship, each row gets the value in place of the related rows.
• Only the result is synced, and it stays up to date as rows change.
• where(), start(), and limit() apply before the aggregate, as in SQL.
• Column types, empty results (0 for count(), null otherwise), and which aggregates update immediately when a mutator runs.

It also adds Distinct and Group By subsections, for distinct() and groupBy(...).count()/sum()/avg()/min()/max():

• distinct() returns one row per combination of its columns, and distinct().count() counts them, with null counted as a value, unlike SQL's COUNT(DISTINCT).
• groupBy() returns one row per group with the aggregate under the function's name. null forms a group, and rows are ordered by the grouped columns only.
• What they don't support yet: limit(), start(), one(), related(), a further aggregate, use in related()/whereExists(), JSON group columns, and ordering by the aggregate.
• Which ones update immediately when a mutator runs.

Also regenerates assets/search-index.json. It will conflict in that file with the JSON filters docs PR; whichever lands second needs the index regenerated. The roadmap and status pages still list aggregates and group-by as future work and should be updated when this merges.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
zero-docs	Ready	Preview	Nov 6, 2026 11:25am UTC

[Copilot]

🟡 Changes recommended

An active documentation issue remains because the restriction around chaining distinct() and count() is ambiguous and contradicts nearby guidance.

1 open issue

• Clarify that distinct().count() is supported as a terminal aggregate · New

What changed in this PR

Documents ZQL aggregate, distinct(), and groupBy() query capabilities, along with regenerated search metadata.

Changes:

• Adds aggregate documentation for queries and relationships, including result semantics, synchronization, supported types, and mutation timing.
• Documents distinct() and groupBy() behavior, examples, limitations, null handling, ordering, and update behavior.
• Regenerates the search index with the new sections and updated identifiers.

File	Description
contents/​docs/​zql.mdx	Adds documentation for ZQL aggregates, distinct(), and groupBy(), including examples, semantics, limitations, and synchronization behavior.
assets/​search-index.json	Indexes the new ZQL documentation sections and updates subsequent section identifiers.

_{Review effort: Lite}