GraphQL Query Complexity Analyzer
Estimate a GraphQL query's cost by multiplying nested page sizes, measure depth and field count, and catch unused variables, fragments and cycles.
The interactive tool loads here when JavaScript runs.
About this toolWhat is the GraphQL Complexity Analyzer?
The GraphQL Query Complexity Analyzer parses a query, mutation or subscription and estimates how much work it asks the server to do. It reports the maximum depth, the number of fields selected (with fragments expanded where they are used), and an estimated cost: the number of field resolutions once list sizes are multiplied through.
The cost model is the one large public APIs use. Each field costs 1, and a field under a paginated parent costs as many times as that parent can return items. posts(first: 10) { comments(first: 5) { body } } asks for up to 50 comment bodies. Page sizes come from first, last, limit, take, top, pageSize, perPage or count arguments, from variable defaults, or an assumed 10 when a variable has no default.
It also lists problems a server would reject or that usually signal a mistake: unknown or unused fragments, fragment cycles, variables used without being declared or declared without being used, several anonymous operations, and page sizes above 100. It works without your schema, so it cannot know which unpaginated fields are lists; treat the number as a lower bound.
- Real parsing, so braces in strings and comments do not skew depth
- Cost estimate that multiplies nested page sizes
- Fragment expansion with cycle detection
- Unused and undeclared variable checks
- Downloadable text report; runs in your browser
Updated
How to use the GraphQL Complexity Analyzer
- Paste a query into GraphQL Query Input, or press Load Sample for a deeply nested example.
- Press Analyze Complexity.
- Read Complexity Metrics: the level, estimated cost, max depth, field count and number of queries and mutations.
- Work through Issues Found and Optimization Suggestions, then re-analyze.
- Use the download button to save a text report that includes the query.
Worked examples
Nested pagination multiplies
Input
query { posts(first: 10) { title comments(first: 5) { body } } }Output
Estimated cost 71, depth 3, 4 fields, level Low
posts costs 1, title and comments cost 10 each (one per post) and body costs 50 (5 per post times 10 posts): 1 + 10 + 10 + 50 = 71.
The loaded sample
Input
GetUserWithPosts: user > posts(first: $first = 10) > comments(first: 5) > replies(first: 3)
Output
Estimated cost 1,251, depth 12, 37 fields, level High, plus a depth warning
Twelve levels of nesting and three nested connections. Splitting the replies into a separate request would cut both numbers sharply.
Background and insight
GraphQL lets a client ask for a lot in one request, and nested lists are where cost hides. A query that is only 15 lines long can ask for hundreds of thousands of objects if each level requests 100 items. That is why public APIs put limits on queries. GitHub's GraphQL API requires first or last between 1 and 100 on connections and refuses a call that would return more than 500,000 nodes in total, calculated with the same multiplication this tool uses.
Depth limits are the simpler defence. Many servers reject queries nested beyond a fixed depth because cyclic schemas (a user has friends, who have friends...) otherwise allow unbounded nesting. Depth here counts fields: a root field is depth 1, and inline fragments and fragment spreads do not add a level.
Common use cases
Reviewing client queries
Check a new screen's query in code review before it ships and hits production limits.
Choosing server limits
Measure the depth and cost of your real queries to pick depth and cost limits that block abuse without breaking clients.
Debugging rate limits
Understand why an API with point-based rate limiting charges a query more than expected.
Cleaning up documents
Find unused fragments and variables left behind after refactors.
Tips and limitations
- The outermost page size multiplies everything below it, so reduce it first.
- Without a schema the analyzer cannot see unpaginated list fields, so a field like tags may return many items while counting once.
- __typename fields are counted as fields but not as cost, since servers resolve them without a resolver call.
- Thresholds used for the level: under 100 is Low, under 1,000 Medium, under 10,000 High, and Critical above that.
- Prefer variables over hard-coded argument values so servers can cache and persist the query document.
Sources and further reading
- Rate limits and query limits for the GraphQL API, GitHub Docs. The 1 to 100 page size rule and the 500,000 node limit
- Security, GraphQL Foundation. Depth limiting, query cost analysis and other defences
- GraphQL Specification, October 2021 edition, GraphQL Foundation. Fragments and the rule that every fragment must be used
Frequently asked questions
How is GraphQL query complexity calculated here?
Each field costs 1, multiplied by the page size of every paginated ancestor. A field under first: 10 inside first: 5 costs 50. Page sizes come from first, last, limit and similar arguments, from variable defaults, or an assumed 10 for variables without one.
What is a safe maximum depth for GraphQL queries?
There is no standard number. Measure the depth of your real client queries and set the server limit just above the deepest legitimate one. This tool flags anything deeper than 7 as a prompt to look, not as a rule from the spec.
Why does a short GraphQL query get a high cost?
Because cost grows with nested lists, not with line count. Three nested connections asking for 100 items each can mean a million objects. The estimate shows that multiplication so you can shrink the page sizes that matter.
Does the analyzer need my GraphQL schema?
No. It works from the query alone, which is convenient but means it cannot tell which unpaginated fields return lists. Server-side cost analysis with schema-aware weights is more accurate; use this as a quick first check.
Why is my fragment reported as never used?
A fragment defined in a document must be spread somewhere with ...FragmentName in an operation, or servers reject the document. Remove the fragment or spread it where you meant to use it.
Is there an in-depth guide to the GraphQL Complexity Analyzer?
Yes. “GraphQL Schemas and Queries: Validation, Types and Query Cost” covers the background, how it works, common pitfalls and worked examples. Read the full guide.
Related Tools You May Like
Free, in-browser tools that pair well with this one.