GraphQL Cost Estimator — Analyze Query Complexity and Depth

How to Use the GraphQL Query Cost Estimator:

1. Paste your GraphQL query: Enter any valid GraphQL query into the Query textarea on the left. The tool supports shorthand queries, named queries, mutations, aliases, fragments, inline fragments, and nested selection sets. Use the example buttons (Simple Query, Nested + Args, Social Graph) to load ready-made queries and see how the tool works.

2. Load a field weight preset: Click one of the three preset buttons above the Field Weights table — REST-like API, Social Graph, or E-Commerce — to load a pre-configured weight table suited to your API type. Each preset includes typical field names and their recommended complexity costs. You can edit any value after loading a preset.

3. Configure field weights: The Field Weights table maps each field name to a numeric cost. Fields with weight 0 are free (leaf fields like id, name). Fields like users or products get higher weights because they trigger database queries or joins. Use the field name input to match the exact name as it appears in your GraphQL schema. Click Add Field to add more rows, or the trash icon to remove a row.

4. Set the default weight: The Default Weight controls the cost assigned to any field not explicitly listed in the table. Set it to 0 if you only want to score specific fields, or to a small positive number (like 1 or 2) to count every unspecified field toward the total.

5. Understand argument multipliers: If a field has a count-style argument — limit, first, last, count, pageSize, size, or take — the estimator multiplies that field's base weight by the argument value. For example, users(limit: 10) with a weight of 10 contributes 100 to the total score. This models the real cost of fetching large result sets.

6. Click Calculate Cost: Press the Calculate Cost button to parse the query and compute the total complexity score. The tool builds a recursive AST from your query, resolves aliases and inline fragments, and walks the full field tree.

7. Read the total score and rating: The large score card shows the total complexity number along with a rating — Low (≤50), Medium (≤200), High (≤500), or Very High (>500). Use these thresholds as starting points and adjust them to match your API's capacity and rate limits.

8. Review the per-field breakdown table: The breakdown table shows every field in the query with its depth (indented visually), base weight, argument multiplier, and individual cost. Rows with high costs are easy to spot. Use this to identify which fields are driving the complexity and decide whether to reduce their weights, add caching, or impose argument limits.

9. Iterate on weights: Adjust field weights and re-run the calculation to find the right balance. You can set critical root fields (search, recommendations) much higher than scalar leaf fields. Fields that always return a single object (user, order) can have lower weights than list fields (products, posts) that scale with argument values.

10. Export or document thresholds: Copy the total score value to set a threshold in your GraphQL server middleware. Tools like graphql-cost-analysis, graphql-query-complexity, or GraphQL Shield use similar field-weight schemes. You can translate the weights and thresholds from this tool directly into your server configuration.

Common Use Cases:

• API rate limiting: Set a maximum complexity threshold (e.g., 500) and reject queries that exceed it
• Cost-aware caching: Prioritize caching for high-cost fields and queries
• Developer education: Show engineers which queries are expensive before they ship
• Security hardening: Prevent deeply nested or large-result queries from overloading your database
• Schema design reviews: Evaluate the cost implications of new field additions before release
• CI checks: Integrate complexity scoring into pull request checks for GraphQL schema changes
• Client SDK guidelines: Document complexity budgets so client teams know which queries to avoid

Tips and Best Practices:

• Start with a preset that matches your API type, then adjust individual field weights
• Set scalar leaf fields (id, name, email, createdAt) to 0 — they add no measurable database cost
• Give list-returning fields (users, posts, products) high base weights since they scale with result size
• Use argument multipliers for pagination — a field with limit=100 is 100× more expensive than limit=1
• A good starting threshold for a typical API is 200–500 total complexity points
• Treat the score as relative, not absolute — calibrate it against your real server performance
• Fields backed by full-text search or aggregation (search, analytics) should have the highest weights
• Nested list fields multiply — posts inside users inside feed compounds the cost exponentially
• Set up your production GraphQL server (Apollo, Yoga, Envelop) to enforce the same thresholds
• Re-run analysis after every schema change that adds new list fields or expensive resolvers