2026-09-25 · 9 min
GraphQL DataLoader: Solving the N+1 Problem in Production Without Magic
Your GraphQL API works in development. It is fast, the queries look clean, and your tests pass. Then you hit a dataset of 200 records in staging and suddenly your /graphql endpoint takes 4 seconds. You open pg_stat_activity and see 201 identical SELECT queries running in a loop. That is the N+1 problem, and it will find you eventually.
GraphQL DataLoader is the standard fix. It is not magic — it is a batching and memoization library that exploits the fact that all resolvers for a single GraphQL query execute within the same Node.js event loop tick. Understanding exactly what it does (and what it does not do) is what separates a working integration from one that silently fails under load.
Why resolvers naturally produce N+1
In a REST API you control exactly what joins happen in a query. In GraphQL, resolvers are independent functions. The schema decides what fields exist; the resolver decides how to fetch them. This independence is powerful for composability, but it means each resolver has no awareness of what other resolvers are fetching at the same time.
Take a simple schema:
type Query {
orders(limit: Int!): [Order!]!
}
type Order {
id: ID!
total: Int!
user: User!
}
type User {
id: ID!
name: String!
}
The naive resolver setup:
const resolvers = {
Query: {
orders: (_, { limit }) => db.query(`SELECT * FROM orders LIMIT $1`, [limit]),
},
Order: {
// This fires once for EVERY order in the list
user: (order) => db.query(`SELECT * FROM users WHERE id = $1`, [order.userId]),
},
};
Fetch 50 orders, fire 51 queries. Fetch 200 orders — a realistic production dataset for a dashboard on Jalan M.H. Thamrin scraping transaction data from a fintech partner — and you get 201 queries, most of them fetching the same 5 users over and over.
DataLoader: what actually happens
DataLoader works by collecting .load(key) calls that happen within the same event loop tick, then calling your batch function once with all those keys combined.
Install it:
npm install dataloader
Create a loader per entity type, scoped to the request:
import DataLoader from "dataloader";
import { Pool } from "pg";
// One factory function — call this once per incoming GraphQL request
export function createLoaders(db: Pool) {
return {
userLoader: new DataLoader<string, User | null>(async (userIds) => {
// userIds is the collected array of all keys from this tick
const result = await db.query(
`SELECT * FROM users WHERE id = ANY($1::uuid[])`,
[userIds]
);
// DataLoader requires the returned array to be the same length
// as the input array, in the same order
const userMap = new Map(result.rows.map((u) => [u.id, u]));
return userIds.map((id) => userMap.get(id) ?? null);
}),
productLoader: new DataLoader<string, Product | null>(async (productIds) => {
const result = await db.query(
`SELECT * FROM products WHERE id = ANY($1::uuid[])`,
[productIds]
);
const productMap = new Map(result.rows.map((p) => [p.id, p]));
return productIds.map((id) => productMap.get(id) ?? null);
}),
};
}
export type Loaders = ReturnType<typeof createLoaders>;
The critical part is the ordering guarantee. DataLoader expects the batch function to return an array where index 0 corresponds to key 0, index 1 to key 1, and so on. If your batch function returns results in a different order — which is exactly what a SQL query with WHERE id = ANY(...) does — you must re-map them manually. I have seen bugs where engineers forgot this and ended up returning user B’s data to requests expecting user A.
Wiring loaders into the GraphQL context
Loaders are per-request. Create them in the context function of your GraphQL server:
import { ApolloServer } from "@apollo/server";
const server = new ApolloServer({ typeDefs, resolvers });
// Express integration
app.use(
"/graphql",
expressMiddleware(server, {
context: async ({ req }) => {
return {
db,
loaders: createLoaders(db), // fresh loaders per request
currentUser: await getUserFromRequest(req),
};
},
})
);
Then update your resolvers to use the loader instead of querying directly:
const resolvers = {
Query: {
orders: (_, { limit }, { db }) =>
db.query(`SELECT * FROM orders LIMIT $1`, [limit]),
},
Order: {
// Now this returns a Promise — DataLoader batches all calls
user: (order, _, { loaders }) => loaders.userLoader.load(order.userId),
},
};
Those 201 queries become 2. One for the orders list, one batched query for all unique user IDs. The resolver code barely changed — just swap the direct query for loaders.userLoader.load(id).
The ordering guarantee is your most common bug
Worth repeating with a concrete failure case. If your batch function does this:
// WRONG — SQL returns rows in arbitrary order
const userLoader = new DataLoader<string, User>(async (ids) => {
const result = await db.query(`SELECT * FROM users WHERE id = ANY($1)`, [ids]);
return result.rows; // rows might be [user_3, user_1, user_2] for ids [1, 2, 3]
});
DataLoader will assign user_3 to id 1, user_1 to id 2, etc. Wrong data gets served, no error thrown. The correct pattern is to build a map and re-index:
// CORRECT
const userLoader = new DataLoader<string, User | null>(async (ids) => {
const result = await db.query(`SELECT * FROM users WHERE id = ANY($1)`, [ids]);
const map = new Map(result.rows.map((u) => [u.id, u]));
return ids.map((id) => map.get(id) ?? null); // guaranteed same order as input
});
Always return null (not undefined) for missing keys. Some versions of DataLoader are strict about this.
Caching and when to clear it
DataLoader caches by key within a request. If two resolvers both call userLoader.load("user-42") in the same request, the second call hits the cache and no additional query is made. This is correct and safe for per-request loaders.
Sometimes you need to bust the cache — for example, after a mutation that updates a user within the same request:
const resolvers = {
Mutation: {
updateUser: async (_, { id, input }, { db, loaders }) => {
await db.query(`UPDATE users SET name = $1 WHERE id = $2`, [input.name, id]);
// Clear this key so subsequent reads in this request get fresh data
loaders.userLoader.clear(id);
return loaders.userLoader.load(id);
},
},
};
For cross-request caching — reducing database hits for frequently-read reference data like product categories or exchange rates — DataLoader is not the right tool. Use Redis with an appropriate TTL. DataLoader and Redis serve different purposes: DataLoader eliminates duplicate queries within a request; Redis eliminates queries across requests.
Monitoring: how to verify DataLoader is working
Trust but verify. Add query logging to your database layer and watch what happens:
// Wrap pg Pool to count queries per request
function createInstrumentedPool(pool: Pool) {
return {
query: async (sql: string, params?: unknown[]) => {
const requestId = AsyncLocalStorage.getStore()?.requestId;
queryCounter.increment(requestId);
return pool.query(sql, params);
},
};
}
In your GraphQL server, log the query count after each request. Before DataLoader, a typical dashboard query might show 150+ queries. After, it should be under 10. If the number is still high, check whether your loaders are actually being used (add a console.log inside the batch function temporarily) and whether you are accidentally creating new loader instances inside resolvers instead of using the context.
A simpler check: enable log_min_duration_statement = 0 in PostgreSQL for one request cycle and count the queries in the logs. Raw, but effective for a quick audit during a production incident.
Nested batching: loaders calling loaders
DataLoader handles nested fetching gracefully. If your Order.user resolver triggers userLoader, and User.company triggers companyLoader, these will be batched in separate ticks but each tick still batches correctly. You do not need to flatten your resolver graph to make DataLoader work. The batching happens naturally at each level of nesting.
What you should avoid is mixing DataLoader calls with direct database calls inside the same resolver without a good reason. Inconsistency makes it harder to reason about query counts during debugging.
When DataLoader is not enough
DataLoader solves the per-field batch problem. It does not solve these:
Overfetching from parent queries. If your orders query does SELECT * and returns 50 columns but the GraphQL query only asks for id and total, you are wasting bandwidth and memory. Consider projecting columns based on the info object (which contains the selected fields), though this adds significant complexity and is rarely worth it unless columns are very wide.
Deeply nested queries with cartesian explosions. A GraphQL query that fetches orders, then for each order fetches line items, then for each line item fetches the product, then for each product fetches its category — four levels deep — will produce four batched queries total, but those intermediate queries might return thousands of rows. DataLoader makes the query count manageable, but it does not protect you from fetching too much data. Add complexity limits to your GraphQL schema to cap this.
Unbounded list resolvers. Always paginate list resolvers. orders(limit: Int! = 20, cursor: String) instead of orders: [Order!]! without a limit. DataLoader helps with N+1 but cannot help if someone requests 10,000 orders in one query.
Production checklist
Before shipping a GraphQL API to production:
- Confirm loaders are created per-request, not as module-level singletons
- Verify batch functions maintain ordering (test with non-sequential IDs)
- Add query count logging per request and set an alert if it exceeds a threshold (e.g., 50 queries per request is a signal something is wrong)
- Set query complexity limits on your GraphQL server
- Load test with a realistic dataset size — staging with 20 records will never surface N+1 issues
The N+1 problem is one of those bugs that feels minor in development and catastrophic in production. DataLoader eliminates it cleanly, but only if you wire it correctly. The ordering guarantee is not optional, the per-request scoping is not optional, and monitoring is not optional. Get those three right and you will not be staring at pg_stat_activity at midnight wondering why your API degraded.
Ditulis oleh Reza Pradipta