Cybersecurity glossary
What is GraphQL Query Depth?
Learn what GraphQL query depth is, how deeply nested queries abuse resolvers, how depth limits differ from complexity scoring, and how to cap nesting safely in production.
Definition
GraphQL query depth is the maximum nesting level of fields in a query selection set; without depth limits, clients can send recursively nested queries that force excessive resolver chains, circular relationship walks, and denial-of-service conditions.
Why query depth matters
GraphQL schemas often model real-world graphs: users, friends, comments, authors, and more users. GraphQL query depth is how far a single request is allowed to walk that graph.
Unlimited depth turns recursive relationships into a denial-of-service primitive—no exploit chain required, just a deeply nested document.
Depth-related abuse patterns
Recursive relationship walks
Repeatedly nest friend/follower fields to explode resolver chains.
Circular type ping-pong
Alternate between two related types to deepen without obvious repetition.
Fragment-hidden nesting
Spread fragments that conceal deep structures from casual review.
Depth plus width
Combine moderate depth with huge lists for devastating total work.
Enforcing depth before resolvers run
Parse the query document
Build an AST including fragments and aliases.
Calculate maximum depth
Walk selection sets to find the deepest nesting path.
Compare to configured limit
Apply global and optionally per-operation depth policies.
Reject over-limit queries
Return a validation error without touching data sources.
Execute safe queries
Resolve only documents within the allowed nesting envelope.
Tune with product telemetry
Raise or lower limits based on legitimate client depth needs.
Depth vs complexity at a glance
| Dimension | Depth limit | Complexity budget |
|---|---|---|
| Measures | Nesting levels | Estimated total work |
| Stops well | Recursive deep trees | Wide expensive selections |
| Misses alone | Shallow but huge lists | Needs good field weights |
| When to apply | Validation phase | Validation phase |
Depth hardening checklist
- Set a default maximum query depth and enforce it in validation.
- Ensure analysis includes fragments, inline spreads, and aliases.
- Combine with complexity limits and max page sizes.
- Add timeouts and concurrency caps as backstop controls.
- Document legitimate deep queries so product needs inform the limit.
- Alert when clients repeatedly hit depth rejections.
- Review schema relationships that enable trivial recursion.
- Test with intentionally deep payloads in CI security suites.
The practical takeaway
GraphQL query depth caps how deep a request may nest. It is a simple, high-value control against recursive denial-of-service queries.
Use depth limits with complexity scoring and pagination rules so both deep and wide abuse patterns are covered.
Related security terms
GraphQL Query Complexity
Cost scoring that complements depth caps for wide queries.
Unrestricted Resource Consumption
Broader OWASP issue that deep queries exemplify.
GraphQL
Query language that allows arbitrary nesting by design.
GraphQL Batching Attack
Another amplification technique often combined with deep queries.
Rate Limiting
Volume control that should sit beside depth enforcement.
Frequently asked questions
What is GraphQL query depth in simple terms?
It is how many layers deep a query nests fields—like user { friends { friends { friends … } } }. Too much depth can crush the server.
How is depth different from complexity?
Depth counts nesting levels. Complexity estimates total work, which can explode from wide lists even when depth is small.
What is a safe depth limit?
It depends on the schema, but many APIs start around 5–10 and tune with real client needs and performance tests.
Can circular relationships be queried forever?
If types reference each other and depth is unlimited, queries can recurse until resources are exhausted.
Should depth be checked before execution?
Yes. Reject oversized depth during validation so resolvers never start.
Do fragments affect depth?
Depth analysis must account for fragments and inline spreads so nesting is not hidden.
Is depth limiting enough alone?
No. Pair it with complexity limits, pagination caps, and timeouts.
References
Explore authoritative guidance and frameworks related to graphql query depth.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.