Batch Key Design

## What a batch key is actually doing The DataLoader pattern sits between a field resolver and a data source. It is a **convention** — nothing in the GraphQL specification or the GraphQL over HTTP specification mentions it — but it is close to universal, because the execution algorithm resolves a list's child fields item by item and something has to put those calls back together. The shape is always the same. Resolvers call `load(key)`. The loader accumulates the keys reached during one stretch of execution and hands the whole list to a **batch function**, which is expected to return one value per key. That makes the key load-bearing in a way people underestimate: **the key is everything the batch function is told.** It is not a hint, not an id it can enrich from context — it is the complete description of the work. Three properties follow from that, and a key that misses any one of them fails in a different way. ## 1. Sufficiency: the key must fully determine the value Take a bank statements graph: ```graphql type Account { id: ID! displayName: String! balance(asOf: Date!): Money! statements(period: StatementPeriod!): [Statement!]! } ``` A loader for `Account.balance` keyed by account id alone is already wrong, and it is wrong in the quietest possible way. Two selections in the same document — one asking the balance as of the quarter end, one as of today — produce the same key. The loader dedupes them, calls the backend once, and hands the same value to both fields. Nothing throws. One of the two fields is simply reporting a number for a date nobody asked about. The rule is mechanical: enumerate every input that can change the answer — the parent's identifier, each field argument the backend actually honours — and every one of them belongs in the key. The converse rule matters too. Anything **constant for the whole request** — the viewer, a trace id, the connection — does *not* belong in the key. It belongs to the loader instance the request built. Folding it into every key adds bytes and buys nothing, because it never varies within the batch. ## 2. Comparability: the loader must be able to tell two keys apart Inside one request the loader memoizes by key, so repeated `load` calls for the same key hit the backend once. That requires an equality test. Primitive keys — an id string, an integer — compare by value and behave. A key expressed as an object or a tuple usually compares by **reference** in the host runtime, so two structurally identical keys look like two different keys: the deduplication silently stops working, the batch grows, and the same row is fetched several times in one request. The standard remedy is a cache-key function that projects a non-scalar key onto a stable primitive, which is a design exercise of its own. ## 3. One-lookup shape: all keys in a batch must collapse into a single request This is the property candidates skip, and it is the one that decides whether batching pays at all. Batching is only a win if the whole key list becomes **one** call to the backend — in the common case, one predicate over a set of values: *return every row whose account id is in this set*. So the keys must differ only along a dimension that a single lookup can vary. Ids: fine, they go into the set. A statement period that is the same for every key: fine, it rides along as a constant in the query. A **per-key row limit** — "the five most recent transactions for each of these accounts" — is not fine, because a flat set-membership predicate has no way to say *five per account*. Neither is a per-key sort order or a per-key free-text filter. When the keys cannot be merged, the batch function has only one honest move left: loop over the keys and issue one call each. The trace then shows a loader that batched perfectly and a database that was asked eighty-seven separate questions. ## A quick check you can apply in an interview Before writing the loader, say the key out loud as a sentence, then write the single backend call that answers a list of them. * "The balance of account `A-4471` as of `2026-03-31`" — sentence is complete, and a list of them is one lookup over pairs. Good key. * "The statements of account `A-4471`" — incomplete; the field takes a period. * "The five most recent transactions of account `A-4471`" — complete, but a list of them is not one flat lookup. The key is honest and the *lookup* is the problem, which is a different fix. A four-person platform team can carry that check in their heads during review, which is roughly the point: bad keys do not announce themselves in tests, because a test with one account in the fixture batches one key and looks perfect.