⚙️ Queries, Mutations, and Resolvers

The Three Operations

GraphQL defines exactly three operation types:

1. Queries — read data.
2. Mutations — create, update, or delete data.
3. Subscriptions — receive real-time updates (usually over WebSockets).

This lesson focuses on queries and mutations, and on the resolvers that fulfil both.

💡 A restaurant analogy. The schema is the menu. A query is ordering dishes that already exist. A mutation is asking the kitchen to make or change something. And the resolvers are the kitchen staff who actually know how to prepare each item on the menu.

Queries in Depth

A query names the fields you want, mirroring the shape of the JSON you'll get back:

query {
  user(id: "123") {
    id
    name
    email
    posts {
      title
      publishedAt
    }
  }
}

Its parts: the operation type (query), a field (user), its arguments (id: "123"), and a nested selection for related data.

Query variables

Hard-coding values into a query is a mistake. Declare variables so the same query is reusable, type-checked, and safe from injection-style bugs:

query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
  }
}

Variables travel alongside the query as a separate JSON object:

{ "userId": "123" }

Aliases, Fragments & Directives

Aliases

You can't request the same field twice with different arguments unless you rename the results. Aliases do exactly that:

query {
  activeUser: user(id: "123") { id fullName: name email }
  adminUser:  user(id: "456") { id fullName: name email }
}

{
  "data": {
    "activeUser": { "id": "123", "fullName": "Alice Smith", "email": "alice@example.com" },
    "adminUser":  { "id": "456", "fullName": "Bob Jones",  "email": "bob@example.com" }
  }
}

Fragments

A fragment is a reusable selection set — the DRY principle for queries:

fragment UserBasics on User {
  id
  name
  email
}

query {
  regularUser: user(id: "123") { ...UserBasics }
  contentCreator: user(id: "456") {
    ...UserBasics
    posts { id title }
  }
}

Directives: @include and @skip

Two built-in query directives conditionally include fields based on a variable:

query GetUserDetails($withPosts: Boolean!, $skipEmail: Boolean!) {
  user(id: "123") {
    id
    name
    email @skip(if: $skipEmail)
    posts @include(if: $withPosts) {
      title
    }
  }
}

• @include(if: Boolean) — include the field only when the argument is true.
• @skip(if: Boolean) — omit the field when the argument is true.

Mutations & Payloads

Mutations change server-side data. They look like queries but use the mutation keyword and typically return the object they affected:

mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
    email
  }
}

Two behaviors set mutations apart from queries: they always use the explicit mutation keyword, and top-level mutation fields execute sequentially (queries may resolve in parallel), so ordering side effects is predictable.

Payload types

Returning the bare object works, but production APIs usually return a dedicated payload type. It carries the affected object and structured errors, and it can grow new fields later without breaking clients:

type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  path: String!
  message: String!
  code: String!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

Resolvers: The Implementation

A resolver is a function that produces the value for a single field. Resolvers are the bridge between your schema and your data sources.

The resolver signature

Every resolver receives four arguments:

const resolvers = {
  User: {
    // parent:  the User object this field belongs to
    // args:    arguments for THIS field (e.g. limit, offset)
    // context: shared per-request object (auth, db, loaders)
    // info:    execution details (field name, path, AST)
    posts: (parent, args, context, info) => {
      return context.db.post.findMany({ where: { authorId: parent.id } });
    },
  },
};

• parent — the result of the resolver one level up (the object holding this field).
• args — the arguments supplied to this field in the query.
• context — a value shared by every resolver in a request; the home for the database client, the authenticated user, and DataLoaders.
• info — metadata about the execution (rarely needed day to day).

Nested, field-level resolution

GraphQL resolves the query field by field, walking down the tree. Given this schema and query:

query {
  user(id: "123") {
    name
    posts {
      title
      comments { text }
    }
  }
}

the server runs, in order: the user resolver → reads name off the returned object → the posts resolver → for each post reads title and runs the comments resolver. Any field without an explicit resolver uses the default resolver, which simply reads the matching property off parent. That's why scalar fields like name usually need no resolver at all.

const resolvers = {
  Query: {
    user: (_parent, { id }, { db }) => db.user.findUnique({ where: { id } }),
  },
  User: {
    posts: (user, _args, { db }) => db.post.findMany({ where: { authorId: user.id } }),
  },
  Post: {
    comments: (post, _args, { db }) => db.comment.findMany({ where: { postId: post.id } }),
  },
};

The N+1 Problem & DataLoader

Field-level resolution is elegant, but it can quietly fire a flood of database queries. Consider:

query {
  posts(limit: 10) {
    title
    author { name }
  }
}

The posts resolver runs once (1 query), then the author resolver runs once per post (10 queries) — 11 queries for 10 posts. Scale that to a page of 100 items and the database groans. This is the same N+1 pattern we saw with REST, now on the server side.

DataLoader fixes this by batching all the individual loads that happen in a single tick into one query, and caching results per request:

import DataLoader from 'dataloader';

// Create fresh loaders for EACH request (never share across requests)
export function createLoaders(db) {
  return {
    userLoader: new DataLoader(async (userIds) => {
      const users = await db.user.findMany({ where: { id: { in: userIds } } });
      // Return in the SAME order as the requested ids
      const byId = new Map(users.map((u) => [u.id, u]));
      return userIds.map((id) => byId.get(id) ?? null);
    }),
  };
}

// In the resolver, load by key — DataLoader batches the calls
const resolvers = {
  Post: {
    author: (post, _args, { loaders }) => loaders.userLoader.load(post.authorId),
  },
};

