graphql-performance

name	graphql-performance
user-invocable	false
description	Use when optimizing GraphQL API performance with query complexity analysis, batching, caching strategies, depth limiting, monitoring, and database optimization.
allowed-tools	[]

GraphQL Performance

Apply GraphQL performance optimization techniques to create efficient, scalable APIs. This skill covers query complexity analysis, depth limiting, batching and caching strategies, DataLoader optimization, monitoring, tracing, and database query optimization.

Query Complexity Analysis

Query complexity analysis prevents expensive queries from overwhelming your server by calculating and limiting the computational cost.

import { GraphQLError } from 'graphql';
import { ApolloServer } from '@apollo/server';

// Complexity calculator
const getComplexity = (field, childComplexity, args) => {
  // Base complexity for field
  let complexity = 1;

  // List multiplier based on limit argument
  if (args.limit) {
    complexity = args.limit;
  } else if (args.first) {
    complexity = args.first;
  }

  // Add child complexity
  return complexity + childComplexity;
};

// Directive-based complexity
const schema = `
  directive @complexity(
    value: Int!
    multipliers: [String!]
  ) on FIELD_DEFINITION

  type Query {
    user(id: ID!): User @complexity(value: 1)
    users(limit: Int): [User!]! @complexity(
      value: 1,
      multipliers: ["limit"]
    )
    posts(first: Int): [Post!]! @complexity(
      value: 5,
      multipliers: ["first"]
    )
  }

  type User {
    id: ID!
    posts: [Post!]! @complexity(value: 10)
  }
`;

// Complexity validation plugin
const complexityPlugin = {
  requestDidStart: () => ({
    async didResolveOperation({ request, document, operationName }) {
      const complexity = calculateComplexity({
        document,
        operationName,
        variables: request.variables
      });

      const maxComplexity = 1000;

      if (complexity > maxComplexity) {
        throw new GraphQLError(
          `Query is too complex: ${complexity}. ` +
          `Maximum allowed: ${maxComplexity}`,
          {
            extensions: {
              code: 'QUERY_TOO_COMPLEX',
              complexity,
              maxComplexity
            }
          }
        );
      }
    }
  })
};

// Manual complexity calculation
const calculateComplexity = ({ document, operationName, variables }) => {
  let totalComplexity = 0;

  const visit = (node, multiplier = 1) => {
    if (node.kind === 'Field') {
      // Get field complexity from directive or default
      const complexity = getFieldComplexity(node);

      // Handle multipliers from arguments
      const args = getArguments(node, variables);
      const fieldMultiplier = getMultiplier(args);

      totalComplexity += complexity * multiplier * fieldMultiplier;

      // Visit child fields
      if (node.selectionSet) {
        node.selectionSet.selections.forEach(child =>
          visit(child, multiplier * fieldMultiplier)
        );
      }
    }
  };

  visit(document);
  return totalComplexity;
};

Depth Limiting

Prevent deeply nested queries that can cause performance issues and potential denial of service attacks.

import { ValidationContext, GraphQLError } from 'graphql';

const depthLimit = (maxDepth: number) => {
  return (validationContext: ValidationContext) => {
    return {
      Field(node, key, parent, path, ancestors) {
        const depth = ancestors.filter(
          ancestor => ancestor.kind === 'Field'
        ).length;

        if (depth > maxDepth) {
          validationContext.reportError(
            new GraphQLError(
              `Query exceeds maximum depth of ${maxDepth}. ` +
              `Found depth of ${depth}.`,
              {
                nodes: [node],
                extensions: {
                  code: 'DEPTH_LIMIT_EXCEEDED',
                  depth,
                  maxDepth
                }
              }
            )
          );
        }
      }
    };
  };
};

// Usage with Apollo Server
const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [depthLimit(7)]
});

// Example queries
// ✅ Allowed (depth: 4)
query {
  user {
    posts {
      comments {
        author {
          username
        }
      }
    }
  }
}


query {
  user {
    friends {
      friends {
        friends {
          friends {
            friends {
              friends {
                friends {
                  username
                }
              }
            }
          }
        }
      }
    }
  }
}

Query Cost Analysis

Implement cost-based rate limiting to protect against expensive queries.

interface CostConfig {
  objectCost: number;
  scalarCost: number;
  defaultListSize: number;
}

