# GROUP_CARDINALITY_EXCEEDED — too many distinct group buckets

Raised by `POST /api/entity/stats/{entityName}/{modelVersion}/query`. `CYODA_STATS_GROUP_MAX` (default `10000`) bounds the number of distinct buckets the …

<em>cyoda-go version <a href="https://github.com/Cyoda/cyoda-go/releases/tag/v0.8.4">0.8.4</a></em>

# errors.GROUP_CARDINALITY_EXCEEDED

## NAME

GROUP_CARDINALITY_EXCEEDED — the grouped-statistics query produced more distinct group keys than the configured ceiling allows.

## SYNOPSIS

HTTP: `422` `Unprocessable Entity`. Retryable: `no`.

## DESCRIPTION

Raised by `POST /api/entity/stats/{entityName}/{modelVersion}/query`. `CYODA_STATS_GROUP_MAX` (default `10000`) bounds the number of distinct buckets the endpoint will build. The bound is enforced on both execution paths — the backend's native GROUP BY pushdown and the in-process streaming tally — so the same query is rejected identically on every storage backend.

No partial result is returned: the buckets accumulated so far are a prefix of the answer, not the answer, and returning them would be indistinguishable from a complete result.

Retrying the same request gives the same outcome. Narrow the population with a more selective `condition`, drop a `groupBy` dimension (high-cardinality payload fields such as identifiers are the usual cause), or have an operator raise `CYODA_STATS_GROUP_MAX`. Note that `limit` does not help: it caps the buckets *returned* after the full set has been built, so the ceiling is reached first — a `limit` above the ceiling is itself rejected with `INVALID_LIMIT`.

## SEE ALSO

- errors
- crud
- config
- errors.INVALID_LIMIT

## See also

- [`cyoda help errors`](/help/errors/) — Every error response from the Cyoda REST API carries a structured `errorCode` in the `properties` object. Multiple codes may share the same HTTP status. Programmatic handling keys on `errorCode`, not HTTP status.
- [`cyoda help crud`](/help/crud/) — Entities are instances of models. Each entity has a UUID, a model reference (`entityName`, `modelVersion`), and a lifecycle state managed by the workflow engine. Creating an entity requires the referenced model to be in `LOCKED` state. All write operations run within a Cyoda transaction and return a `transactionId` alongside the affected entity IDs.
- [`cyoda help config`](/help/config/) — Environment variables beat default values. The `_FILE` suffix variant takes precedence over the plain variable when both are set — for example, `CYODA_POSTGRES_URL_FILE=/etc/secrets/db-url` wins over `CYODA_POSTGRES_URL`. There are no command-line flags for configuration values; env vars are the sole configuration surface.
- [`cyoda help errors INVALID_LIMIT`](/help/errors/invalid_limit/) — Raised by `POST /api/entity/stats/{entityName}/{modelVersion}/query`. `limit` is optional; when present it is a top-N cap on the buckets returned, and it must be greater than zero and no greater than the server's `CYODA_STATS_GROUP_MAX` (default `10000`). A value outside that range is rejected up front rather than clamped, so the response never silently covers a smaller set than the one asked for. The message carries the configured maximum.

## Raw formats

- [`/help/errors/group_cardinality_exceeded.json`](/help/errors/group_cardinality_exceeded.json) — full descriptor (matches `GET /help/{topic}` envelope)
- [`/help/errors/group_cardinality_exceeded.md`](/help/errors/group_cardinality_exceeded.md) — body only