Why can a single GraphQL query exhaust your server?
In a REST API, the server decides the shape of each response. An endpoint like /users/42/friends returns a bounded payload, and its cost is roughly the same every time. GraphQL gives that decision to the client. The client chooses how deep to nest and how many items each list returns. It can also request the same field many times under different aliases, and it can reuse fragments so that a short query document expands into a large selection set. Every one of those choices turns into resolver calls on your server.
Take a friends-of-friends query. It starts at user(id: 42), selects friends(first: 50), and inside each friend selects friends(first: 50) again, nested three levels deep, ending at name. Trace the resolver work (illustrative estimate, assuming every user has at least 50 friends):
- Level 1: 1 user resolves to 50 friends.
- Level 2: each of those 50 resolves 50 more, giving 2,500.
- Level 3: each of those 2,500 resolves 50 more, giving 125,000.
The query text is only a few lines long, but it triggers more than 127,000 list resolutions. Repeat the outer selection under five aliases and the total rises past 600,000. Batching reduces the number of database round trips, but the server still has to fetch, hold and serialize every one of those objects.
A GraphQL query complexity limit is a bound on the work a single request may cause. The server estimates that work from the parsed query and checks it against the bound before execution, so an expensive request is rejected before any resolver runs.
Any public, partner-facing or multi-tenant GraphQL API needs one. Backend and platform engineers who own that API's availability are the ones who should set the limit.
# Friends-of-friends: a few lines of query text, a large amount of resolver work.
# Counts are an illustrative estimate, assuming every user has at least 50 friends.
query FriendsOfFriends {
user(id: 42) { # 1 user
friends(first: 50) { # level 1: 1 x 50 = 50 users
friends(first: 50) { # level 2: 50 x 50 = 2,500 users
friends(first: 50) { # level 3: 2,500 x 50 = 125,000 users
name
}
}
}
}
}
# Total: 50 + 2,500 + 125,000 = 127,550 user objects to fetch, hold and serialize.
# The same work, multiplied with a fragment and aliases.
# The fragment is written once but expands at every alias that spreads it.
fragment Fan on User {
friends(first: 50) {
friends(first: 50) {
friends(first: 50) {
name
}
}
}
}
query AliasedFanOut {
a: user(id: 42) { ...Fan } # 127,550
b: user(id: 42) { ...Fan } # 127,550
c: user(id: 42) { ...Fan } # 127,550
d: user(id: 42) { ...Fan } # 127,550
e: user(id: 42) { ...Fan } # 127,550
}
# Total: 5 x 127,550 = 637,750 user objects from one short request.
# A complexity limit computes a cost like this from the parsed document
# and rejects the request before any resolver runs.
A three-level friends-of-friends query, followed by a version that reuses one fragment under five aliases. The comments trace how list sizes multiply at each level until a short query document reaches more than 600,000 resolved objects (illustrative estimate).
Is query depth limiting enough to stop expensive queries?
A depth limit is the easiest place to start. After parsing and before execution, a validation rule walks the query's abstract syntax tree from each operation's root selection set and counts how many levels of nested fields it passes through. If any path goes deeper than the configured maximum, the request is rejected and no resolver runs.
Fragments affect the count. An inline fragment (... on User) only narrows the type, so the walker descends into its selections without adding a level. A named fragment spread is looked up by name in the document, and its selections are counted as if they were written at the point of the spread. A spread placed four levels deep therefore contributes from depth four.
The GraphQL specification forbids fragment cycles, and standard validation rejects a document in which fragment A spreads B and B spreads A. A depth walker should still keep its own set of fragments it is currently expanding. If the walker runs before or apart from the standard rules and finds a cycle, it must stop instead of recursing until the stack overflows.
The weakness is that depth measures only one dimension of a query:
- Wide queries: A query only three levels deep can request dozens of sibling fields, and each one may call a separate backend.
- Aliases: Aliases let a client request the same expensive field hundreds of times at the same depth. Each alias resolves independently.
- Pagination arguments:
first: 10000on two nested connections can produce millions of resolved nodes at depth two.
Each of these passes a depth check and can still exhaust the server. Depth limiting is cheap to add, but it gives false confidence if it is the only control. Keep it as a backstop and use cost analysis as the main defense.
import { parse, Kind, SelectionSetNode, FragmentDefinitionNode } from "graphql";
type Frags = Map<string, FragmentDefinitionNode>;
// Returns the deepest field level reachable from this selection set.
function depthOf(set: SelectionSetNode, frags: Frags, depth: number, expanding: Set<string>): number {
let max = depth;
for (const sel of set.selections) {
if (sel.kind === Kind.FIELD) {
// Only fields add a level, whether or not they have sub-selections.
const d = depth + 1;
max = Math.max(max, sel.selectionSet ? depthOf(sel.selectionSet, frags, d, expanding) : d);
} else if (sel.kind === Kind.INLINE_FRAGMENT) {
// `... on User` narrows the type. It does not add a level.
max = Math.max(max, depthOf(sel.selectionSet, frags, depth, expanding));
} else {
// Named spread: count the fragment's fields as if written here.
const name = sel.name.value;
if (expanding.has(name)) throw new Error(`Fragment cycle through "${name}"`);
const frag = frags.get(name);
if (!frag) throw new Error(`Unknown fragment "${name}"`);
expanding.add(name);
max = Math.max(max, depthOf(frag.selectionSet, frags, depth, expanding));
expanding.delete(name);
}
}
return max;
}
export function queryDepth(source: string): number {
const doc = parse(source);
const frags: Frags = new Map();
for (const def of doc.definitions) if (def.kind === Kind.FRAGMENT_DEFINITION) frags.set(def.name.value, def);
let max = 0;
for (const def of doc.definitions)
if (def.kind === Kind.OPERATION_DEFINITION) max = Math.max(max, depthOf(def.selectionSet, frags, 0, new Set()));
return max;
}
// Depth 3, so it passes a limit of 5. It can still request up to 10000 x 10000 nodes,
// and each alias of `search` resolves independently.
console.log(queryDepth(`{ users(first: 10000) { friends(first: 10000) { name } }
s1: search(term: "a") { id } s2: search(term: "a") { id } s3: search(term: "a") { id } }`));
A graphql-js depth walker that expands inline and named fragments, rejects cyclic or unknown fragment spreads, and reports depth 3 for a query that uses large pagination arguments and repeated aliases, so that query passes a depth limit of 5.
How does GraphQL cost analysis work?
Static cost analysis scores the parsed query document before any resolver runs. Each field gets a cost, and each list field multiplies the cost of its selection by the expected number of items, usually read from a first or limit argument. The scores are summed over the whole document, including fragments. If the total exceeds the limit, the server rejects the query without touching the database.
The rule is: cost(field) = own_cost + multiplier × sum(cost(children)). For a non-list field, the multiplier is 1.
Illustrative estimate (assumed numbers, not a benchmark). Take user { friends(first: 50) { friends(first: 50) { name } } } and assume objects cost 1 and scalars cost 0:
- Inner
friends: 1 + 50 × 0 = 1 per item - Outer
friends: 1 + 50 × (1 + 50 × 1) = 2,551 user: 1 + 2,551 = 2,552
Raising both page sizes to 100 gives roughly 10,000. Depth stays the same, but the cost grows with the square of the page size.
| Where costs live | Strength | Weakness |
|---|---|---|
| Schema directives | Cost sits next to the field definition | Adds noise to the SDL; needs directive support |
| Separate cost map | No schema changes | Drifts out of sync with the schema |
| Default rules | Zero setup | Every field costs the same |
For list fields with no size argument, you need an assumed default size. That default is a trade-off: set it too low and attacks pass, set it too high and legitimate queries are rejected. Requiring pagination arguments is the cleaner fix.
The score is only an estimate. Search, filters, and computed fields can cost far more than their annotation suggests. The annotations also need maintenance every time the schema changes.
import { parse, Kind, FieldNode, SelectionSetNode, OperationDefinitionNode } from "graphql";
const SCALAR_COST = 1, OBJECT_COST = 1, MAX_COST = 1000;
const DEFAULT_LIST_SIZE = 20; // guess for lists with no first/limit
const UNBOUNDED_LISTS = new Set(["tags"]); // list fields that take no size argument
const COST_MAP: Record<string, number> = { search: 50 }; // separate cost map, keyed by field name
// Multiplier comes from first/limit. Unbounded lists fall back to the default size.
function listSize(f: FieldNode, vars: Record<string, unknown>): number {
const arg = f.arguments?.find(a => a.name.value === "first" || a.name.value === "limit");
if (arg?.value.kind === Kind.INT) return Number(arg.value.value);
if (arg?.value.kind === Kind.VARIABLE) return Number(vars[arg.value.name.value] ?? DEFAULT_LIST_SIZE);
return UNBOUNDED_LISTS.has(f.name.value) ? DEFAULT_LIST_SIZE : 1; // 1 means a non-list field
}
// cost(field) = own_cost + multiplier * sum(cost(children))
function cost(set: SelectionSetNode, vars: Record<string, unknown>): number {
let total = 0;
for (const sel of set.selections) {
if (sel.kind === Kind.INLINE_FRAGMENT) { total += cost(sel.selectionSet, vars); continue; }
if (sel.kind !== Kind.FIELD) continue; // named fragment spreads omitted for brevity
const own = COST_MAP[sel.name.value] ?? (sel.selectionSet ? OBJECT_COST : SCALAR_COST);
total += sel.selectionSet ? own + listSize(sel, vars) * cost(sel.selectionSet, vars) : own;
}
return total;
}
const doc = parse("{ user { friends(first: 50) { friends(first: 50) { name } } } }");
const op = doc.definitions.find(
(d): d is OperationDefinitionNode => d.kind === Kind.OPERATION_DEFINITION)!;
const score = cost(op.selectionSet, {});
// Reject before any resolver or database call runs.
console.log(score, score > MAX_COST ? "rejected" : "accepted"); // 2552 rejected
A minimal static cost calculator built on graphql-js's parser. It multiplies child costs by first/limit, falls back to a default size for unbounded lists, and reproduces the illustrative 2,552 score for the friends-of-friends query when objects and scalars each cost 1.
How do you implement a query complexity limit before execution?
Order matters here, because each step protects the one after it.
1. Cap the raw document first. Reject request bodies above a fixed byte size before parsing, then limit the token count during parsing. A parser and a cost walker both do work proportional to input size. Without these caps, a multi-megabyte query can exhaust CPU during analysis, before any resolver runs.
2. Parse, validate, score, compare. After parsing, run the standard validation rules, then a cost rule that walks the document and sums field costs multiplied by list arguments. Compare the total with the request's budget. In graphql-js terms, this is a validation rule passed to validate() alongside the defaults. Because it runs before execute(), a rejected query never reaches a resolver or the database.
3. Make pagination arguments mandatory. A multiplier is only meaningful if the server enforces it. Require first or limit on every list field, and set a maximum page size. You can reject missing or oversized values, or clamp them to the maximum. Rejecting is more explicit. Clamping is friendlier but can silently change results. Either way, the estimate now bounds real work.
4. Add cheap supplementary checks. Count aliases, root fields, and total field nodes. These catch wide, flat queries that per-field costs underweight. Disable introspection and request batching where clients don't need them.
5. Return a useful error. Include the computed cost and the limit so developers can fix their queries. The same numbers also let an attacker tune a query to sit just under the limit. For public endpoints, consider returning the details only to authenticated or internal clients.
import { parse, validate, specifiedRules, GraphQLError, getNullableType, isListType, Kind } from 'graphql';
const MAX_BYTES = 10_000, MAX_TOKENS = 2_000, MAX_COST = 1_000, MAX_PAGE = 100;
// Validation rule: cost = sum over fields of (product of enclosing page sizes).
// Simplification: fragment spreads are not expanded here; production code must inline them.
function costRule(variables) {
return (context) => {
const stack = [1]; // multiplier inherited from enclosing list fields
let total = 0;
return {
Field: {
enter(node) {
const def = context.getFieldDef();
let mult = 1;
if (def && isListType(getNullableType(def.type))) {
const arg = node.arguments?.find((a) => a.name.value === 'first');
const v = !arg ? undefined
: arg.value.kind === Kind.VARIABLE ? variables?.[arg.value.name.value]
: arg.value.kind === Kind.INT ? Number(arg.value.value) : undefined;
// Enforce pagination so the multiplier bounds real work (reject, not clamp).
if (typeof v !== 'number' || v < 0 || v > MAX_PAGE) {
context.reportError(new GraphQLError(`"${node.name.value}" requires first <= ${MAX_PAGE}`, { nodes: [node] }));
}
mult = typeof v === 'number' ? Math.min(Math.max(v, 0), MAX_PAGE) : MAX_PAGE;
}
total += stack[stack.length - 1];
stack.push(stack[stack.length - 1] * mult);
},
leave() { stack.pop(); },
},
Document: { leave() {
// Reporting cost and limit helps developers; consider hiding numbers from anonymous clients.
if (total > MAX_COST) context.reportError(new GraphQLError(`Query cost ${total} exceeds limit ${MAX_COST}`));
} },
};
};
}
export function checkQuery(schema, body, variables) {
if (Buffer.byteLength(body, 'utf8') > MAX_BYTES) return [new GraphQLError('Query document too large')];
const doc = parse(body, { maxTokens: MAX_TOKENS }); // throws a GraphQLError if the token cap is hit
return validate(schema, doc, [...specifiedRules, costRule(variables)]); // runs before execute()
}
A graphql-js sketch that caps bytes and tokens before analysis, then runs a cost validation rule alongside the default rules. The rule multiplies field costs by enforced first page sizes and rejects the query before any resolver runs.
When should you enforce per-client cost budgets, and when should you avoid strict limits?
A per-query limit stops one expensive request. It does nothing against a client sending thousands of cheap ones. Per-client budgets close that gap. Each client gets a pool of cost points that refills at a fixed rate, and each query's computed cost is deducted before execution. When the pool is empty, requests are rejected until it refills.
Illustrative estimate (assumed numbers, not a benchmark): sustained queries per minute = refill rate ÷ average query cost. With a refill rate of 1,000 points/minute and an average cost of 25, a client sustains 1,000 ÷ 25 = 40 queries/minute. A burst capacity of 5,000 points allows 200 such queries at once before throttling.
Budgets need shared state across instances, such as a central store keyed by client. If each replica keeps its own counter, a client effectively gets its budget multiplied by the replica count. Budgets also need a reliable client identity, such as an API key or an authenticated token. Anonymous traffic is hard to budget fairly. Many users can share one IP behind NAT, and attackers rotate IPs, so an anonymous budget ends up either too generous or punishing for legitimate users.
Relax or skip strict limits in three cases:
- Internal-only APIs with known callers.
- Introspection queries from IDEs and schema tooling.
- Existing clients whose queries already exceed a new ceiling.
Changing a limit is effectively an API contract change, because queries that worked yesterday fail today. Announce the change, publish the numbers, and give clients a migration window.
Budgets and per-field cost annotations also need maintenance as the schema grows. That work pays off if expensive queries have already caused incidents. For a small internal API, a depth limit may be enough.
What are the alternatives to query cost analysis?
Cost analysis is one of four common defenses, and each one constrains a different thing: the set of allowed queries, the shape of a query, its estimated work, or the number of requests.
| Approach | What it limits | Blocks expensive nested queries? | Main cost to you |
|---|---|---|---|
| Persisted / allowlisted queries | Which query documents can run | Yes, unknown queries are rejected | Build-pipeline step, no ad-hoc queries |
| Depth limits only | Nesting levels | Partially, wide shallow queries pass | Very little |
| Cost analysis | Estimated work per query | Yes, if estimates are accurate | Keeping field costs current |
| Plain rate limiting | Requests per client per window | No, one heavy request still counts as one | Very little |
Persisted queries are the strongest option for first-party clients. The build step extracts each query, registers it by hash, and the server runs only registered hashes. An attacker cannot submit an arbitrary nested query because arbitrary queries are no longer part of the API surface. The trade-off is flexibility. Third-party developers lose ad-hoc querying. Every client release also has to register its queries before deploying, or production requests will fail.
The two approaches combine well. Your web and mobile apps send registered hashes, which bypass cost checks entirely. Any request carrying a raw query document, such as one from a partner integration or a public API consumer, goes through cost analysis and per-client budgets. This split also saves engineering time. You know exactly what each allowlisted query does, so you do not need to keep cost estimates accurate for them. Your cost-tuning effort can go to the open part of the API, where estimates actually decide what runs.
How do you roll out complexity limits safely and back them up at runtime?
Start in log-only mode. Compute the cost of every incoming query and record it, but don't reject anything yet. After a week or two of real traffic, you have a cost distribution per operation and per client. That shows where legitimate peaks sit, which is better than guessing at a threshold.
Set the limit above the highest legitimate cost you observed, with headroom for normal growth such as larger pages or new fields.
Illustrative estimate (assumed numbers, not a benchmark): limit = observed p99.9 cost × headroom factor. With an assumed p99.9 of 800 and a factor of 1.5, the limit is 1,200.
Then switch to enforcement. Emit rejections as a metric tagged by client and operation, and alert on sudden increases. A spike right after a deploy usually means a cost weight is wrong. It can also mean a client shipped a new query. Either way, investigate it before it turns into a support ticket.
The static estimate will sometimes be wrong. A field you weighted at 1 might hit a slow index. Back the limit up at runtime with several layers:
- Resolver timeouts. A single slow data source fails fast instead of holding a worker.
- A per-request execution deadline. This caps total wall-clock time no matter how many resolvers run.
- DataLoader-style batching. It collapses N+1 lookups, so the real cost tracks the estimate more closely.
- Proxy limits. Cap request body size and connection and concurrency counts, so oversized or flooding traffic never reaches the GraphQL layer.
Checklist
- Depth limit
- Cost analysis with an enforced complexity limit
- Per-client budgets where appropriate
- Persisted queries or allowlists for first-party clients
- Rejection metrics and alerts
- Resolver timeouts and a request deadline
- Batching
- Proxy-level size and concurrency caps
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to graphql query complexity limit, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Consumers learn about a breaking change at review time rather than from production errors.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.