Nested Fetch Amplification

## Execution is defined per object, not per document GraphQL's execution algorithm is specified in terms of a pair: a selection set and a single source object. For every field in that selection set the executor invokes the field's resolver with that object as the parent, then *completes* the returned value against the field's declared type. When the declared type is a list, completion walks the list and, for each item that is itself an object, runs the field's sub-selection set against that one item. There is no step anywhere in that algorithm where the executor gathers all the items of a list and hands them to a child field's resolver together. The child resolver's contract is one parent in, one value out. That is not a quirk of any particular server — it is what the specification describes, and every conforming implementation behaves this way. ## The arithmetic that falls out Take a course-enrolment graph. A client asks a term for its courses and, for each course, the instructor: ```graphql query TermRoster { term(code: "2026-FALL") { courses(first: 47) { title instructor { displayName } } } } ``` If `instructor` is a foreign key on the course row and its resolver looks the instructor up by id, the executor invokes that resolver 47 times — once per course — and each invocation issues its own lookup. Add the single call that fetched the 47 courses and the request costs 48 backend calls. `title`, by contrast, costs nothing: it is read directly off the course object the list resolver already returned, which is what the specification's default resolution does when a field has no explicit resolver. So the multiplier is not "how many fields the document mentions". It is: **for each field whose resolver reaches a backend, how many parent objects that field is resolved against**. A document with twenty scalar fields on one object costs one call. A document with one object-valued field over a list of 200 costs 201. ## Why the count is set by the caller, not the schema The number of parents is a runtime property. It comes from the page size the caller passed (`first: 47`), or from however many rows an unbounded list happened to return that day. The same stored document therefore costs a different amount on every execution. This is the single most important consequence for anyone operating a GraphQL endpoint: the schema author fixes the *shape* of the cost, the caller fixes the *scale* of it, and the server discovers the total only while it is executing. It is also why the failure mode is invisible in a smoke test. With one course in the fixture the request makes two calls instead of one; nobody notices a doubling. With a realistic page it makes forty-eight, and the latency is roughly the list call plus N times the per-child call. ## Concurrency does not remove the calls A common half-answer is that the executor runs the sibling resolvers in parallel, so the fan-out does not matter. The specification does permit fields in the same selection set to be executed in any order and, for query operations, concurrently. That changes the *wall-clock shape* — 47 lookups may overlap rather than queue — but it does not change the *count*. Forty-seven concurrent lookups still occupy forty-seven connections from a pool that probably holds eight, so in practice they serialise on the pool anyway, and a bursty fan-out is often harder on a shared data store than the same work spread out. The number of round trips is the thing to reason about; concurrency only decides how they are packed in time. ## What is spec and what is convention Worth separating cleanly, because interviewers probe it: - **Specified**: per-object resolution, per-item execution of a list's sub-selection, default resolution reading a property of the parent, permission to execute sibling fields concurrently. - **Convention**: everything that fixes the amplification. Coalescing the N child lookups into one bulk lookup per tick — the pattern named DataLoader — is an implementation practice with no standing in the specification. So is prefetching children while resolving the parent, and so is reading the incoming selection set to decide what to fetch up front. Saying "GraphQL batches this for you" is simply wrong, and it is the answer that ends a screening call. Nothing batches unless the server was written to batch. ## Recognising it in the wild Three symptoms travel together. Latency scales with the requested page size rather than with document length. The data store's statement log shows the same statement text repeated within one request with only the bound id changing. And adding one innocuous-looking field to an existing client document multiplies backend load, because that field is resolved once per row of a list that is already there.