const calculateQueryCost = (
  document,
  variables,
  config: CostConfig
) => {
  let totalCost = 0;

  const visit = (node, multiplier = 1) => {
    if (node.kind === 'Field') {
      const fieldType = getFieldType(node);

      // List cost
      if (isListType(fieldType)) {
        const listSize = getListSize(node, variables) ||
          config.defaultListSize;
        multiplier *= listSize;
      }

      // Field cost
      if (isObjectType(fieldType)) {
        totalCost += config.objectCost * multiplier;
      } else {
        totalCost += config.scalarCost * multiplier;
      }

      // Visit children
      if (node.selectionSet) {
        node.selectionSet.selections.forEach(child =>
          visit(child, multiplier)
        );
      }
    }
  };

  ();
   totalCost;
};


 costLimitPlugin = {
  :  ({
     () {
       cost = (
        ,
        request.,
        { : , : , :  }
      );

      
       limit =  (contextValue.);
       used =  (contextValue.);

       (used + cost > limit) {
          (, {
          : {
            : ,
            cost,
            used,
            limit
          }
        });
      }

      
       (contextValue., cost);
    }
  })
};

Batching with DataLoader

Optimize data fetching by batching multiple requests into single database queries.

import DataLoader from 'dataloader';

// Basic DataLoader setup
const createUserLoader = (db) => {
  return new DataLoader<string, User>(
    async (userIds) => {
      // Single query for all users
      const users = await db.users.findByIds(userIds);

      // Map to maintain order
      const userMap = new Map(users.map(u => [u.id, u]));
      return userIds.map(id => userMap.get(id) || null);
    },
    {
      // Cache for duration of request
      cache: true,
      // Batch at most 100 at a time
      maxBatchSize: 100,
      // Wait 10ms before batching
      batchScheduleFn: callback => setTimeout(callback, 10)
    }
  );
};

// Advanced batching with joins
const createPostsLoader = (db) => {
  return  <, []>(
     (authorIds) => {
      
       posts =  db..()
        .(, authorIds)
        .();

      
       postsByAuthor = authorIds.(
        posts.( post. === authorId)
      );

       postsByAuthor;
    }
  );
};


  {
  : ;
  : ;
}

  = () => {
    <, []>(
     (keys) => {
      
       authorIds = [... (keys.( k.))];
       statuses = [... (keys.( k.))];

      
       posts =  db..()
        .(, authorIds)
        .(, statuses)
        .();

      
       keys.(
        posts.(
          post. === key. &&
          post. === key.
        )
      );
    },
    {
      :  
    }
  );
};


 {  }  ;

  = () => {
   cache =  <, >({
    : ,
    :  *  *  
  });

    <, >(
     (userIds) => {
       users =  db..(userIds);
       userMap =  (users.( [u., u]));
       userIds.( userMap.(id) || );
    },
    {
      : cache
    }
  );
};

Response Caching Strategies

Implement multi-level caching for optimal performance.

import { createHash } from 'crypto';

// Field-level caching
const cacheControl = {
  User: {
    __cacheControl: { maxAge: 3600 }, // 1 hour

    posts: {
      __cacheControl: { maxAge: 300 } // 5 minutes
    }
  },

  Post: {
    __cacheControl: { maxAge: 600, scope: 'PUBLIC' }
  }
};

// Redis caching
import Redis from 'ioredis';

const redis = new Redis();

const cacheQuery = async (key: string, ttl: number, fn: () => any) => {
  // Try cache
  const cached = await redis.get(key);
  if (cached) {
    return JSON.parse(cached);
  }

  // Execute and cache
  const result = await fn();
  await redis.setex(key, ttl, .(result));

   result;
};

 resolvers = {
  : {
    :  (_, args) => {
       cacheKey = ;

       (cacheKey, ,  () => {
         db..(args);
      });
    },

    
    :  (_, { id }) => {
       cacheKey = ;

       (cacheKey, ,  () => {
         db..(id);
      });
    }
  }
};



 server =  ({
  typeDefs,
  resolvers,
  : [
    {
       () {
         {
           () {
            
             (!request.?.?.) {
               ;
            }

            
             {
              : {
                :  ([
                  [, ]
                ])
              }
            };
          }
        };
      }
    }
  ]
});

Persistent Queries and APQ

Implement Automatic Persisted Queries to reduce payload size and enable better caching.

