✍️ Queries and Mutations

Two Kinds of Operation

Every GraphQL request is one of three operation types. Two of them matter today:

• Query — a read. It fetches data and, by convention, never changes anything. Queries can run in parallel.
• Mutation — a write. It creates, updates, or deletes, then returns the affected data. Mutations run in series, top to bottom, so one can't stomp another.

(The third, Subscription, pushes real-time updates over a WebSocket — a topic for later.) The syntax is nearly identical; the difference is intent and the root type each hangs off: type Query versus type Mutation.

# A read
query {
  book(id: "1") { title }
}

# A write — note the "mutation" keyword and Mutation-type field
mutation {
  addBook(title: "Dune", author: "Frank Herbert") { id title }
}

Arguments

Fields can accept arguments — the way a client narrows or parameterises what it wants. You've already used book(id: "1"); arguments also power filtering, limiting, and sorting.

query {
  # arguments filter and limit the result
  books(genre: "SCIFI", limit: 5) {
    title
    year
  }
}

On the server, arguments arrive as the resolver's second parameter:

const resolvers = {
  Query: {
    books: (_parent, { genre, limit }) => {
      let result = books;
      if (genre) result = result.filter((b) => b.genre === genre);
      if (limit) result = result.slice(0, limit);
      return result;
    },
  },
};

Arguments are declared in the schema with their types, and can carry defaults:

type Query {
  books(genre: String, limit: Int = 10): [Book!]!
}

Variables

Hard-coding id: "1" into a query string is fine in the Sandbox, but a real app needs the id to change at runtime. Variables let you write the query once and supply values separately — the GraphQL equivalent of parameterised SQL. They keep queries reusable and dodge string-concatenation bugs.

Declare variables in the operation signature with a $ prefix and a type, then use them by name:

query GetBook($id: ID!, $withReviews: Boolean!) {
  book(id: $id) {
    title
    year
    reviews @include(if: $withReviews) {
      rating
      text
    }
  }
}

The values travel alongside the query as a separate JSON object — never spliced into the string:

{
  "id": "1",
  "withReviews": true
}

That @include(if: ...) is a built-in directive: it conditionally includes a field based on a variable. Its sibling @skip(if: ...) does the reverse. Together they let one query serve several UI states.

Query → Resolver → Data

Here's the mental model that makes GraphQL click. When a query arrives, Apollo doesn't run one big function — it walks the query field by field, calling the resolver for each, passing each result down as the parent of its children. The response is assembled from the bottom up.

Mutations: Writing Data

A mutation is structurally just a field under type Mutation, but it carries a promise: running it changes server state. By convention its return type is the thing it affected, so the client can read back the fresh state in the same round trip.

type Mutation {
  addBook(title: String!, author: String!, year: Int): Book!
  updateBook(id: ID!, title: String): Book
  deleteBook(id: ID!): Boolean!
}

The resolvers live under a Mutation key, mirroring Query:

const resolvers = {
  Mutation: {
    addBook: (_, { title, author, year }, { user }) => {
      if (!user) throw new Error('You must be signed in');
      const book = { id: String(books.length + 1), title, author, year };
      books.push(book);
      return book;              // return the created object
    },

    updateBook: (_, { id, title }, { user }) => {
      if (!user) throw new Error('You must be signed in');
      const book = books.find((b) => b.id === id);
      if (!book) throw new Error(`Book ${id} not found`);
      if (title) book.title = title;
      return book;              // return the updated object
    },

    deleteBook: (_, { id }, { user }) => {
      if (!user?.isAdmin) throw new Error('Admins only');
      const i = books.findIndex((b) => b.id === id);
      if (i === -1) return false;
      books.splice(i, 1);
      return true;              // report success as a Boolean
    },
  },
};

Calling it, and reading back exactly the fields you care about:

mutation AddBook($title: String!, $author: String!) {
  addBook(title: $title, author: $author) {
    id
    title
  }
}

Input Types & Payloads

Once a mutation takes more than two or three arguments, listing them all gets unwieldy. GraphQL's answer is the input type — an object type used specifically for arguments. It groups related fields into one tidy parameter.

input AddBookInput {
  title: String!
  author: String!
  genre: String
  year: Int
}

type Mutation {
  addBook(input: AddBookInput!): Book!
}

mutation AddBook($input: AddBookInput!) {
  addBook(input: $input) {
    id
    title
  }
}

