Limit Expensive GraphQL Queries with Complexity Analysis (2026)

GraphQL queries can bring your backend to its knees if you’re not careful about how complex they are.

Let’s see this in action. Imagine a client wants to fetch a list of users and, for each user, their most recent 5 orders, and for each order, the 3 most recent product reviews.

query GetComplexUserData {
  users {
    id
    name
    email
    orders(last: 5) {
      id
      orderDate
      products(last: 3) {
        id
        name
        reviews(last: 3) {
          id
          rating
          comment
        }
      }
    }
  }
}

This looks innocent enough, but the server has to perform a lot of work. For N users, it’s doing N * 5 order lookups, and for each of those, 5 * 3 product lookups, and for each of those, 15 * 3 review lookups. That’s N * 5 * 3 * 3 = 45N nested operations, plus the initial user fetch. If N is large, or if the depth of nesting increases, this query can become exponentially expensive.

The problem GraphQL solves here is over-fetching and under-fetching. REST APIs often require multiple round trips to get related data (under-fetching) or return far more data than the client needs (over-fetching). GraphQL, by allowing clients to specify exactly what they need, eliminates both. But this power comes with a cost: the server has no inherent way to know how much work a query will require until it starts executing it.

Complexity analysis is the solution. It’s a mechanism to assign a "cost" to different parts of a GraphQL query before execution. This cost is typically based on the depth of the query, the number of fields requested, and the arguments used. For example, fetching a list of users might have a base cost of 1. Fetching orders for each user might add a cost proportional to the number of orders requested, say 5 per user. Fetching products for each order adds another multiplier, and reviews for each product adds yet another. The total complexity is the sum of these costs.

The core idea is to pre-define a "depth" or "complexity" budget for any incoming query. When a query arrives, the GraphQL server analyzes it and calculates its total complexity score. If this score exceeds a predefined threshold (e.g., 1000), the server rejects the query before it even touches your database or business logic. This prevents runaway queries from impacting performance.

You control this by implementing a query cost analyzer. Most GraphQL server libraries (like Apollo Server, graphql-js, etc.) provide hooks or middleware for this. You define a function that recursively traverses the Abstract Syntax Tree (AST) of a GraphQL query. For each node (field, argument), you apply a scoring rule. For instance, a simple users field might be cost = 1. An argument like first: 10 or last: 10 might add cost += 10. A nested field like orders might add cost += 5 * argument_value_of_first_or_last. The total cost is the sum of all these calculated costs.

// Example (simplified) scoring function for Apollo Server
const queryComplexity = require('graphql-query-complexity');

const schema = buildSchema(`...`); // Your GraphQL schema

const server = new ApolloServer({
  schema,
  plugins: [
    queryComplexity({
      // The maximum allowed complexity
      maximumComplexity: 1000,
      // Optional: function to calculate the complexity of a field
      estimators: [
        fieldExtensionsEstimator({
          // Define custom field costs here, e.g.:
          // myCustomScalarField: 5,
          // myConnectionField: (args) => 1 + (args.first || args.last || 10) * 2
        }),
        // Default estimators for depth and argument multipliers
        simpleEstimator({
          defaultComplexity: 1,
          objectArgumentMultiplier: 1,
          listArgumentMultiplier: 1,
        }),
      ],
    }),
  ],
});

The most surprising thing about complexity analysis is that it doesn’t need to be perfectly accurate; it just needs to be a good enough heuristic to prevent the worst offenders. A perfectly precise cost calculation would be incredibly complex and might even be more expensive than executing a slightly complex query. The goal is to catch exponentially growing queries, not to micro-manage the cost of every single field. A simple depth-based or argument-based multiplier is often sufficient.

The next concept you’ll run into is how to handle legitimate but high-cost queries, such as paginated lists where the client does need a large number of items.