Now those 10 author lookups collapse into a single WHERE id IN (...) query. Two rules matter: the batch function must return results in the exact order of the keys, and loaders must be created per request so their cache never leaks between users.

Auth & Error Handling

GraphQL has no built-in auth. The standard pattern is to authenticate once when building the context, then read context.user in resolvers.

import jwt from 'jsonwebtoken';

// Build context once per request
export async function buildContext({ req, db }) {
  const token = (req.headers.authorization ?? '').replace('Bearer ', '');
  let user = null;
  if (token) {
    try {
      const { userId } = jwt.verify(token, process.env.JWT_SECRET);
      user = await db.user.findUnique({ where: { id: userId } });
    } catch {
      // Invalid/expired token → treat as anonymous
    }
  }
  return { db, user, loaders: createLoaders(db) };
}

Throwing structured errors

For genuinely exceptional cases, throw a GraphQLError with an extensions.code so clients can branch on the machine-readable code rather than the message text:

import { GraphQLError } from 'graphql';

const resolvers = {
  Query: {
    me: (_p, _a, { user }) => {
      if (!user) {
        throw new GraphQLError('You must be logged in', {
          extensions: { code: 'UNAUTHENTICATED' },
        });
      }
      return user;
    },
    adminDashboard: (_p, _a, { user }) => {
      if (!user) throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED' } });
      if (user.role !== 'ADMIN') throw new GraphQLError('Forbidden', { extensions: { code: 'FORBIDDEN' } });
      return getDashboardData();
    },
  },
};

Two shapes of error

• Throw for exceptional failures (not authenticated, record truly missing, database down). These populate the top-level errors array.
• Return typed errors in a payload for expected validation problems ("email already in use", "password too short"), so the client can show field-level feedback.

Putting It Together

Here's a compact but complete Apollo Server v4 setup that combines resolvers, context, DataLoader, auth, and payload-based validation. (Assume typeDefs holds the SDL from the previous lesson and db is a Prisma-style client.)

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { GraphQLError } from 'graphql';
import bcrypt from 'bcrypt';
import jwt from 'jsonwebtoken';

const resolvers = {
  Query: {
    post: (_p, { id }, { db }) => db.post.findUnique({ where: { id } }),
    posts: (_p, { filter = {} }, { db }) =>
      db.post.findMany({ where: buildPostWhere(filter) }),
    me: (_p, _a, { user }) => {
      if (!user) throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED' } });
      return user;
    },
  },

  Mutation: {
    register: async (_p, { input }, { db }) => {
      const errors = [];
      if (!input.email.includes('@')) errors.push({ path: 'email', message: 'Invalid email' });
      if (input.password.length < 8) errors.push({ path: 'password', message: 'Password too short' });

      const existing = await db.user.findUnique({ where: { email: input.email } });
      if (existing) errors.push({ path: 'email', message: 'Email already in use' });
      if (errors.length) return { user: null, token: null, errors };

      const hashed = await bcrypt.hash(input.password, 10);
      const user = await db.user.create({ data: { ...input, password: hashed } });
      const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET, { expiresIn: '1d' });
      return { user, token, errors: [] };
    },

    createPost: async (_p, { input }, { db, user }) => {
      if (!user) return { post: null, errors: [{ path: 'auth', message: 'You must be logged in' }] };
      if (!input.title.trim()) return { post: null, errors: [{ path: 'title', message: 'Title required' }] };
      const post = await db.post.create({ data: { ...input, authorId: user.id } });
      return { post, errors: [] };
    },
  },

  // Type resolvers — batched to avoid N+1
  User: {
    posts: (user, _a, { loaders }) => loaders.postsByUserLoader.load(user.id),
  },
  Post: {
    author: (post, _a, { loaders }) => loaders.userLoader.load(post.authorId),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req }) => buildContext({ req, db }),
});

console.log(`🚀 Server ready at ${url}`);

Hands-on Exercise

type Query {
  post(id: ID!): Post
  me: User
}

type Mutation {
  createPost(input: CreatePostInput!): PostPayload!
}

type Post { id: ID! title: String! author: User! }
type User { id: ID! name: String! posts: [Post!]! }
type PostPayload { post: Post errors: [Error!]! }
type Error { path: String! message: String! }

input CreatePostInput { title: String! content: String! }

import { GraphQLError } from 'graphql';

const resolvers = {
  Query: {
    post: (_p, { id }, { db }) => db.post.findUnique({ where: { id } }),
    me: (_p, _a, { user }) => {
      if (!user) throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED' } });
      return user;
    },
  },
  Mutation: {
    createPost: async (_p, { input }, { db, user }) => {
      if (!user) return { post: null, errors: [{ path: 'auth', message: 'Log in first' }] };
      if (!input.title.trim()) return { post: null, errors: [{ path: 'title', message: 'Title required' }] };
      const post = await db.post.create({ data: { ...input, authorId: user.id } });
      return { post, errors: [] };
    },
  },
  User: {
    posts: (user, _a, { db }) => db.post.findMany({ where: { authorId: user.id } }),
  },
  Post: {
    author: (post, _a, { loaders }) => loaders.userLoader.load(post.authorId),
  },
};

Quiz

Summary

📚 Further Reading

• GraphQL.org — Queries and mutations
• Apollo Server — Resolvers
• DataLoader — Batching and caching
• Apollo Server — Error handling

🚀 What's Next?

You've now built a functional GraphQL API end to end. Next we zoom out from single services to system design — Microservices Design Principles — where GraphQL often acts as the gateway that stitches many services together.