The payload pattern

For production mutations, many teams return a payload type instead of the bare object — a wrapper that can carry the entity and structured, per-field errors. This lets a mutation partially succeed and report validation problems the client can act on, rather than throwing a blanket error.

type UserError {
  message: String!
  field: String
}

type AddBookPayload {
  book: Book              # null if it failed
  errors: [UserError!]!   # empty on success
}

type Mutation {
  addBook(input: AddBookInput!): AddBookPayload!
}

addBook: (_, { input }) => {
  const errors = [];
  if (!input.title) errors.push({ message: 'Title is required', field: 'title' });
  if (errors.length) return { book: null, errors };

  const book = { id: String(books.length + 1), ...input };
  books.push(book);
  return { book, errors: [] };
},

The N+1 Problem

Now the performance trap the whole GraphQL world talks about. Consider this innocent-looking query:

query {
  books {          # 1 query: fetch all books
    title
    author {       # for EACH book, fetch its author...
      name
    }
  }
}

If there are 50 books, the naïve resolvers fire 1 query for the list of books, then 50 more — one per book — to fetch each author. That's N+1 database round trips for a single request. It scales linearly with your data and quietly destroys performance.

The root cause is the resolver-per-field model you learned last lesson: Book.author runs once per book, and each call looks up its author in isolation, with no idea the others are happening at the same time.

Fixing It with DataLoader

DataLoader is a tiny utility (from the GraphQL team) that solves N+1 with two tricks: batching and per-request caching. Instead of firing a query the instant each Book.author runs, DataLoader collects all the author ids requested during one tick of the event loop, then makes a single batched lookup for all of them.

npm install dataloader

import DataLoader from 'dataloader';

// The batch function receives an array of ALL keys requested this tick
function createLoaders(db) {
  return {
    authorLoader: new DataLoader(async (authorIds) => {
      // ONE query for every author id collected — not N queries
      const authors = await db.author.findMany({
        where: { id: { in: authorIds } },
      });
      // Must return results in the SAME order as the incoming ids
      return authorIds.map((id) => authors.find((a) => a.id === id));
    }),
  };
}

Build a fresh set of loaders per request in the context — the cache must not leak between users:

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req }) => ({
    user: await getUserFromToken(req),
    loaders: createLoaders(db),   // new loaders every request
  }),
});

Then the Book.author resolver simply defers to the loader:

const resolvers = {
  Book: {
    author: (book, _args, { loaders }) => loaders.authorLoader.load(book.authorId),
  },
};

Now those 50 author lookups collapse into one batched query. The .load(id) calls all happen synchronously in the same tick; DataLoader gathers the ids, runs the batch function once, and hands each resolver back its author.

Practice & Quiz

query SearchBooks($genre: String!, $limit: Int) {
  books(genre: $genre, limit: $limit) {
    title
    year
  }
}

{ "genre": "SCIFI", "limit": 5 }

input AddAuthorInput {
  name: String!
  bio: String
}

type Mutation {
  addAuthor(input: AddAuthorInput!): Author!
}

Mutation: {
  addAuthor: (_, { input }, { user }) => {
    if (!user) throw new Error('You must be signed in');
    const author = { id: String(authors.length + 1), ...input };
    authors.push(author);
    return author;
  },
},

Best Practices & Pitfalls

✅ Do

• Name your operations (query GetBook, mutation AddBook) — it aids debugging, caching, and analytics
• Pass runtime values as variables, never by concatenating them into the query string
• Give mutations verb-prefixed names (addBook, updateBook, deleteBook) and return the affected object
• Group multi-field mutation arguments into an input type
• Wrap every related-entity resolver in a DataLoader from day one

❌ Don't

• Do reads inside a mutation resolver's side effects, or writes inside a query — keep the intent honest
• Return only a Boolean from a create/update when the client needs the fresh object back
• Share a DataLoader across requests, or return batch results in the wrong order
• Reuse an output type as a mutation argument — inputs need the input keyword

Summary

📚 Additional Resources

• graphql.org — Queries and Mutations
• Apollo Server — Resolvers & arguments
• Apollo Server — Fetching data & batching
• DataLoader — official repository

🚀 What's Next?

You've now built a complete, performant GraphQL API — reads, writes, and no N+1. Next we shift from the server to the whole app experience: PWA principles, where you'll learn to make web apps installable, offline-capable, and native-feeling.