Why can a shallow GraphQL document still be expensive enough to need a cost limit?

## Shape is not volume A GraphQL document is a description of the response a client wants, and two properties of that description are easy to confuse. Its **shape** is how many levels of selection it nests and how many fields it names. That is a property of the text, and it is what a nesting cap or a field-count cap measures. Its **volume** is how many objects the server must produce in order to answer it. That is a property of the *data behind* the text, and nothing in the text's size tells you about it. A control that reads only the shape can happily admit a document that asks for the entire database, because the expensive thing about a GraphQL document is almost never how far down it goes. It is multiplication. ## Where the multiplication comes from A field that returns a list is normally given a slice argument — `first`, `last`, `limit` — saying how many items the client wants. Those names are convention: `first`/`last` come from the Relay server specification's connection convention, and the GraphQL specification itself defines no pagination argument and no cost model at all. Whatever the client selects *underneath* a list field is produced once per item in that slice. Nest a second list field inside the first, and its slice multiplies. Nest a third, and you have a product of three factors. ## A worked case Take a solar-array telemetry graph: sites own inverters, and inverters emit power readings. ```graphql query { sites(first: 213) { inverters(first: 184) { readings(first: 466) { wattage capturedAt } } } } ``` Four levels of selection, five named fields, forty-odd characters per line. A nesting cap of six waves it through without comment. The server, meanwhile, is being asked for 213 sites, 213 × 184 = 39,192 inverters, and 39,192 × 466 = 18,263,472 readings, each carrying two scalars — roughly 36.5 million leaf values. Change one digit, `466` to `999`, and the document is the same length while the work more than doubles. This is why "the document looked small" is never a defence. The client controls the multipliers, and a text-length or shape check cannot see them. ## Why the layers below do not save you Three tempting answers fail here. *The response will be huge, so something downstream will kill it.* By the time the response is huge the work is already done: rows read, objects allocated, the request thread or event loop occupied. An abuse control that triggers after the cost has been paid is not a control. *The database will refuse an unreasonable query.* The database is not asked one unreasonable query. It is asked 39,192 reasonable ones — each individually fast, collectively an outage. Nothing at that layer sees the aggregate. *Rate limiting by requests per minute will bound it.* A limit of sixty requests per minute is meaningless when a single request can be worth millions of object fetches. Requests are not a unit of work on a GraphQL endpoint; that is precisely the property that makes one endpoint with one HTTP verb harder to police than a hundred REST routes with fixed response shapes. ## What a cost score adds Complexity scoring replaces "how big is the text" with "how much work does this text authorise". The mechanism is deliberately crude and entirely static: 1. Every field in the schema is given a **weight** — usually 1 by default, higher for fields backed by an expensive call. 2. A list field's subtree cost is **multiplied** by the slice its arguments request. 3. The document's total is compared to a **budget**. Over budget, the server answers with an error and executes nothing. For a public endpoint, the value of this is that the rejection is cheap. Parsing and scoring a document costs microseconds; executing it costs an outage. And because scoring happens before any resolver runs, there is no half-served response, no orphaned backend work, and no partially charged downstream. ## What the score is and is not The number is an **upper bound**, computed from the document and its variables alone. It says: *no matter what the data looks like, this document cannot ask for more than this.* It is not a latency prediction and not a measurement — a document scored at 400,000 may return in 20 ms because a cache was warm, and a document scored at 900 may be slow because one field is a slow external call whose weight was set too low. That gap between authorised work and actual work is the source of both the control's strength (it is decidable before execution) and its main operational annoyance (it can refuse documents that would have been cheap). Two other things it is not: it is not authorization — a cheap document can still ask for data the caller may not see — and it is not part of the GraphQL specification. Every weight, every multiplier convention and every budget in this area is server configuration and local policy.