Guide
Formatting GraphQL and estimating what a query costs
GraphQL queries are often copied from network logs, error reports and code generators on a single line, which makes them hard to read and review. And because one query can ask for nested lists of lists, a request that looks small can ask the server for thousands of objects. This tool formats queries, mutations and schemas with the reference printer and estimates the depth, size and cost of each operation.
Formatting with the reference printer
The text is parsed with graphql-js, the reference implementation maintained by the GraphQL Foundation, and printed back with its print function. That produces the canonical layout: two-space indentation, one field per line, arguments and variables formatted consistently and comments removed. If the text does not parse, the parser’s message with line and column appears instead, which is often the fastest way to find a missing brace.
Depth, fields and aliases
For each operation, the analyser counts how deeply selections are nested, how many fields are requested and how many aliases are used. Depth matters because many servers reject queries above a limit such as 7 or 10 levels to prevent deeply recursive requests. Fields inside fragments count where the fragment is spread, and introspection fields such as __typename are left out.
The cost model
Field counts understate the work when lists are involved. The estimate follows the approach public APIs such as GitHub’s use: every field costs 1, multiplied by the page size of each list it sits inside, read from arguments named first, last, limit, take, pageSize, perPage or count. A field inside repositories(first: 20) costs 20; inside issues(first: 5) within that, it costs 100. Lists without a size argument count as 1, so the real cost can be higher.
Fragments and warnings
Named fragments are expanded where they are spread, with protection against fragments that spread each other in a loop. The analyser warns about fragments that are defined but never used, operations deeper than seven levels, more than ten aliases in one operation, and documents with several operations where one is unnamed, which servers reject.
A worked example
The Sample is a one-line RepoDashboard query. After formatting it starts query RepoDashboard($owner: String!, $name: String!) { and spreads over several dozen lines. The analysis reports a depth of 7, 25 fields, no aliases and an estimated cost of 1,305. The comments alone account for 800 of it: up to ten comments for each of twenty issues, each with a body and an author login, even though the query names those fields only once.
Schemas too
Schema definition language (SDL), the type, interface, enum, input, union and scalar definitions in schema.graphql files, is formatted the same way, and the number of type definitions is reported. Cost analysis applies only to operations.
What a syntax-only analyser cannot know
The tool does not have your schema, so it cannot tell whether fields exist, whether arguments have the right types or whether a list returns ten items or ten thousand when no size argument is given. Each server has its own cost formula and limits; use this estimate to compare versions of a query and to spot the ones that multiply, then check the real numbers against the API’s documentation or its rate-limit headers.
Related tools
- JSON Formatter tidies the JSON responses.
- Protobuf Formatter does a similar job for gRPC schemas.
- cURL to Code turns a copied GraphQL request into application code.
- Rate Limit Simulator shows how cost-based limits behave over time.
Checked against the current version of the GraphQL Formatter on .