---
id: "packages/active-grid/api/helpers-server-contract"
title: "Server contract (helpers)"
description: "aggregateCount, aggregateScalar, byCount, byField and 12 more: generated from the source of active-grid."
url: "/packages/active-grid/api/helpers-server-contract"
locale: "en"
revision: "g0mvjxwj5c-88bdbe1c:helpers-server-contract"
---

# Server contract (helpers)

Exported by `@workspace/active-grid`. Generated from the package source; part of [the index of every export](/packages/active-grid/api).

## Functions, hooks and constants

**aggregateCount**: `(args?: { relation?: string; }) => AggregateCountMapping`

Aggregate mapping for a count. With `relation`: produces Prisma
`_count: {<relation>: true}` — number of related records per group.
With `relation: null` or omitted: produces Prisma `_count: {_all: true}`
— number of rows per group, regardless of any specific field.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | no |  |

**aggregateScalar**: `(args: { path?: string; ops: readonly AggregateOp[]; }) => AggregateScalarMapping`

Aggregate mapping on a scalar field. Declares **and** selects: under the
single-source-of-truth model, the listed `ops` are both
"what is possible for this column" and "what is displayed per group".
There is no aggregate-toggle UI; a separate selection layer
(engine-state or opt-in prop) could sit on top of this declaration
without breaking it.

If `path` is omitted, the column-id is used. `ops` must be a non-empty
subset of `AggregateOp` (`sum | avg | min | max | count`). Prisma's
`_count`/`_sum`/`_avg`/`_min`/`_max`-blocks are built from this list.

Note: `count` here is the **non-null-count** on the scalar (Prisma
`_count: {<field>: true}`). For relation-counts use `aggregateCount`
with a `relation` argument.

No DMMF-derived default for aggregates. Auto-defaulting
sum/avg over every
numeric scalar is semantically dangerous — a `versionNumber` column
is valid Prisma but nonsensical UX. Consumer declares aggregate
explicitly per column.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `path` | `string` | no | The field of the related record, as a dotted path (`role.name`). |
| `ops` | `readonly AggregateOp[]` | yes |  |

**byCount**: `(relation: string) => SortCountMapping`

Sort mapping on the count of a relation. Produces Prisma
`orderBy: {<relation>: {_count: <direction>}}`.

**byField**: `(path?: string) => SortFieldMapping`

Sort mapping on a scalar field. If `path` is omitted, the server uses
the column-id as path.

**everyByField**: `(args: { relation: string; path: string; filterType?: ColumnFilterType; }) => FilterRelationMapping`

Filter mapping with relation `every`. The filter passes only if every
related record matches.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | yes | The relation on the record the condition runs through, as the server query names it (`userRoles` in `userRoles: {some: …}`). |
| `path` | `string` | yes | The field of the related record, as a dotted path (`role.name`). |
| `filterType` | `ColumnFilterType` | no | Overrides type-inference when the operator alone is ambiguous (`equals` can be text, number or date). |

**fieldFilter**: `(path?: string, options?: { filterType?: ColumnFilterType; }) => FilterFieldMapping`

Filter mapping on a scalar field. If `path` is omitted, the server uses
the column-id as path. `filterType` overrides type-inference when the
operator alone is ambiguous (e.g. `equals` can be text / number / date).

Fields of `options`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `filterType` | `ColumnFilterType` | no | Overrides type-inference when the operator alone is ambiguous (`equals` can be text, number or date). |

**globalEveryByField**: `(args: { relation: string; path: string; operator?: GlobalOperator; }) => GlobalRelationMapping`

Global-search mapping with relation `every`. The column participates in
the search only if every related record matches the query.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | yes | The relation on the record the condition runs through, as the server query names it (`userRoles` in `userRoles: {some: …}`). |
| `path` | `string` | yes | The field of the related record, as a dotted path (`role.name`). |
| `operator` | `GlobalOperator` | no | How the query matches: `"contains"` (case-insensitive) when omitted, `"startsWith"` for a prefix match, `"equals"` for an exact match. |

**globalField**: `(path?: string, options?: { operator?: GlobalOperator; }) => GlobalFieldMapping`

Mark a column as participating in the global search-box (the toolbar's
single-search input). When the user types a query and `column.server.global`
is set on at least one column, the server-action wraps the per-column
conditions in an `OR`-clause that is ANDed with the column-filters and
`extraWhere`.

If `path` is omitted, the column-id is used (consistent with `byField` /
`fieldFilter`). `operator` defaults to `"contains"` (case-insensitive)
on the server side; override for prefix-match (`"startsWith"`) or
exact-match (`"equals"`) semantics.

