How do you count the backend calls a GraphQL document makes when list fields nest?

## The counting rule There is one rule, applied level by level from the root: > **calls at a level = (number of parent objects at that level) × (fields at that level whose resolver reaches a backend)** and > **number of parent objects at a level = the product of the list sizes on the path above it** That second line is the whole story of nested amplification. Levels do not add, they multiply, because the executor runs a sub-selection against every item of every list on the way down. ## A worked example ```graphql query TermRoster { term(code: "2026-FALL") { # 1 object courses(first: 47) { # 47 objects title instructor { displayName } # resolved per course enrolments(first: 12) { # 12 per course => 564 objects grade student { displayName } # resolved per enrolment } } } } ``` Tally it: | Level | Parent objects | Backend-resolved fields | Calls | |---|---|---|---| | root | 1 | `term` | 1 | | term | 1 | `courses` | 1 | | course | 47 | `instructor` | 47 | | course | 47 | `enrolments` | 47 | | enrolment | 564 | `student` | 564 | Total: **660 backend calls for one document**. `title` and `grade` contribute nothing — they are read off objects already in memory by default resolution. Notice how little of the document is responsible. Two nested list fields and two object-valued fields produced 660 round trips, and 564 of them — 85% — came from a single innocuous line, `student { displayName }`, sitting two levels down. ## Why depth is the dangerous axis Adding a sibling field at a level you are already at is additive: a second backend-resolved field on the course adds 47 calls. Adding a *level* is multiplicative: it takes the parent count you already had and multiplies it by the new list's size. That asymmetry is why reviewers who count fields miss the problem entirely. The number to watch is the running product of list sizes, not the line count. It also means the last level dominates. In the tally above, everything above the enrolment level accounts for 96 calls and the bottom level accounts for 564. Optimising the top of a document is almost always the wrong end. ## The caller sets the scale, the schema sets the ceiling Each of those list sizes came from an argument the caller chose. The same document with `courses(first: 3)` and `enrolments(first: 2)` costs 1 + 1 + 3 + 3 + 6 = 14 calls. Nothing about the server changed; the multiplier did. The worst case a schema permits is therefore the product of the maximum page size each list field allows, multiplied along the deepest chain of list fields the schema can express. Two things follow: - A list field with **no** page-size cap makes the ceiling unbounded, and one uncapped field anywhere in the chain is enough to do it — the product has an unbounded factor in it. - Caps compose badly. A cap of 100 at each of three levels reads as reasonable per field and permits a million leaf objects. Sensible per-field limits are not sensible in composition, which is why the caps that matter are usually chosen by looking at the product along real client documents rather than field by field. (Turning that ceiling into an enforced pre-execution budget is an abuse-control concern with its own machinery; the counting here is what tells you whether such a control is needed and where the product blows up.) ## Recursion and cycles GraphQL type graphs are usually cyclic — a course reaches its enrolments, an enrolment reaches its student, a student reaches their enrolments again. A document may walk that cycle repeatedly, and each traversal is another multiplicative level. This is how a document that looks short on the page can express a product of five or six list sizes. ## Doing the count in practice You rarely count by hand for long. Two habits do it better: 1. **Instrument per field.** Have the server tally resolver invocations keyed by the field's path in the document, then print the tally for one request. The 564 will be sitting there on the `student` row, and the ratio between a row and its parent's row is exactly the fan-out at that level. 2. **Reason on the response.** The number of objects at a level in the response body is the parent count for the level beneath it. If the response contains 564 enrolment objects, any backend-resolved field on the enrolment cost 564 calls — no tracing needed to know that. And the arithmetic explains a class of surprises that otherwise looks random: a client adds one field, the document's text grows by three words, and backend load multiplies. That is not a mystery. It is the product of the list sizes above the field they added.