GraphQL Concepts: Schema, Resolvers, Execution
The ideas behind GraphQL that last, no matter which server is in fashion right now – the schema as a typed contract, the query as a shape, the resolver model and the order of execution. A conceptual deep dive with diagrams.
GraphQL Concepts: Schema, Resolvers, Execution
GraphQL isn’t a query language for databases, and a resolver isn’t a controller. Both comparisons hold up to a point and then break – at the latest with the query that looks harmless and triggers thirty individual database calls in the server. The explanation isn’t in the manual of whichever server you use but in the specification. Once you have properly understood its execution rules, you read different GraphQL servers with the same mental model.
The GraphQL overview laid out the topic in breadth, from the schema to federated architecture. Here we go one level deeper, to the ideas behind the tools: what a schema really is, why a query looks like its response, and how execution walks through the tree field by field. That sounds like basics, but it’s exactly on these basics that it’s decided whether you master GraphQL or merely use it.
The schema is a typed graph#
On first reading, a schema looks like a collection of data types. It is that, but the decisive property lies in the relationships between the types. Let’s take a blog again:
type Author {
id: ID!
name: String!
posts: [Post!]!
}
type Post {
id: ID!
title: String!
author: Author!
}
Author points to Post, and Post points back to Author. So the schema doesn’t describe a flat catalog but a graph: the types are nodes, and the fields that point to other types are edges. The name is meant literally. A query is then nothing more than a path through this graph that the client chooses itself.
The modifiers are part of the contract, not decoration. String! means: this field is guaranteed to be present. [Post!]! means: guaranteed to be a list, guaranteed to have no gaps in it. A client can rely on this and doesn’t have to check defensively for null where the schema rules null out. Conversely, a non-nullable field that does return null forces an error – so the guarantee is enforced, not merely promised.
And then there are the three root types: Query, Mutation and Subscription. They are the only doors into the graph. Everything a client can do starts at a field of one of these three types. Whatever isn’t there doesn’t exist for the client. That makes the schema a complete, binding contract – and one of the few API descriptions that are documentation, validation rule and type definition at the same time.
A query is a shape#
The second idea is simple and still the one that surprises people switching over the longest: a GraphQL query has the same shape as its response.
query {
author(id: "1") {
name
posts {
title
}
}
}
The response to it has the same structure – an author with a name and a list of posts, in which every entry has a title. You don’t describe how data is fetched but which shape you want to have in the end. That’s the same declarative attitude that shows up elsewhere in the modern frontend world: you name the goal, not the path.
From this follows the well-known promise of reducing over-fetching and under-fetching at the interface. The client only receives the selected fields and can request related data in one document. That guarantees neither a single network round trip under every transport architecture nor efficient access behind the resolvers. But the server gets a precise description of what is needed – a good basis for planning execution accordingly.
The resolver model#
Now to execution. For every field in the query, the server calls a function, the resolver. A resolver always receives the same four arguments, in this order:
function resolver(source, args, context, info) {
// source – the parent object (the return value of the field above)
// args – this field's arguments in the query
// context – a per-request object (e.g. the logged-in user, data access)
// info – information about execution state (which field, which path)
}
The first argument is the key to understanding the chain. The return value of a resolver becomes the source for the resolvers of the fields below it. If the resolver for author resolves an author, the resolver for that author’s posts gets exactly this author as source and can use it to load the posts.
const resolvers = {
Query: {
author: (source, { id }, context) => context.db.loadAuthor(id),
},
Author: {
// source here is the author from the resolver above
posts: (author, args, context) => context.db.loadPostsForAuthor(author.id),
},
Post: {
// source here is a single post
author: (post, args, context) => context.db.loadAuthor(post.authorId),
},
};
For most fields, you don’t write a resolver at all. If a field is called name and the parent object has a name property, the default resolver kicks in: it reads the property of the same name from the source. So you only write resolvers explicitly where something needs to be done – where data is loaded, computed or transformed. That keeps most schemas surprisingly lean.
The context deserves a sentence of its own, because a lot depends on it. It’s built once per request and passed to every resolver. That’s where the identity of whoever makes the request ends up, and that’s where access to the data sources lives. Because every resolver sees the same context, it’s the natural place for authentication and for shared resources – without having to thread them through every function signature.
The order of execution#
How exactly does execution walk through the tree? It follows the selection recursively from the root fields to their subfields. A subfield can only be resolved once the value of its parent field is available; independent sibling fields, on the other hand, may be evaluated in parallel. So it isn’t a strictly clocked breadth-first traversal, level by level.
flowchart TB Q["Query"] --> A["author resolver<br/>returns author"] A --> N["name<br/>(default resolver)"] A --> P["posts resolver<br/>returns list"] P --> T1["title of post 1"] P --> T2["title of post 2"]
Two subtleties matter, because they have consequences in everyday work. First: the server resolves sibling fields on the same level concurrently, not strictly one after the other. If a resolver returns a promise, the server waits for it, but it doesn’t block the siblings. That’s why resolvers must not make assumptions about their execution order relative to neighboring fields – they should work independently of one another.
Second, and this is the one deliberate exception: at the top level of a mutation, execution runs serially. If a mutation names several write fields, the server executes them one after the other in document order. That replaces neither transactions nor isolation. For queries, freedom from side effects is an important convention, not a guarantee enforced by the execution model; that’s why the server may evaluate independent root fields in parallel.
N+1 and why batching belongs to it#
An almost inevitable problem follows from the resolver model, one that every GraphQL developer runs into sooner or later. If someone queries a list of authors and the posts for each, the posts resolver runs once per author. With ten authors, that’s ten calls – and if each makes its own database query, you have ten queries plus the one for the author list. That’s the N+1 problem: one query for the list, N more for the children.
The way out is batching. Instead of running off immediately, you collect all requests that arise within one execution tick and answer them with a single query. The usual implementation is the DataLoader library: you no longer ask the database directly but a loader for an ID; the loader waits until the end of the current tick, bundles all collected IDs and resolves them in one go. Along the way, it remembers within the request what it has already loaded, so the same ID isn’t fetched twice.
flowchart LR
R1["posts of author 1"] --> L["DataLoader<br/>collects IDs in the tick"]
R2["posts of author 2"] --> L
R3["posts of author 3"] --> L
L -->|one batched query| DB[("Database")]Batching doesn’t paper over a design flaw. It’s the consistent answer to the nature of the resolver model: field-by-field resolution is the reason for GraphQL’s flexibility – and batching is both its price and the clean solution for it. A loader belongs in the context, so that it’s fresh for each request and its cache doesn’t persist across request boundaries.
Why these concepts last#
You can build GraphQL with Apollo Server, with GraphQL Yoga, with a library in C#, Go or Python. The server changes, the ecosystem shifts, the specification gets new versions. But the schema remains a typed graph, the query remains a shape, the resolvers remain a chain with the same four arguments, and execution remains a top-down traversal with serial mutations and concurrent siblings.
That’s exactly why it pays to understand this level and not just the API of a particular server. If you know what a resolver receives and how execution runs through the tree, you can narrow down N+1 problems in a more targeted way, design schemas that grow with you, and find your way around a different server faster. The tools are interchangeable. The concepts aren’t.
Further reading#
- Repository introduction-graphql (chapters resolver, schema, subscriptions): https://github.com/mikebild/introduction-graphql
- Slide overview for this topic area: https://slides.mikebild.dev/introduction-graphql.en.html
- GraphQL, execution: https://graphql.org/learn/execution/
- GraphQL, Schema and types: https://graphql.org/learn/schema/
- GraphQL specification, execution: https://spec.graphql.org/
- DataLoader (batching and caching per request): https://github.com/graphql/dataloader
Revised and translated from German with the help of AI.