import { ApolloServer } from '@apollo/server';
import { KeyvAdapter } from '@apollo/utils.keyvadapter';
import Keyv from 'keyv';

// APQ with Redis backend
const server = new ApolloServer({
  typeDefs,
  resolvers,
  persistedQueries: {
    cache: new KeyvAdapter(new Keyv('redis://localhost:6379'))
  }
});

// Client sends hash instead of full query
// First request:
// POST /graphql
// {
//   "query": "query GetUser { user(id: \"1\") { id name } }",
//   "extensions": {
//     "persistedQuery": {
//       "version": 1,
//       "sha256Hash": "abc123..."
//     }
//   }
// }

// Subsequent requests (99% smaller):
// GET /graphql?extensions={"persistedQuery":{"version":1,"sha256Hash":"abc123..."}}

// Query whitelisting
const allowedQueries = new Map([
  ['getUser', 'query GetUser($id: ID!) { user(id: $id) { id name } }'],
  ['getPosts', 'query GetPosts { posts { id title } }']
]);

const whitelistPlugin = {
  :  ({
     () {
       hash = source.?.?.;

       (!hash || !allowedQueries.(hash)) {
          (, {
          : { :  }
        });
      }
    }
  })
};

Database Query Optimization

Optimize database queries to support GraphQL efficiently.

// Use info parameter for selective field loading
import { GraphQLResolveInfo } from 'graphql';
import { parseResolveInfo } from 'graphql-parse-resolve-info';

const resolvers = {
  Query: {
    users: async (_, args, { db }, info: GraphQLResolveInfo) => {
      // Parse requested fields
      const parsedInfo = parseResolveInfo(info);
      const fields = Object.keys(parsedInfo.fields);

      // Only select requested fields
      return db.users.query().select(fields);
    },

    // Conditional joins based on requested fields
    posts: async (_, args, { db }, info: GraphQLResolveInfo) => {
      const parsedInfo = parseResolveInfo(info);

      let query = db.posts.query();

      // Join author only if requested
      if (parsedInfo.fields.author) {
        query = query.withGraphFetched('author');
      }

      // Join comments only if requested
      if (parsedInfo.fields.comments) {
        query = query.();
      }

       query;
    }
  }
};


 optimizedResolvers = {
  : {
    :  (_, { limit, offset }, { db }) => {
      
       db..()
        .(limit)
        .(offset)
        .();
    }
  },

  : {
    :  (parent, _, { db }) => {
      
       (parent.) {
         parent.;
      }

      
       db..().(, parent.);
    }
  }
};

Monitoring and Profiling

Implement comprehensive monitoring to identify performance bottlenecks.

import { ApolloServer } from '@apollo/server';

// Timing plugin
const timingPlugin = {
  requestDidStart() {
    const start = Date.now();

    return {
      async willSendResponse({ response }) {
        const duration = Date.now() - start;

        // Add timing to response
        response.extensions = {
          ...response.extensions,
          timing: { duration }
        };
      }
    };
  }
};

// Detailed resolver timing
const detailedTimingPlugin = {
  requestDidStart() {
    const resolverTimings = {};

    return {
      async executionDidStart() {
        return {
          willResolveField({ info }) {
            const start = Date.now();

            return () => {
              const duration = Date.now() - start;
              const path = info.path.key;

              resolverTimings[path] = duration;
            };
          }
        };
      },

      async () {
        response. = {
          ...response.,
          resolverTimings
        };
      }
    };
  }
};


 performancePlugin = {
  () {
     {
       () {
        
        (, , {
          : operation.,
          : operation.?. || 
        });
      },

       () {
        errors.( {
          (, , {
            : error.?. || 
          });
        });
      },

       () {
         responseSize = .(response).;

        (, responseSize);
      }
    };
  }
};

Tracing and Observability

Implement distributed tracing for GraphQL operations.

import { trace, SpanStatusCode } from '@opentelemetry/api';

