In a normalized cache, which arguments of a paginated list field belong in the storage key?

## One argument list doing two different jobs A paginated field's arguments look uniform in the document and are not. Some of them decide **which set of items the field denotes**; the rest decide **which window of that set you are being handed**. A normalized cache's storage key should capture the first group and nothing else, because the key is meant to be the identity of the list and the merge rule is meant to accumulate windows into it. **Identity arguments** — keep them in the key: - filters: `status: PAID`, `planYear: 2026`, a date range, a search term; - ordering: the sort field and direction; - scope: the account, employer or viewer the list belongs to, when it is expressed as an argument. **Window arguments** — leave them out: - `after` / `before` cursors, `offset` / `skip`; - `first` / `last` / `limit` page size. ```graphql query Statements($status: PayStatementStatus!, $after: String) { employee(id: "emp_4471") { # status and sort identify the list; first and after only window it payStatements(status: $status, sort: PERIOD_END_DESC, first: 25, after: $after) { edges { node { id periodEnd netPay } } pageInfo { endCursor hasNextPage } } } } ``` ## The failure when you drop too much A payroll team excluded `after` from the key — correctly — and excluded `status` at the same time, on the reasoning that the screen only ever shows one tab at a time. It does, but the cache does not know that. Switching from the PAID tab to the VOIDED tab wrote a different set of rows into the same entry, and the merge rule appended, so the list showed paid statements followed by voided ones under a heading that claimed one status. It got worse when the schema gained a new member on the status enum, `REVERSED`, that the tab bar had no branch for. Rows of a status the renderer's switch fell through on now sat inside an accumulated list that no longer corresponded to any single filter, showing as blank rows partway down; and because the entry never reset on a tab change it grew until the list view missed its 340 ms p99 render budget. The fix was one line — put `status` back in the key. Each tab then owns its own accumulating entry, and switching back to a tab is instant because its rows are still there. ## The failure when you keep too much The opposite mistake is the default. Leave the cursor in the key and every page becomes a separate entry, so the merge rule never runs, "load more" appears to replace the list, and memory holds one reference list per page. There is a third category that is easy to miss: arguments that vary per request without changing the answer. A `now:` timestamp used for relative filtering, a client-generated request id, a correlation value added for tracing. Left in the key, each of them mints a fresh entry on every call, so the cache never hits, the store grows for the whole session, and the symptom reads as "the cache does nothing" or as a memory leak. The best fix is usually to stop sending the argument. ## Sort order deserves its own paragraph Sort is an identity argument, and cursor pagination makes that structural rather than aesthetic: a cursor is only meaningful within the ordering that produced it. If the sort argument is left out of the key, changing the sort accumulates the new ordering into the entry built under the old one, and the next cursor is applied against an ordering the accumulated list no longer reflects. Keeping sort in the key makes the change automatic — new key, empty entry, a clean first page. ## Viewer scope and identity changes A list scoped to a person is only safe to keep for as long as that person is the one looking. Encoding the viewer into every field's key is possible but brittle; the usual discipline is coarser and stronger — reset the whole store when the signed-in identity changes, on sign-in and sign-out alike, so nothing cached under one account can be read under another. ## A mechanical way to decide For each argument, ask: *if I changed only this, would the server return a different set of items, or a different window on the same set?* Different set means it belongs in the key. Different window means it belongs to the merge rule. Neither means it should not be an argument on the request at all. ## The cost of getting it right Keeping identity arguments in the key is correct and not free: every distinct combination retains its own accumulated list for the session. A filter panel with a free-text search box will mint an entry per keystroke unless that argument is debounced, and a rich filter UI can hold dozens of accumulated lists at once. Budget for it — evict on route change, cap retained combinations, and reset on sign-out. None of this is specified. The GraphQL specification defines the type system, documents and execution; storage keys, key-argument selection and merge rules are conventions of client caches, and the vocabulary differs between them even where the mechanism does not.