Introduction to Mutations: Modifying Data in GraphQL

Previously in this course, we explored the resolver signature and how to pass data through the context object. Up to this point, our API has been entirely "read-only"—we've only been fetching data.

In real-world applications, however, your API must be able to change things: create users, update settings, or delete records. This is where Mutations come in.

Understanding Mutations vs. Queries

In GraphQL, we categorize operations into two primary buckets based on their intent: Queries and Mutations.

While both are just fields in your schema, they represent different architectural intentions:

When a client sends a query, the server assumes it is safe to execute multiple fields simultaneously. Because mutations often involve writing to a database or updating server-side state, GraphQL ensures these are processed sequentially to avoid "race conditions"—where two simultaneous writes might corrupt your data.

Defining a Mutation Type

Just as we defined a Query type in our schema to act as the entry point for fetching data, we define a Mutation type to act as the entry point for data modification.

If you have been defining custom object types, you already know the SDL (Schema Definition Language). Adding a mutation follows that same pattern:

GraphQL
type Mutation {
  # We define the mutation name and the data it returns
  createItem(name: String!): Item!
}

In this example, createItem is the name of the operation. Just like a query, it takes arguments (in this case, a name) and returns an object (an Item). By returning the Item we just created, the client can immediately update its local cache without needing a follow-up query.

The Role of Schema Contracts

A common pitfall for beginners is thinking that a mutation must change data. In reality, a mutation is just a field with a "side effect." The schema contract requires you to be explicit about what the mutation returns.

When you enforce data with non-null fields, you ensure that your API consumers always receive a predictable response, even after a write operation. Always return the modified object (or at least its ID) so the client knows the operation succeeded and what the resulting state looks like.

Hands-on Exercise: Structuring Your Mutation

For our project, we are building a library API. Let's add the ability to add a new book to our list.

1. Open your typeDefs.
2. Add a Mutation type.
3. Define a field named addBook that accepts a title (String) and an author (String).
4. Ensure it returns the Book object type.

GraphQL
type Mutation {
  addBook(title: String!, author: String!): Book!
}

Common Pitfall: Many developers try to use the Query type for modifications. If you see a feature that "deletes" or "updates" something, it must be under the Mutation type. If you place a write operation under Query, your API will violate the architectural design of GraphQL, making it harder for caches and tools to understand which operations are safe to retry and which are destructive.

Recap

• Mutations are the standard GraphQL mechanism for modifying data.
• Queries are for reading; Mutations are for writing.
• Mutations are executed in sequence, while Queries are executed in parallel.
• Always return the modified object from your mutation so the client can stay in sync.

Up next, we will move from the schema definition to the implementation by Implementing a Simple Mutation in our server-side code.