// OpenTelemetry tracing plugin
const tracingPlugin = {
  requestDidStart() {
    const tracer = trace.getTracer('graphql-server');

    return {
      async didResolveOperation({ request, operation }) {
        const span = tracer.startSpan('graphql.operation', {
          attributes: {
            'graphql.operation.type': operation.operation,
            'graphql.operation.name': operation.name?.value
          }
        });

        return {
          async executionDidStart() {
            return {
              willResolveField({ info }) {
                const fieldSpan = tracer.startSpan(
                  `graphql.resolve.${info.fieldName}`,
                  { attributes: { 'graphql.field': info.fieldName } }
                );

                return () => {
                  fieldSpan.end();
                };
              }
            };
          },

          async willSendResponse({ errors }) {
             (errors) {
              span.({
                : .,
                : errors[].
              });
            }

            span.();
          }
        };
      }
    };
  }
};


 server =  ({
  typeDefs,
  resolvers,
  : [
    ()(),
    {
      () {
         {
           () {
            
             (process..) {
              ({
                : metrics.,
                : metrics.,
                : response.
              });
            }
          }
        };
      }
    }
  ]
});

Pagination Optimization

Implement efficient pagination strategies for large datasets.

// Cursor-based pagination with database optimization
const resolvers = {
  Query: {
    posts: async (_, { first, after }, { db }) => {
      const limit = first || 10;

      let query = db.posts.query()
        .orderBy('createdAt', 'desc')
        .limit(limit + 1); // Fetch one extra to determine hasNextPage

      if (after) {
        const cursor = decodeCursor(after);
        query = query.where('createdAt', '<', cursor.createdAt);
      }

      const posts = await query;
      const hasNextPage = posts.length > limit;

      const edges = posts.slice(0, limit).map(post => ({
        cursor: encodeCursor({ createdAt: post.createdAt }),
        node: post
      }));

      return {
        edges,
        pageInfo: {
          hasNextPage,
          endCursor: edges[edges.length - 1]?.cursor
        }
      };
    }
  }
};

// Keyset pagination for better performance
const  =  () => {
   query = (table)
    .([
      { : , :  },
      { : , :  }
    ])
    .(limit + );

   (after) {
     cursor = .(.(after, ).());
    query = query.(() {
      .(, , cursor.)
        .(() {
          .(, , cursor.)
            .(, , cursor.);
        });
    });
  }

   query;
};

Best Practices

1. Implement query complexity limits: Prevent expensive queries from overwhelming your server with complexity analysis
2. Use depth limiting: Set maximum query depth to prevent deeply nested queries that cause performance issues
3. Batch with DataLoader: Always use DataLoader for related data to avoid N+1 query problems
4. Cache strategically: Implement multi-level caching (DataLoader, Redis, CDN) based on data volatility
5. Monitor performance: Track resolver timing, query complexity, and error rates to identify bottlenecks
6. Optimize database queries: Use selective field loading and conditional joins based on requested fields
7. Implement APQ: Use Automatic Persisted Queries to reduce payload size and enable CDN caching
8. Use cursor pagination: Prefer cursor-based pagination over offset for large datasets
9. Add proper indexes: Create database indexes for common query patterns and filter fields
10. Enable tracing: Use OpenTelemetry or Apollo Studio for distributed tracing and debugging

Common Pitfalls

1. No query limits: Allowing unbounded queries that can cause denial of service
2. Inefficient resolvers: Writing resolvers that don't use batching or caching, causing N+1 problems
3. Missing indexes: Not creating database indexes for GraphQL query patterns
4. Over-caching: Caching data too aggressively, leading to stale data being served
5. Ignoring info parameter: Not using GraphQLResolveInfo to optimize field selection
6. No monitoring: Deploying without performance monitoring and unable to identify issues
7. Blocking operations: Using synchronous operations in resolvers that block the event loop
8. Inefficient pagination: Using offset-based pagination for large datasets
9. No rate limiting: Allowing unlimited queries per user without cost-based limits
10. Cache stampede: Not handling cache expiration properly, causing all requests to hit the database simultaneously

When to Use This Skill

Use GraphQL performance optimization skills when:

• Building a new GraphQL API that needs to scale
• Experiencing slow query response times
• Debugging N+1 query problems in production
• Implementing rate limiting and query cost analysis
• Adding caching layers to improve performance
• Optimizing database queries for GraphQL patterns
• Setting up monitoring and observability
• Protecting against malicious or expensive queries
• Migrating to production and need performance tuning
• Identifying and fixing performance bottlenecks

Resources

• GraphQL Best Practices - Official performance guidance
• DataLoader Documentation - Batching and caching patterns
• Apollo Performance Guide Performance optimization guide
• GraphQL Query Complexity Query complexity analysis
• OpenTelemetry for GraphQL - Distributed tracing implementation