TaskGroup

One group's share of the whole matching corpus, when a query asked for counts with group_by.

Keyed by `(workspace, key)`, because a ListId belongs to one workspace's list table and folding two workspaces' rails together would name a group neither of them has. A bucket key is universal rather than workspace-scoped, and the rows stay per workspace anyway: a task belongs to exactly one workspace, so a cross-workspace rail sums them and loses nothing, while folding here would throw away an answer a client may want.

Under group_by: "list" these do not overlap: koru.list is cardinality-one, so a task is in exactly one list or in none, and the counts sum to at most the number of matching tasks. A list nothing matches has no row rather than a zero - a client draws its rail from the list table and reads a missing group as an empty bucket. Buckets partition the corpus for the same reason and completely: every task is in exactly one of the five, so those counts sum to the whole matching set.

Type object

Shape

Field	Type	Description
workspacerequired	WorkspaceId	Which workspace this group counts in.
listrequired	string	The group's key, in the vocabulary the query's `group_by` named: a `ListId` in storage form under `"list"`, one of [`BUCKETS`] under `"bucket"`. A list id the table no longer names still counts - a deleted list's memberships clear document by document, and a stale value is not a missing task. The field is spelled `list` because lists were the only grouping when it was published, and this route's schemas are generated and consumed: widening the name would break every caller and every literal built against it for a rename. It wants to be `key`, and that is a rename to make in one change with its call sites rather than a second field carrying a second meaning.
countrequired	integer (uint, >= 0)	Matching tasks in this group across the whole corpus - not the page.
overduerequired	integer (uint, >= 0)	How many of `count` are overdue: by the windows the query's `overdue` named when grouping by list, and by `bucket_windows`' `today` and `now_ms` when grouping by bucket - one notion of overdue through one SQL builder, stated once by whichever object the grouping already required. Zero when nothing named it; dateless tasks are never overdue, and a completed task is not overdue whatever its due says.
trashedrequired	integer (uint, >= 0)	How many of `count` sit in a binned document. Counted and flagged rather than dropped, exactly as those rows are.

Example

{
  "workspace": {},
  "list": "string",
  "count": 0,
  "overdue": 0,
  "trashed": 0
}

The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Generated from contract version 1. Last updated November 12, 2026.