Grouping 50 million rows by a key returns immediately — what has actually been built at that point?

## What a grouping call hands back A **grouped handle** is what a grouping call returns before any per-group computation has run: it records which rows belong to which key value and nothing else. That is the whole reason a grouping call over fifty million rows can return in a moment. The expensive things — reading each group's values, folding them, assembling a result — have not happened. Concretely the split does two things: 1. Evaluate the **grouping key** — the column, columns or expression whose value decides which rows belong together — once for every row. 2. Organise those values so the rows carrying each distinct value can be found again, by recording row **positions** against each key value. ## Bookkeeping against copying The distinction worth carrying out of this question is between *forming* the groups and *materialising* them. - **Forming the groups** is bookkeeping: a mapping from key value to a set of row positions. It holds no copy of the data. - **Materialising a group** means gathering that key's rows into a table of its own. That is real work and real memory, and it happens only when something asks for it. Some designs do materialise a sub-table per group, and any design materialises at the moment something demands a whole table as an argument. So the useful question is never "does grouping copy?" but "what in my step forces the copy?" ## What forces the copy | what the apply is | what it needs | does it materialise | | --- | --- | --- | | a reduction the library implements (sum, count, minimum) | the column's values at the recorded positions | normally not | | a body handed the group's column | that one column, gathered | one column at most | | a body handed the whole group as a table | every column of the group, side by side | yes | | anything returning rows rather than a value | somewhere to assemble the rows | yes, on the output side | The practical consequence is that a **hand-written per-group body** — a function you supply that the library cannot look inside — is the usual reason a grouped step that should have streamed suddenly allocates. It is not that the body is yours; it is what the surface hands it. ## What the bookkeeping itself costs It is not free. One key evaluation happens per row, and the structure holds one entry per distinct key plus one position per row. Where the number of distinct keys approaches the number of rows, that structure is comparable in size to the column you grouped on. "Grouping returned instantly, so grouping is cheap" is therefore only half true: it returned instantly because the work was deferred, not because the work is small. ## How long the handle lives Designs disagree here, and the disagreement produces a real bug class: - In some, grouping is a **state the table carries** until explicitly removed, so subsequent operations honour it and a step written as though it were over the whole table is silently computed per group. - In others, grouping produces a **transient handle** consumed by the very next call, after which the result is an ordinary table with no memory of the split. Neither is wrong; they are different contracts. The hazard — a summary computed one level less grouped than the author believed — is live only in the first model, so it is worth knowing which one you are in before chaining a second step. ## Sorted runs against hashed buckets There are two common routes to the bookkeeping: - A **sorted split** orders the key column so equal keys form a contiguous run. It pays an ordering cost up front and makes the subsequent reads sequential. - A **hashed split** drops each key value into a bucket by its hash. It avoids the ordering cost, and the reads it feeds are scattered. Both produce the same grouping. They differ in cost, and in whether they leave an ordering behind as a by-product. ## What this changes about how you write the step - Read a fast-returning grouping call as **nothing having happened yet**, never as evidence the operation is cheap. - If the step allocates unexpectedly, look at what the apply is handed before you look at the data volume. - Prefer a reduction the library implements when one exists, because that is the path that can fold over the original storage. - When you do need your own body, prefer a surface that hands it a column over one that hands it a whole table, where the design offers both.