Create a group
A group keeps aggregates per value of a key attribute, over the documents matching match, and GET reports
them: a group-by you declare, for reporting. The aggregates are at most about an hour behind the namespace’s writes.
Creating one starts a group_build job that computes its first
aggregates with no fan-out, over every document the namespace
holds, including those written just before. The same create again
returns the group; a name another group already has, with other
settings or inherited from the template, is conflict. On a
template prefix it exists in every
namespace under it, each with its own aggregates. At most 8 groups
per namespace, counting
inherited ones, and at most 1,000 live key values per group: a key
attribute with more at create is invalid_request. A key value with
no matching document newer than keep_keys is not live.
Authorizations
An organization API key. Keys carry a role (read_write or
read_only) and may be restricted to a namespace prefix such as
acme/*, or to one namespace such as acme/prod/tenant_1. A prefix
matches on a / boundary: acme/prod/tenant_1* covers
acme/prod/tenant_1 and everything under acme/prod/tenant_1/,
never acme/prod/tenant_12.
Headers
One key per logical request, reused only on its retries. A key
belongs to one request: within your organization, the same method,
path, query and body. For 24 hours after a successful response, a
request with the key and the same body gets that response back
verbatim, with Idempotent-Replayed: true, and runs nothing. Only a
successful response is kept, so the retry of a request that failed
runs again. While the first request runs or its response is kept,
the key with a different request is idempotency_key_reused (422).
A request sent while one with its key is still running is
rate_limited with Retry-After: 1, without running: retry it to
get the first one's response. In the rare case the key can't be
checked, the request runs as if it had none.
1 - 255Path Parameters
A namespace name, or a template prefix ending in /*, with any
/ sent as %2F: acme%2Fprod%2Ftenant_123 or acme%2Fprod%2F*.
A namespace name, or a template prefix: a namespace path ending in
/*, such as acme/prod/*, which every namespace under acme/prod/
inherits judgments from. Up to 256 bytes. Never exactly
. or .., which a URL path can't carry.
1 - 256^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$Body
A group definition.
A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..
1 - 128^[A-Za-z0-9_-]+$The attribute whose values the group is kept per, such as attributes.plan. A document with no value there belongs to no key value.
^attributes\.[A-Za-z0-9_-]+$What the group keeps per key value, over the documents matching match, exact as of the group's as_of. At most 8
paths in total. count_where counts documents by plain judgments'
answers, with the roll-up rules: answers.<j>.value or
.thresholds.<name> by equality, .p or .score by a cut. sum,
avg, min and max read document paths only.
Which documents count. All documents when absent.
A key value whose newest matching document was created longer ago than this is not live, and leaves the rows and the 1,000 cap. Defaults to 90d.
^[1-9][0-9]*[smhd]$Response
The group, building, with its group_build job in job_id.
A group, its status and, on get in a namespace, its rows.
A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..
1 - 128^[A-Za-z0-9_-]+$^attributes\.[A-Za-z0-9_-]+$What the group keeps per key value, over the documents matching match, exact as of the group's as_of. At most 8
paths in total. count_where counts documents by plain judgments'
answers, with the roll-up rules: answers.<j>.value or
.thresholds.<name> by equality, .p or .score by a cut. sum,
avg, min and max read document paths only.
A whole number and a unit (s, m, h or d), such as 7d or 1h.
^[1-9][0-9]*[smhd]$building until its group_build job has computed the aggregates, then ready.
building, ready RFC 3339, UTC.
Which documents something applies to, by their attributes. Each key is an attribute path; a value is equality, and a
list of values is In, as in query filters. Keys combine with And.
Present when the group is inherited, the template prefix it comes from.
1 - 256^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$The group_build job, while it runs.
Live key values now; null on a template's prefix path.
x >= 0group_over_cap: more than 1,000 live key values. The rows hold the 1,000 largest by count until key values age out past keep_keys.
group_over_cap The namespace position the rows are exact at. Absent from lists and on a template's prefix path.
x >= 0On get in a namespace, one row per live key value, the largest count first. Null on a template's prefix path, absent from lists.
1000