Fields of `options`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | `GlobalOperator` | no | How the query matches: `"contains"` (case-insensitive) when omitted, `"startsWith"` for a prefix match, `"equals"` for an exact match. |

**globalNoneByField**: `(args: { relation: string; path: string; operator?: GlobalOperator; }) => GlobalRelationMapping`

Global-search mapping with relation `none`. The column participates in
the search only if no related record matches the query.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | yes | The relation on the record the condition runs through, as the server query names it (`userRoles` in `userRoles: {some: …}`). |
| `path` | `string` | yes | The field of the related record, as a dotted path (`role.name`). |
| `operator` | `GlobalOperator` | no | How the query matches: `"contains"` (case-insensitive) when omitted, `"startsWith"` for a prefix match, `"equals"` for an exact match. |

**globalSomeByField**: `(args: { relation: string; path: string; operator?: GlobalOperator; }) => GlobalRelationMapping`

Global-search mapping with relation `some`. The column participates in
the search if at least one related record matches the query.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | yes | The relation on the record the condition runs through, as the server query names it (`userRoles` in `userRoles: {some: …}`). |
| `path` | `string` | yes | The field of the related record, as a dotted path (`role.name`). |
| `operator` | `GlobalOperator` | no | How the query matches: `"contains"` (case-insensitive) when omitted, `"startsWith"` for a prefix match, `"equals"` for an exact match. |

**groupByField**: `(path?: string) => GroupByFieldMapping`

Group-by mapping on a scalar field. If `path` is omitted, the column-id
is used as path (same convention as `byField` / `fieldFilter` /
`globalField`).

Prisma's `groupBy({by: [...]})` only accepts scalar field-names in `by`.
`groupByField` is the helper for that direct case; for grouping through
a 1:1 relation (where the FK is a scalar on the model itself) use
`groupByRelation()`. One-to-many relations are not expressible as a
declarative group key (grouping through a to-many relation is ambiguous);
server-side grouping for such cases belongs in a resource view
(`@workspace/active-resources`).

**groupByRelation**: `(args: { relation: string; path: string; }) => GroupByRelationMapping`

Group-by mapping that resolves through a relation. Intended for
**1:1 relations** where the FK lives as a scalar on the to-be-grouped
model — e.g. `provider` (FK `providerId`) with `name` as the display
key. The server uses `providerId` for Prisma's `groupBy.by` and
`path` for downstream display resolution; same pattern as how
`scalarField("user.email")` separates Prisma-path from column-id.

For one-to-many relations grouping is ambiguous (which related record's
value determines the group?) — those are not expressible here; server-side
grouping for such cases belongs in a resource view.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | yes | The relation on the record the condition runs through, as the server query names it (`userRoles` in `userRoles: {some: …}`). |
| `path` | `string` | yes | The field of the related record, as a dotted path (`role.name`). |

**multiField**: `(paths: readonly string[], options?: { filterType?: ColumnFilterType; }) => FilterMultiFieldMapping`

Filter mapping that ORs across multiple scalar paths.

Fields of `options`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `filterType` | `ColumnFilterType` | no | Overrides type-inference when the operator alone is ambiguous (`equals` can be text, number or date). |

**noneByField**: `(args: { relation: string; path: string; filterType?: ColumnFilterType; }) => FilterRelationMapping`

Filter mapping with relation `none`. The filter passes only if no
related record matches.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | yes | The relation on the record the condition runs through, as the server query names it (`userRoles` in `userRoles: {some: …}`). |
| `path` | `string` | yes | The field of the related record, as a dotted path (`role.name`). |
| `filterType` | `ColumnFilterType` | no | Overrides type-inference when the operator alone is ambiguous (`equals` can be text, number or date). |

**scalarField**: `(path?: string) => Pick<ServerColumnContract, "sort" \| "filter">`

Shortcut that fills both `sort` and `filter` for a scalar column. The
80%-case helper.

- `scalarField()` — uses the column-id as path (deferred resolution on
the server when the column-id is dotted).
- `scalarField("user.email")` — explicit nested path; both sort and
filter use this path.

Returns a `Pick<ServerColumnContract, "sort" | "filter">` that can be
spread or assigned directly to `column.server`.

**someByField**: `(args: { relation: string; path: string; filterType?: ColumnFilterType; }) => FilterRelationMapping`

Filter mapping with relation `some`. The filter passes if at least one
related record matches.

Fields of `args`:

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `relation` | `string` | yes | The relation on the record the condition runs through, as the server query names it (`userRoles` in `userRoles: {some: …}`). |
| `path` | `string` | yes | The field of the related record, as a dotted path (`role.name`). |
| `filterType` | `ColumnFilterType` | no | Overrides type-inference when the operator alone is ambiguous (`equals` can be text, number or date). |