Why can a single GraphQL request exhaust your backend?
A REST endpoint usually does a bounded amount of work per call. A GraphQL endpoint does whatever the query describes, and the client writes the query. One HTTP request can ask for a list of users, each user's posts, each post's comments, and each comment's author. The work multiplies at every level.
Consider an illustrative estimate with assumed inputs. A query requests 50 users, 50 posts per user, and 50 comments per post. That is 125,000 comment objects from a single request. If each comment's author is resolved without batching, the downstream calls grow by the same amount. Aliases make it worse: a client can request the same expensive field ten times under different names in one operation. Fragments let a short query body expand into a much larger selection set once the server resolves it.
Request-rate limiting cannot catch this. A limit of 100 requests per minute treats a cheap profile lookup and the 125,000-object query as equal, even though their costs differ by orders of magnitude.
Query cost analysis solves this by estimating the work a query will cause from its structure before any resolver runs. The server then rejects queries that exceed a budget.
This matters most for:
- Teams running public or partner-facing Apollo Server APIs, where clients are untrusted.
- Platform teams that own shared gateways, where one consumer's query can degrade service for everyone else.
- Schemas with many list fields, or resolvers backed by expensive databases, search clusters, or metered third-party services.
fragment PostTree on Post {
title
comments(first: 50) { # x50 per post
body
author { name } # one lookup per comment unless batched
}
}
query FanOut {
# Aliases request the same expensive field under different names.
# Each alias is resolved separately, so the work is repeated.
a: users(first: 50) { # 50 users
posts(first: 50) { # x50 = 2,500 posts
...PostTree # x50 = 125,000 comments
}
}
b: users(first: 50) {
posts(first: 50) { ...PostTree } # another 125,000
}
c: users(first: 50) {
posts(first: 50) { ...PostTree } # another 125,000
}
}
A short GraphQL operation that uses nested lists, a fragment and aliases to request about 375,000 comment objects in one request (illustrative estimate assuming 50 items per list), while a request-rate limiter counts it as one call.
How does a query complexity limit work?
A complexity limit is a check on the query document, not on the data. It runs in the gap between receiving a request and executing it, and it has four steps:
- Parse. Apollo Server turns the query string into an abstract syntax tree (AST). Every field, alias, argument, fragment and inline fragment becomes a node.
- Walk the tree. The analyzer visits each selected field and expands fragment spreads in place, so a fragment counts wherever it is used. Each alias is visited separately, because each one is resolved separately.
- Score. Each field gets a cost from rules you define. A depth check measures how deeply selections nest. A cost model assigns a weight per field and multiplies a list field's child cost by its page size, which it reads from arguments such as
first. Variables must be substituted first so the page sizes are real numbers. - Compare and decide. If the depth or total cost exceeds the configured limit, the server returns a GraphQL error and never calls a resolver. Otherwise the operation executes normally.
Because the check only reads the AST and schema, it does not touch databases or downstream services. Its cost grows with the size of the query document, which is why you also bound the document size, as described later. The rest of this article covers each step in Apollo Server: depth rules during validation, cost weights in the schema, and the cost check in a plugin hook once variables are known.
How does depth limiting work in Apollo Server, and why is it not enough?
Apollo Server accepts custom validation rules through its validationRules option, and depth limiting is usually implemented as one of them. GraphQL validation runs after parsing and before any resolver is called. A depth rule walks the operation's AST, tracks how many selection sets deep each field sits, and reports a validation error if any path exceeds the configured maximum. The resolvers never run, so the rejection costs almost nothing.
Most implementations resolve fragment spreads during the walk. A fragment's fields count at the depth where the fragment is spread, not at depth zero, so a client cannot hide nesting inside named fragments. Introspection fields such as __schema and __type need deliberate handling. The standard introspection query nests ofType several levels deep and can trip a strict limit. Teams typically either exempt introspection fields from the count or disable introspection in production.
To choose a limit, measure the deepest legitimate operation your clients send, using persisted queries or request logs, and add one or two levels of headroom. Don't pick a round number.
Depth only measures nesting. It ignores how many objects the server fetches at each level. Assume a limit of 5:
| Query shape | Depth | Objects potentially resolved (illustrative estimate) | Passes limit of 5? |
|---|---|---|---|
50 aliases of users(first: 1000) { posts(first: 100) { id } } |
3 | 50 × 1,000 × 100 = 5,000,000 | Yes |
viewer { profile { settings { notifications { email { enabled } } } } } |
6 | 5 single objects, likely from one or two rows | No |
The rule accepts the query that could resolve millions of objects and rejects the one that reads a handful of rows. Depth limiting is still worth keeping as a cheap first check. Bounding actual work requires a cost model that accounts for list sizes and aliases.
import { ApolloServer } from '@apollo/server';
import { GraphQLError, Kind } from 'graphql';
import type { ASTVisitor, SelectionSetNode, ValidationContext } from 'graphql';
import { typeDefs, resolvers } from './schema';
// Deepest legitimate operation seen in logs was 5; allow 2 levels of headroom.
const MAX_DEPTH = 7;
// Top-level fields are depth 1; each nested selection set adds 1.
function maxDepth(ctx: ValidationContext, set: SelectionSetNode, depth: number, seen: Set<string>): number {
let max = 0;
for (const sel of set.selections) {
if (sel.kind === Kind.FIELD) {
if (sel.name.value.startsWith('__')) continue; // exempt __schema, __type, __typename
max = Math.max(max, sel.selectionSet ? maxDepth(ctx, sel.selectionSet, depth + 1, seen) : depth);
} else if (sel.kind === Kind.INLINE_FRAGMENT) {
max = Math.max(max, maxDepth(ctx, sel.selectionSet, depth, seen)); // no extra level
} else {
// Fragment spread: count its fields at the depth where it is spread.
const frag = ctx.getFragment(sel.name.value);
if (frag && !seen.has(frag.name.value)) {
max = Math.max(max, maxDepth(ctx, frag.selectionSet, depth, new Set(seen).add(frag.name.value)));
}
}
}
return max;
}
// Runs during validation: after parsing, before any resolver executes.
const depthLimit = (ctx: ValidationContext): ASTVisitor => ({
OperationDefinition(node) {
const depth = maxDepth(ctx, node.selectionSet, 1, new Set());
if (depth > MAX_DEPTH) {
ctx.reportError(new GraphQLError(`Query depth ${depth} exceeds limit of ${MAX_DEPTH}`, { nodes: [node] }));
}
},
});
export const server = new ApolloServer({ typeDefs, resolvers, validationRules: [depthLimit] });
A custom depth-limiting validation rule for Apollo Server that walks the AST before execution, counts fragment fields at their spread depth, and exempts introspection fields.
How do you design a query cost model that reflects real resolver work?
A cost model should reflect how many objects each field can return and how expensive each resolver actually is. A useful model has three parts.
Base cost per field. Give every object-returning field a weight of 1 and scalars a weight of 0. Scalars are usually read from an already-loaded parent, so counting them mostly adds noise.
List multipliers. A list field's cost is its own weight plus the cost of its child selection multiplied by the page size. Read the page size from first or limit. If a client omits the argument, use the server's maximum page size rather than the default. Otherwise a client can skip the argument and get a list that your model prices as small.
Resolver-aware weights. Raise the weight of fields that call a slow downstream service, bypass a cache, or run an unindexed query. A field that triggers a network call per parent deserves a weight in the tens, not 1.
Declare these weights in the schema with a custom directive you define, such as @cost(weight: 10). When a weight sits next to the field definition, anyone changing a resolver's data source sees the cost in the same diff. Code review then catches stale weights.
Illustrative estimate (assumed numbers, not a benchmark). The formula is cost = w + n × c_child. Assume users(first: 50) selects name, posts(first: 20) { title }, and recommendations(first: 5) { id }, where recommendations has weight 10.
- Posts per user: 1 + 20 × 1 = 21.
- Recommendations per user: 10 + 5 × 1 = 15.
- Per user: 1 + 21 + 15 = 37.
- Total: 1 + 50 × 37 = 1,851.
// Schema-level cost weights live next to the fields they describe,
// so a change to a resolver's data source and its weight share one diff.
export const typeDefs = `#graphql
# Custom directive we define. The cost evaluator reads it from the schema.
# Fields without @cost use the defaults: objects = 1, scalars = 0.
directive @cost(weight: Int!) on FIELD_DEFINITION
type Query {
# List field. The evaluator multiplies child cost by \`first\`.
# If \`first\` is omitted, it uses the server max page size (100),
# not a small default, so leaving out the argument can't shrink the price.
users(first: Int): [User!]! @cost(weight: 1)
}
type User {
id: ID!
name: String! # scalar from the loaded parent, weight 0
# Indexed, batched lookup, so it keeps the base weight.
posts(first: Int): [Post!]! @cost(weight: 1)
# One call to a slow, uncached recommendation service per parent user.
# The higher weight reflects that, not the size of the response.
recommendations(first: Int): [Recommendation!]! @cost(weight: 10)
}
type Post {
id: ID!
title: String!
}
type Recommendation {
id: ID!
}
`;
// Illustrative estimate for the sample query in this section,
// counting each returned list item as 1, as the worked example does:
// posts per user = 1 + 20 * 1 = 21
// recommendations per user = 10 + 5 * 1 = 15
// per user = 1 + 21 + 15 = 37
// total = 1 + 50 * 37 = 1851
An Apollo Server typeDefs string that defines a custom @cost directive and puts per-field weights next to the fields, with a higher weight on the field backed by a slow service, plus comments that work through the illustrative 1,851-point calculation.
How do you enforce a GraphQL query complexity limit before execution?
Those numbers only exist once first: 20 and first: 5 are known. In practice clients pass them as variables (first: $n), so a cost check that runs as a plain validation rule sees an unresolved variable and either guesses or skips the field. Run the check where both the parsed document and the coerced variable values are available. In Apollo Server, the natural place is a plugin's didResolveOperation hook. It fires after parsing, validation, and operation selection, and before any resolver runs.
Request -> [Body size / token limit] -> Parse -> Validate (depth, schema)
-> Resolve operation + variables -> Cost check -> Execute
-> [Runtime limits: timeouts, DataLoader batching, per-resolver caps]
When the computed cost exceeds the budget, throw a GraphQLError with a stable extension code. Include both the computed cost and the limit, for example extensions: { code: "QUERY_TOO_COMPLEX", cost: 1840, limit: 1000 }. A client that sees "1840 of 1000" knows how far to trim. A bare rejection only prompts it to retry.
Multipliers are only meaningful if they have a ceiling. Make first/last required on list fields, or apply a server-side default. Reject or clamp values above a maximum, and have resolvers enforce the same cap. Otherwise a client can omit the argument and get an unbounded list that your model priced at the default.
The analysis itself also costs CPU. A megabyte of aliased fields can be expensive to parse and walk before cost is ever computed. Cap the request body size at the HTTP layer and limit token or node counts during parsing where your parser supports it. These limits keep the analysis cheap enough that an attacker cannot use it as the attack vector.
import { ApolloServer, ApolloServerPlugin } from '@apollo/server';
import { GraphQLError } from 'graphql';
import { getComplexity, simpleEstimator } from 'graphql-query-complexity';
import { typeDefs, resolvers } from './schema';
const MAX_COST = 1000;
const MAX_PAGE = 100; // hard ceiling; resolvers must enforce the same cap
const DEFAULT_PAGE = 20; // price an omitted page size at the server default
const costLimitPlugin: ApolloServerPlugin = {
async requestDidStart() {
return {
// Runs after parse + validate + operation selection, before any resolver.
async didResolveOperation({ request, document, schema }) {
const cost = getComplexity({
schema,
query: document,
operationName: request.operationName,
variables: request.variables ?? {}, // resolves first: $n to a real number
estimators: [
// List fields: multiply child cost by the page size.
({ args, childComplexity }) => {
if (args.first === undefined && args.last === undefined) return;
const n = Number(args.first ?? args.last);
if (n > MAX_PAGE) {
throw new GraphQLError(`Page size ${n} exceeds ${MAX_PAGE}`, {
extensions: { code: 'PAGE_SIZE_TOO_LARGE', limit: MAX_PAGE },
});
}
return 1 + (n || DEFAULT_PAGE) * childComplexity;
},
simpleEstimator({ defaultComplexity: 1 }),
],
});
if (cost > MAX_COST) {
throw new GraphQLError(`Query cost ${cost} exceeds limit ${MAX_COST}`, {
extensions: { code: 'QUERY_TOO_COMPLEX', cost, limit: MAX_COST },
});
}
},
};
},
};
// maxTokens bounds parse work before cost analysis ever runs.
export const server = new ApolloServer({ typeDefs, resolvers, plugins: [costLimitPlugin], parseOptions: { maxTokens: 5000 } });
An Apollo Server plugin that computes query cost in didResolveOperation with variables resolved, rejects oversized page sizes and over-budget queries with cost and limit in the error, and caps parser tokens.
Which related gaps should you close alongside cost limits?
Aliases, repeated fields, and batching
A cost model that scores each schema field once can miss the fact that aliases let a client request the same expensive field many times under different response keys. Count every selection, aliased or not, and also set a hard cap on the number of aliases per operation. Exact duplicate selections are merged during execution, but they still add parsing and validation work, so include them in the node limit. If your server accepts batched HTTP requests, apply the limit to the whole batch. Otherwise a client can send fifty operations that each fall just under the per-operation budget.
Introspection and operation allow-lists
Introspection does not bypass cost limits. It does give an attacker a full map of your most expensive fields. For a public API, introspection is often a deliberate feature. For a private API, disable it in production through Apollo Server's introspection setting. For first-party clients, register operations at build time and reject anything the server has not seen before. A true allow-list makes cost analysis largely redundant for those clients. Automatic persisted queries are a different mechanism: they cache arbitrary queries that clients send, and they restrict nothing on their own.
What static analysis cannot see
Static scores are estimates. They cannot know how many rows a filter will actually match, whether a downstream service is slow today, or whether a resolver triggers N+1 lookups. Keep these runtime safeguards in place:
- Per-resolver timeouts.
- Database statement timeouts and row limits.
- An overall request deadline that cancels outstanding work once it expires.
What are the alternatives to static query cost analysis?
Cost analysis is one layer among several, and each alternative covers a different failure mode:
| Control | Protects against | Misses | Client and tooling impact |
|---|---|---|---|
| Depth limiting | Deeply nested and cyclic queries | Wide, shallow queries with large list arguments | Low; easy to explain |
| Static cost analysis | Expensive shapes, including breadth and pagination | Data-dependent cost, slow resolvers | Moderate; clients need to know their budget |
| Persisted / allow-listed operations | Any query you did not ship | Abuse of approved operations through variables | High; requires a build step that registers operations |
| Introspection restriction | Easy schema discovery | Determined attackers who infer the schema | Breaks IDE autocompletion and codegen against production |
| Runtime timeouts | Runaway execution regardless of cause | Work already spent before cancellation | Invisible until a query fails |
| Rate limiting | High request volume per client | One expensive request within the limit | Low, unless limits are tuned too tight |
Rate limiting and cost analysis work best together. When you charge each client's quota by computed cost rather than by request count, the throttle tracks actual load.
Deprioritize cost analysis when every client is first-party and the server rejects operations that are not on the allow list. In that case the set of possible queries is fixed and reviewed. Measure those operations directly, and spend your effort on variable bounds, such as maximum first values, and on timeouts.
In federated setups, enforce depth and cost at the gateway or router. It sees the whole operation before query planning, while each subgraph sees only its own fragment. Subgraphs should still keep their own timeouts and row limits. They cannot assume every caller came through the gateway.
When should you avoid a query complexity limit?
A cost limit is a tool for untrusted or unpredictable query shapes. In several situations it adds maintenance without adding protection, or it actively causes harm:
- All operations are allow-listed. If the server executes only operations registered at build time, no client can send a new shape. Measure the registered operations, bound their variables, and skip the general cost model.
- The schema has no fan-out. A small internal API with few list fields, all with enforced page caps, gives a cost model little to catch. Depth limits, page caps and timeouts cover the realistic risks.
- You cannot keep weights current. A model whose weights no longer match the resolvers rejects legitimate queries and admits expensive ones. If no team will own weight reviews when resolvers change, a stale model is worse than a simple depth limit plus timeouts, because it gives false confidence.
- You have no traffic data yet. Enforcing a budget picked without measurement tends to break real clients. Run in log-only mode until you know what legitimate operations cost, as described in the next section.
- Cost is dominated by data, not shape. If the expensive part is a search or filter whose cost depends on the stored data, a static score cannot predict it. Rely on statement timeouts, row limits and request deadlines there, and keep any cost model coarse.
- Clients cannot handle the rejection. Turning on enforcement for clients that have no way to see their cost or adjust their queries, such as already-shipped mobile app versions, causes outages for users. Exempt those operations through an allow-list or a separate budget until those versions are retired.
Avoiding a general cost limit does not mean skipping protection. Page-size caps, timeouts and body-size limits still apply in every case above.
How do you calibrate and maintain the cost model without breaking clients?
Start in log-only mode. Compute the cost for every operation but reject nothing. Record the cost next to the operation name, client identifier, and measured resolver time. After a few weeks of traffic, plot cost against latency. If cheap-scoring queries run slow, the weights are wrong. If the two track each other, you can pick a budget just above the costliest legitimate operation. Then enforce it. Once enforcement works, you can also charge cost against per-client budgets over a time window, so a client sending many medium-sized queries hits a limit too.
Static scoring has limits you should plan for:
- Data-dependent fan-out. A
first: 10argument says nothing about how many children each item has. - Cache hits. A query can score high and be cheap when cached.
- Weight drift. Weights go stale as resolvers change. Review them whenever a resolver's data source or batching behavior changes.
Admin tools and internal dashboards often issue the largest queries. Give them a separate, higher budget instead of a global exemption. Treat lowering a limit as a breaking API change. Announce it, give clients a deprecation window, and return error messages that state the computed cost and the limit. Validation adds overhead to every request, so cache cost results for persisted or repeated operations.
The upfront cost is the modeling work plus ongoing weight reviews. The return is fewer pages for runaway queries and no more hand-written rules to block one abusive operation at a time.
How can a query complexity limit save engineering time?
The time savings come from replacing reactive, per-incident work with one general rule that runs on every request.
- Fewer incident investigations. Without a limit, an expensive query shows up as a slow database or a saturated downstream service, and an engineer has to trace the load back to a specific operation and client. With a limit, the query is rejected at the edge with an error code, and the logged cost points directly at the operation and client.
- No one-off blocking rules. Teams without cost analysis often respond to abuse by writing a rule that blocks one query string or one client. Each new variant needs another rule. A cost budget rejects the whole class of expensive shapes, including variants nobody has seen yet.
- Cheaper code review. With
@costweights next to field definitions, a reviewer can see from the schema diff when a change makes a field more expensive. That replaces load-testing every new field to find out whether it is dangerous to expose. - Faster client debugging. An error that states the computed cost and the limit tells a client developer exactly how much to trim. They do not need to open a support ticket or wait for a backend engineer to explain a rejection.
- Less capacity guesswork. Logged costs per client and operation give platform teams a single number to plan around, instead of reconstructing load from request counts that treat all queries as equal.
Illustrative estimate (assumed inputs, not a measured result). Assume a team handles two query-driven load incidents a month, each taking two engineers four hours to diagnose and mitigate. That is 16 engineer-hours a month. Assume the cost model takes 40 engineer-hours to build and calibrate, plus 4 hours a month of weight reviews. Under those assumptions, the model pays back its initial effort in about four months, and saves about 12 engineer-hours a month after that. Substitute your own incident rate and review effort. If you rarely see query-driven incidents, the review overhead may exceed the savings, which is one of the cases where the previous section suggests avoiding a general cost limit.
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.