Cybersecurity glossary
What is GraphQL Query Complexity?
Learn what GraphQL query complexity is, how cost analysis scores expensive queries, why request rate limits are not enough, and how to set complexity budgets that stop resource abuse.
Definition
GraphQL query complexity is a measure of how expensive a query is to execute—usually estimated from selected fields, multipliers, and list sizes—so servers can reject or throttle operations that would consume disproportionate CPU, memory, or downstream calls.
Why query complexity matters
In REST, each route roughly implies a cost. In GraphQL, clients compose arbitrary trees. GraphQL query complexity gives servers a way to price that tree before paying for it.
Without complexity budgets, a single crafted query can traverse huge graphs, trigger N+1 resolver storms, and take down shared dependencies.
What drives complexity
Field cost weights
Some fields hit caches; others trigger expensive downstream RPCs.
List multipliers
Arguments like first:1000 multiply child field costs.
Nested selections
Each level adds work across relationships and joins.
Aliases and fragments
Repeated selections increase total scored work in one document.
Complexity analysis flow
Parse and validate the document
Ensure the query matches the schema before costing.
Score the selection set
Apply field costs and multipliers across aliases and fragments.
Compare to the caller budget
Budgets may vary by anonymous vs authenticated vs premium clients.
Reject oversized queries early
Fail closed before resolvers touch databases.
Execute within budget
Resolve only after the estimate is acceptable.
Observe real vs estimated cost
Tune weights using runtime telemetry and slow-query logs.
Limits that work together
| Control | Best at stopping |
|---|---|
| Complexity budget | Wide expensive queries and alias amplification |
| Depth limit | Deep recursive nesting |
| Pagination enforcement | Unbounded list arguments |
| HTTP rate limits | High request volume across many calls |
| Timeouts / concurrency caps | Runaway resolver latency |
Complexity hardening checklist
- Assign explicit costs to expensive fields; do not treat all fields as equal.
- Multiply list costs by requested or default page sizes.
- Include aliases and batch operations in the scored total.
- Reject over-budget queries before execution.
- Enforce maximum page sizes independently of complexity.
- Tune costs from production telemetry, not guesses alone.
- Give tighter budgets to anonymous clients.
- Pair with depth limits and persisted queries for public APIs.
The practical takeaway
GraphQL query complexity prices work so abusive queries fail cheaply. Request rate limits alone cannot see the difference between a featherweight and a database-crushing document.
Budget the cost, enforce it early, and keep tuning weights as your schema evolves.
Related security terms
GraphQL Query Depth
Depth limits that complement complexity scoring for nested queries.
Unrestricted Resource Consumption
OWASP category covering unbounded GraphQL work.
GraphQL Batching Attack
Amplification technique that complexity budgets should price.
Rate Limiting
Request quotas that work best alongside cost-aware GraphQL limits.
GraphQL
Query language that makes per-request cost highly variable.
Frequently asked questions
What is GraphQL query complexity in simple terms?
It is a score for how heavy a query is. A request that asks for thousands of nested records should cost more against your budget than a tiny profile lookup.
Why aren’t HTTP rate limits enough?
Two GraphQL POSTs can differ by orders of magnitude in work. Limiting requests alone lets one cheap-looking call exhaust databases.
How are complexity scores assigned?
Servers assign static costs to fields and multiply by list arguments or default list sizes, then sum the selected tree.
What happens when a query exceeds the budget?
The server should reject it before resolving, returning a clear error rather than starting expensive work.
Is complexity the same as depth?
No. Depth counts nesting levels. Complexity estimates total work, which can be huge even at shallow depth with wide lists.
Can clients bypass complexity analysis?
They can try aliases and alternate shapes, so analysis must account for aliases, fragments, and batching.
Should mutations have costs too?
Yes. Expensive writes and fan-out mutations need budgets just like reads.
References
Explore authoritative guidance and frameworks related to graphql query complexity.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.