GraphQL Optimization

Files (1)

• SKILL.md

SKILL.md (first lines)

# GraphQL Optimization

## Purpose
GraphQL resolvers run per field, so a naive implementation issues one database query per parent object (N+1) and lets clients send arbitrarily expensive queries. This skill removes N+1 with batching, bounds query cost, and adds caching where it is safe.

## Agent Protocol

### Trigger
Exact user phrases: "graphql n+1", "dataloader", "graphql slow", "graphql performance", "batch resolvers", "query complexity", "depth limit", "persisted queries", "graphql caching".

### Input Context
- Server library (Apollo Server, GraphQL Yoga, Mercurius, graphql-java, Strawberry, gqlgen, Hot Chocolate).
- Data layer (SQL/ORM, REST backends) and the slow query or resolver.
- Whether the API is public (untrusted clients) or first-party only.

### Output Artifact
Loader definitions, context wiring, and server validation/caching config. No files unless requested.

### Response Format
```
Problem: {N+1 on Type.field | unbounded query | no caching}
Fix: {DataLoader keyed by X | depth<=N, complexity<=M | APQ/persisted | cache hint}
Queries before/after: {n} -> {m}
Code: {loader + resolver + server config}
```

## Diagnosing N+1
Enable SQL logging (or tracing via OpenTelemetry) and run a list query such as:

```graphql
{ posts(first: 50) { id title author { name } } }
```

51 queries (`SELECT posts` + 50 x `SELECT user WHERE id = ?`) is N+1. Target: 2 queries.

## DataLoader (Node.js)

Rules that make DataLoader correct:
1. **Create loaders per request** (in the context factory). A global loader caches across users and leaks data between requests.
2. The batch function receives an array of keys and **must return an array of the same length in the same order**, with `null` or an `Error` instance for missing keys.
3. Batching happens within one tick of the event loop; resolvers just call `loader.load(id)`.

```ts
import DataLoader from 'dataloader';
import type { Pool } from 'pg';

export interface User { id: string; name: string }

export function createLoaders(db: Pool) {
  return {
    userById: new DataLoader<string, User | null>(async (ids) => {
      const { rows } = await db.query<User>(
        'SELECT id, name FROM users WHERE id = ANY($1)',
        [ids as string[]],
      );
      const byId = new Map(rows.map((u) => [u.id, u]));
      return ids.map((id) => byId.get(id) ?? null);
    }),
    // One-to-many: key = authorId, value = that author's posts.
    postsByAuthor: new DataLoader<string, Post[]>(async (authorIds) => {
      const { rows } = await db.query<Post>(
        'SELECT * FROM posts WHERE author_id = ANY($1)',
        [authorIds as string[]],
      );
      const grouped = new Map<string, Post[]>();
      for (const p of rows) {
        const list = grouped.get(p.author_id) ?? [];
        list.push(p);
        grouped.set(p.author_id, list);
      }
      return authorIds.map((id) => grouped.get(id) ?? []);
    }),
  };
}

export interface Post { id: string; title: string; author_id: string }
```

Resolvers and per-request context (Apollo Server 4+ standalone):

```ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import depthLimit from 'graphql-depth-limit';
import { Pool } from 'pg';
import { createLoaders } from './loaders';
import { typeDefs } from './schema'; // SDL string or DocumentNode

const db = new Pool({ connectionString: process.env.DATABASE_URL });

type Ctx = { loaders: ReturnType<typeof createLoaders> };

const resolvers = {
  Post: {
    author: (post: { author_id: string }, _: unknown, ctx: Ctx) =>
      ctx.loaders.userById.load(post.author_id),
  },
  User: {
    posts: (user: { id: string }, _: unknown, ctx: Ctx) =>
      ctx.loaders.postsByAuthor.load(user.id),
  },
};

const server = new ApolloServer<Ctx>({
  typeDefs,
  resolvers,
  validationRules: [depthLimit(8)], // reject deeply nested queries
});

await startStandaloneServer(server, {
  context: async () => ({ loaders: createLoaders(db) }), // fresh per request
});
```

Equivalents in other stacks: `java-dataloader` (graphql-java, Spring for GraphQL `@BatchMapping`), `strawberry.dataloader.DataLoader` (Python), `graph-gophers/dataloader` or gqlgen's dataloaden pattern (Go), Hot Chocolate `BatchDataLoader` (.NET).

## Alternative: Join-Based Resolution
When the parent resolver can see the selection set, fetch children in the same SQL with a JOIN (tools: Join Monster, PostGraphile, Hasura, Prisma `include`). This is faster for fixed shapes but couples resolvers to SQL; DataLoader stays simpler and works across data sources.

From j4flmao/agent-skills, MIT.

More from j4flmao/agent-skills