Skip to content

skillBackend and APIsgraphql

GraphQL N+1

Finds resolvers that fire one query per parent object and fixes them with request-scoped dataloaders, batching and proof from query counts.

npx workspacetemplates add graphql-n-plus-one --tool claude-code

Writes 1 file to .claude/skills/graphql-n-plus-one/

.claude/skills/graphql-n-plus-one/SKILL.md28 lines · 1.7 KBFile
---
name: graphql-n-plus-one
description: Finds resolvers that fire one query per parent object and fixes them with request-scoped dataloaders, batching and proof from query counts.
---

# GraphQL N+1

Count queries before and after. No count, no fix.

## Steps

1. Reproduce with one realistic query that returns a list with nested fields. Enable query logging (ORM debug flag, `pg_stat_statements` or a logging data source) and count statements for that single request. Record the number.
2. Find the pattern: a resolver on a child type that runs a lookup by the parent's id, for example `Order.customer` calling `db.customer.findById(order.customerId)`.
3. Add a dataloader per resolver family. Create loaders in the per-request context, never at module level, so one user's cache and permissions never leak to another.
4. The batch function receives an array of keys and must return an array of the same length and order. Fetch with one `WHERE id IN (...)` query, then map back by key and return `null` or an error for the missing ones.
5. For one-to-many fields, load by foreign key and group the rows into an array per key.
6. Where a query can join cheaply (the parent query already knows the children are always wanted), prefer a join or a lookahead on the selected fields over a loader.
7. Add a test that runs the query against a fixture of 20 parents and asserts the statement count (for example 3, not 41).

## Rules

- Never share a loader between requests.
- Never rely on the batch result order from the database; reorder it.
- Do not add loaders for fields that are not in a list; it adds code with no gain.

## Report

Query count before and after, resolvers changed, loaders added and the test that guards them.

What it does

A list of 50 orders with a customer on each one can quietly become 51 database queries. It passes review because every resolver looks fine on its own. This skill makes the agent measure first, using query logs, then fix only what it can show.

The usual fix is a dataloader created per request, keyed correctly and returning results in the order the keys came in. The agent adds a test that asserts the number of queries so the regression cannot return unseen.

Example

you › The orders query takes 2 seconds when it returns 100 orders. Find the N+1.

agent › Request issued 304 queries. Causes: Order.customer, Order.items and Item.product each queried per parent. Added three per-request loaders in src/graphql/loaders.ts, with the batch results reordered by key. Count is now 4 and the query takes 140 ms. Added a test asserting 4 statements for 100 orders.

Questions

Why create loaders per request?
The loader caches by key. A shared one would serve one user data loaded for another, which is both stale and a permissions leak.
Does this work with Prisma or SQLAlchemy?
Yes. The batching idea is the same; the skill uses whichever query API your project already has.
  • API Error Responses

    SkillBackend and APIs

    Free
  • API Pagination Design

    SkillBackend and APIs

    Free
  • API Versioning Strategy

    SkillBackend and APIs

    Free
  • Background Job Design

    SkillBackend and APIs

    Free