System Design HLD-03.04
GraphQL
One endpoint and a typed schema: queries, mutations, over- and under-fetching, the N+1 problem and dataloaders, caching and cost limits, and when GraphQL fits.
The big idea
A mobile app's home screen needs the user's name, their last five orders, and for each order the product names and delivery status. With REST that might be one call for the user, one for the orders, and one per order for products: many round trips over a slow mobile network, each returning far more fields than the screen shows. The client either makes too many calls (under-fetchingNeeding several requests to get all the data one screen needs.) or receives too much data (over-fetchingReceiving fields the client does not need because the endpoint returns a fixed shape.).
GraphQLA query language and runtime for APIs where clients send a query describing exactly the fields they want, against a typed schema, usually to a single endpoint. flips the contract. The server publishes a typed schema of everything it can provide, and the client sends one query describing exactly the shape of data it wants. The server returns that shape, no more and no less, in one round trip. It was built at Facebook for exactly this mobile problem and released publicly in 2015.
Think of a restaurant. REST is a set menu: each dish comes as the kitchen designed it. GraphQL is ordering a la carte from a precise list of ingredients: you get exactly your plate, but the kitchen has to be ready for any combination.
How it works
Step 1: Schema, queries and mutations
The server defines types:
type User { id: ID!, name: String!, orders(last: Int): [Order!]! }
type Order { id: ID!, total: Float!, status: String!, items: [Item!]! }
type Item { product: Product!, qty: Int! }
type Query { me: User }
type Mutation { cancelOrder(id: ID!): Order }
The client asks for exactly what the screen needs:
query HomeScreen {
me {
name
orders(last: 5) { status items { product { name } } }
}
}
The response mirrors the query's shape as JSON. Writes use mutations, and many servers also support subscriptions for real-time updates. Because the schema is typed and introspectable, tools can autocomplete queries and generate typed client code.
Step 2: Resolvers and the gateway
Each field in the schema has a resolverA function the GraphQL server calls to produce the value of one field, for example by querying a database or calling another service.. The server walks the query tree and calls resolvers to fill in each field. In a microservice system, a GraphQL gateway often sits in front of many services, so one client query fans out to several backends:
Step 3: The N+1 problem and dataloaders
Naive resolvers are dangerous. Fetching 5 posts and then each post's author runs one query for the posts plus one query per post: the N+1 problemRunning one query for a list and then one more query for each item in it, so N items cost N + 1 queries.. With 100 posts that is 101 database queries for one request. The standard fix is a dataloaderA per-request helper that collects the keys resolvers ask for during one tick and loads them all in a single batched query, also caching repeats.: resolvers ask the loader for an author id, the loader waits until all resolvers at that level have asked, then fetches every needed author in one batched query.
# A GraphQL query: { posts(first: 5) { title author { name } } }
POSTS = [{"id": i, "title": f"Post {i}", "author_id": a} for i, a in enumerate([1, 2, 1, 3, 2], 1)]
AUTHORS = {1: "Ada", 2: "Grace", 3: "Linus"}
queries = []
def db(sql, *args):
queries.append(sql)
return args
def author_naive(post): # resolver runs once per post
db("SELECT * FROM users WHERE id = ?", post["author_id"])
return AUTHORS[post["author_id"]]
class AuthorLoader: # collects ids, then loads them in one query
def __init__(self):
self.ids = []
def load(self, post):
self.ids.append(post["author_id"])
def dispatch(self):
wanted = sorted(set(self.ids))
db(f"SELECT * FROM users WHERE id IN ({', '.join('?' * len(wanted))})", *wanted)
return {i: AUTHORS[i] for i in wanted}
queries.clear(); db("SELECT * FROM posts LIMIT 5")
naive = [(p["title"], author_naive(p)) for p in POSTS]
print("naive: ", len(queries), "queries (1 for posts + 1 per post = N+1)")
queries.clear(); db("SELECT * FROM posts LIMIT 5")
loader = AuthorLoader()
for p in POSTS:
loader.load(p)
names = loader.dispatch()
batched = [(p["title"], names[p["author_id"]]) for p in POSTS]
print("dataloader:", len(queries), "queries ", queries[-1])
print("same result:", naive == batched)Output
naive: 6 queries (1 for posts + 1 per post = N+1)
dataloader: 2 queries SELECT * FROM users WHERE id IN (?, ?, ?)
same result: True Six queries become two, and the gap grows with the list: a page of 100 posts still costs two queries with a dataloader.
Step 4: The costs
- Caching is harder. REST GETs to distinct URLs are cached by browsers, CDNs and proxies for free. GraphQL usually sends POSTs to one URL with different bodies, so HTTP caching does not apply. Teams use persisted queries (a hash of a known query sent as a GET), client-side normalized caches and server-side caching per resolver.
- Expensive queries. A client can ask for users, their friends, their friends' friends and their posts, nested ten deep. Servers must enforce depth limits, cost analysis and timeouts, and often allow only pre-registered queries from their own apps.
- Errors are different. A GraphQL response can be
200 OKwith partial data and anerrorsarray, so monitoring must look inside responses.
Going deeper
Federation
When many teams own parts of the graph, a single schema file does not scale. Federation lets each service publish its own piece of the schema (users, orders, catalog), and a gateway composes them into one graph and plans which services each query needs. It adds a layer of infrastructure, but keeps ownership with the teams that own the data.
GraphQL as a backend-for-frontend
GraphQL is often used precisely where a backend-for-frontend fits: a layer shaped around client screens in front of many services. You will compare the two in API gateway and backend-for-frontend .
Trade-offs
| Option | Wins when | Loses when |
|---|---|---|
| GraphQL | Many client types and complex screens pulling related data from several services | Simple CRUD APIs, public APIs that rely on HTTP caching, teams without capacity to secure query costs |
| REST | Resource-shaped APIs, public APIs, anything that benefits from CDN and browser caching | Screens that need many related resources in one round trip |
| GraphQL with persisted queries only | First-party apps: caching via GET and no arbitrary query risk | Third-party developers who want to write their own queries |
Common mistakes
- Writing resolvers without a dataloader, then discovering hundreds of database queries per request in production.
- Exposing an open GraphQL endpoint with no depth or cost limits, inviting accidental or malicious denial of service.
- Monitoring only HTTP status codes, which are 200 even when fields failed.
- Adopting GraphQL for a simple CRUD service where REST would be easier and cache better.
Check yourself
-
What problem does GraphQL mainly solve for mobile clients?
Show answer
B. Over- and under-fetching: getting exactly the needed fields in one round trip Clients describe the exact shape they need and get it in one request.
-
A query lists 50 posts with their authors and makes 51 database queries. What is this?
Show answer
B. The N+1 problem One query for the list and one per item. A dataloader batches the author lookups into one query.
-
Why is HTTP caching harder with GraphQL?
Show answer
B. Queries usually go as POSTs to one URL with varying bodies, which shared caches do not key on CDNs and browsers cache GETs by URL; GraphQL needs persisted queries or application-level caching.
-
Why must public GraphQL servers limit query depth and cost?
Show answer
B. Because deeply nested queries can be extremely expensive to resolve A single nested query can fan out into millions of lookups without limits.
Recap
- GraphQL exposes a typed schema; clients query exactly the fields they need in one request.
- Resolvers fill each field; a gateway can fan one query out to many services.
- Naive resolvers cause N+1 queries; dataloaders batch them.
- HTTP caching, query cost limits and error monitoring need extra work.
- It fits complex clients over many services; REST still fits simple and public APIs.
Next up
- Crack the system design round learning path