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
}
}
}
}
}
// ❌ Rejected (depth: 8)
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)
);
}
}
};
visit(document);
return totalCost;
};
// Rate limiting based on cost
const costLimitPlugin = {
requestDidStart: () => ({
async didResolveOperation({ request, document, contextValue }) {
const cost = calculateQueryCost(
document,
request.variables,
{ objectCost: 1, scalarCost: 0.1, defaultListSize: 10 }
);
// Check user's rate limit
const limit = await getRateLimit(contextValue.user);
const used = await getCostUsed(contextValue.user);
if (used + cost > limit) {
throw new GraphQLError('Rate limit exceeded', {
extensions: {
code: 'RATE_LIMIT_EXCEEDED',
cost,
used,
limit
}
});
}
// Track cost usage
await incrementCostUsed(contextValue.user, 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 new DataLoader<string, Post[]>(
async (authorIds) => {
// Single query with all author IDs
const posts = await db.posts.query()
.whereIn('authorId', authorIds)
.select();
// Group by author ID
const postsByAuthor = authorIds.map(authorId =>
posts.filter(post => post.authorId === authorId)
);
return postsByAuthor;
}
);
};
// Multi-key loader
interface PostKey {
authorId: string;
status: string;
}
const createFilteredPostsLoader = (db) => {
return new DataLoader<PostKey, Post[]>(
async (keys) => {
// Extract unique author IDs and statuses
const authorIds = [...new Set(keys.map(k => k.authorId))];
const statuses = [...new Set(keys.map(k => k.status))];
// Single query for all combinations
const posts = await db.posts.query()
.whereIn('authorId', authorIds)
.whereIn('status', statuses)
.select();
// Map back to original keys
return keys.map(key =>
posts.filter(post =>
post.authorId === key.authorId &&
post.status === key.status
)
);
},
{
cacheKeyFn: (key) => `${key.authorId}:${key.status}`
}
);
};
// Loader with custom cache
import { LRUCache } from 'lru-cache';
const createCachedLoader = (db) => {
const cache = new LRUCache<string, User>({
max: 500,
ttl: 1000 * 60 * 5 // 5 minutes
});
return new DataLoader<string, User>(
async (userIds) => {
const users = await db.users.findByIds(userIds);
const userMap = new Map(users.map(u => [u.id, u]));
return userIds.map(id => userMap.get(id) || null);
},
{
cacheMap: 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, JSON.stringify(result));
return result;
};
const resolvers = {
Query: {
posts: async (_, args) => {
const cacheKey = `posts:${JSON.stringify(args)}`;
return cacheQuery(cacheKey, 300, async () => {
return db.posts.find(args);
});
},
// Automatic cache with hash
user: async (_, { id }) => {
const cacheKey = `user:${id}`;
return cacheQuery(cacheKey, 3600, async () => {
return db.users.findById(id);
});
}
}
};
// CDN caching with APQ
// Automatic Persisted Queries reduce bandwidth and enable CDN caching
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [
{
async requestDidStart() {
return {
async responseForOperation({ request, operation }) {
// Only cache if APQ hash is present
if (!request.extensions?.persistedQuery?.sha256Hash) {
return null;
}
// Cache GET requests at CDN
return {
http: {
headers: new Map([
['cache-control', 'public, max-age=300']
])
}
};
}
};
}
}
]
});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 = {
requestDidStart: () => ({
async didResolveSource({ source }) {
const hash = source.extensions?.persistedQuery?.sha256Hash;
if (!hash || !allowedQueries.has(hash)) {
throw new GraphQLError('Query not whitelisted', {
extensions: { code: 'FORBIDDEN' }
});
}
}
})
};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.withGraphFetched('comments');
}
return query;
}
}
};
// Optimized relationship loading
const optimizedResolvers = {
Query: {
users: async (_, { limit, offset }, { db }) => {
// Use joins instead of N queries
return db.users.query()
.limit(limit)
.offset(offset)
.withGraphFetched('[posts, profile]');
}
},
User: {
posts: async (parent, _, { db }) => {
// If already fetched with join, return it
if (parent.posts) {
return parent.posts;
}
// Otherwise, fetch individually
return db.posts.query().where('authorId', parent.id);
}
}
};
// Database indexes for GraphQL queries
// CREATE INDEX idx_posts_author_id ON posts(author_id);
// CREATE INDEX idx_posts_status ON posts(status);
// CREATE INDEX idx_posts_created_at ON posts(created_at DESC);
// CREATE INDEX idx_posts_author_status ON posts(author_id, status);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 willSendResponse({ response }) {
response.extensions = {
...response.extensions,
resolverTimings
};
}
};
}
};
// Performance tracking
const performancePlugin = {
requestDidStart() {
return {
async didResolveOperation({ request, operation }) {
// Track operation metrics
trackMetric('graphql.operation', 1, {
operation: operation.operation,
name: operation.name?.value || 'anonymous'
});
},
async didEncounterErrors({ errors }) {
errors.forEach(error => {
trackMetric('graphql.error', 1, {
code: error.extensions?.code || 'UNKNOWN'
});
});
},
async willSendResponse({ response }) {
const responseSize = JSON.stringify(response).length;
trackMetric('graphql.response_size', 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 }) {
if (errors) {
span.setStatus({
code: SpanStatusCode.ERROR,
message: errors[0].message
});
}
span.end();
}
};
}
};
}
};
// Apollo Studio tracing
const server = new ApolloServer({
typeDefs,
resolvers,
plugins: [
require('apollo-server-plugin-response-cache')(),
{
requestDidStart() {
return {
async willSendResponse({ response, metrics }) {
// Send to Apollo Studio
if (process.env.APOLLO_KEY) {
sendToApolloStudio({
operation: metrics.operationName,
duration: metrics.duration,
errors: response.errors
});
}
}
};
}
}
]
});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 keysetPagination = async (table, { after, limit }) => {
let query = db(table)
.orderBy([
{ column: 'createdAt', order: 'desc' },
{ column: 'id', order: 'desc' }
])
.limit(limit + 1);
if (after) {
const cursor = JSON.parse(Buffer.from(after, 'base64').toString());
query = query.where(function() {
this.where('createdAt', '<', cursor.createdAt)
.orWhere(function() {
this.where('createdAt', '=', cursor.createdAt)
.andWhere('id', '<', cursor.id);
});
});
}
return query;
};Best Practices
- Implement query complexity limits: Prevent expensive queries from overwhelming your server with complexity analysis
- Use depth limiting: Set maximum query depth to prevent deeply nested queries that cause performance issues
- Batch with DataLoader: Always use DataLoader for related data to avoid N+1 query problems
- Cache strategically: Implement multi-level caching (DataLoader, Redis, CDN) based on data volatility
- Monitor performance: Track resolver timing, query complexity, and error rates to identify bottlenecks
- Optimize database queries: Use selective field loading and conditional joins based on requested fields
- Implement APQ: Use Automatic Persisted Queries to reduce payload size and enable CDN caching
- Use cursor pagination: Prefer cursor-based pagination over offset for large datasets
- Add proper indexes: Create database indexes for common query patterns and filter fields
- Enable tracing: Use OpenTelemetry or Apollo Studio for distributed tracing and debugging
Common Pitfalls
- No query limits: Allowing unbounded queries that can cause denial of service
- Inefficient resolvers: Writing resolvers that don't use batching or caching, causing N+1 problems
- Missing indexes: Not creating database indexes for GraphQL query patterns
- Over-caching: Caching data too aggressively, leading to stale data being served
- Ignoring info parameter: Not using GraphQLResolveInfo to optimize field selection
- No monitoring: Deploying without performance monitoring and unable to identify issues
- Blocking operations: Using synchronous operations in resolvers that block the event loop
- Inefficient pagination: Using offset-based pagination for large datasets
- No rate limiting: Allowing unlimited queries per user without cost-based limits
- 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