Group server rows
Let your server group a large result, so the grid loads the groups of one level and the rows of the groups the user opens.
The grid never holds a whole server result, so it cannot bucket rows into groups. When the spec holds groupBy, the server groups the result and sends one list at a time. A list is the groups of one level or the rows of one group.
Send the group spec
Put groupBy in defaultSpec of useDataGridServerRows, in scroll mode or in pages mode. An empty array turns grouping on with no group column. Each aggregate column adds one reducer to spec.aggregates:
"use client";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { useDataGridServerRows } from "@/components/data-grid-server/data-grid-server";
type Order = { id: string; region: string; total: number };
const columns = defineColumns<Order>()([
{ id: "region", header: "Region", accessorKey: "region" },
{
id: "total",
header: "Total",
accessorKey: "total",
type: "number",
aggregate: "sum",
},
]);
export function OrdersGrid() {
const server = useDataGridServerRows<Order>({
mode: "scroll",
defaultSpec: {
sorts: [],
filters: [],
searchText: "",
groupBy: ["region"],
},
fetchRows: async (request) => {
const response = await fetch("/api/orders/groups", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(request),
signal: request.signal,
});
return response.json();
},
});
return <DataGrid {...server.gridProps} columns={columns} />;
}A request carries these fields next to spec, start, and end:
| Field | Meaning |
|---|---|
groupPath | The group whose children the request reads, outermost first. Each segment is { columnId, key }. [] is the top level. |
childKind | "groups" while groupPath is shorter than spec.groupBy. Otherwise "rows". |
spec.groupBy | The group columns, outermost first. |
spec.aggregates | { columnId, reducer } for each reduced column. |
A request without groupBy is a flat request. Your handler for flat rows keeps working.
Answer a list
Answer childKind: "groups" with the groups of one level in order, from start to end:
const answer = {
groups: [
{
key: "North",
childCount: 3,
totalRowCount: 40,
aggregates: { total: 1250 },
},
{ key: null, childCount: 1, totalRowCount: 2, aggregates: { total: null } },
],
groupCount: 2,
totalRowCount: 42, // the top level only
};keyis the stored value.nullis the empty group. The server mergesnulland""into one group, and puts it last.childCountcounts the groups of the next level, or the rows of the last level.totalRowCountcounts the rows of the result under the group.aggregatesholds a finite number for each requested column id, ornullwhen no value counted.labelis optional display text. The default is the text of the column's cell type.
Answer childKind: "rows" with { rows, totalRowCount } for the rows of that group, as for a flat request. Sort and filter the groups and the rows with the same spec. A sort on a group column orders the groups. A filter applies before grouping.
Check the request on your server
parseServerSpec reads groupBy and aggregates, and parseGroupPath(body, spec) reads { groupPath, childKind }. Both bound the input. The limits are 4 levels, 1,024 characters per key, and 32 aggregates. List the columns a client can group by with groupable and aggregatable in ServerSpecColumnRules. Pass every key to your query as a parameter and never build SQL text from it. See the server rows contract.
The grid checks each answer. It throws on an answer with no groups. It throws on a repeated key (1 and "1" repeat), on a bad count, and on a top level without totalRowCount. It cuts a list that is longer than the request, and shows null for an aggregate that is not a finite number.
Behavior
- Scroll mode loads the rows of an open group in blocks, and drops the blocks furthest from the screen past
maxLoadedRows. - Pages mode makes the top level one page of groups.
pager.totalRowCountcounts groups, andpager.unitis"groups". - A change of
groupBy, the spec, or the page size returns to the first list. - A change of the spec scrolls the grid to its first row.
- Groups load by offset. In scroll mode,
source: "sequential"has no effect while the spec groups, and the hook warns once in development. Leavesourceunset or use"random"withgroupBy. - While
groupByis set,prefetchNextPagehas no effect, and the hook warns once in development.revalidateIntervalMsandreshapeDelayMsstill apply. - A link to a group page past the last page requests that page first. When the group count arrives, the pager moves to the last page.
- The open groups lay out at most 10,000,000 view rows. Past that, the view stops and the hook warns once in development. Collapse a group or add a filter.
initialAnswercan be the groups answer of the top level.- An insert, a duplicate, a delete, and a move report the reason
server-groups. - A save, a refusal, and
refresh()keep the open groups. selectAllMatching()counts thetotalRowCountof the result.
A server that groups with the query layer needs no handler. See Query layer.
Related
- Row grouping: the props, the keys, and the client mode
- Server rows contract: the limits and the checks
- Server grouping example: the query layer on a database