GraphQL Mutations

# CHAPTER 9

GraphQL Mutations #

1. Introduction #

2. Learning Objectives #

• Understand the conceptual difference between Queries and Mutations.

• Write Mutations for creating, updating, and deleting data (CRUD operations).

• Understand how mutations execute sequentially on the server.

• Request updated data in the response payload of a mutation.

3. Beginner-Friendly Explanation #

A Mutation is essentially a Query that is allowed to cause side-effects. It takes data from the client, saves it to the database, and then immediately asks, "Okay, the data is saved, what information do you want me to send back to you?"

4. Real-World Examples #

• Creating Data: Submitting a sign-up form creates a new User in the database.

• Updating Data: Clicking the "Like" button on a post increments the like count in the database.

• Deleting Data: Clicking the trash can icon on a shopping cart item removes the item from the database.

5. Detailed Code Examples #

The Schema:

type Task {
  id: ID!
  title: String!
  isCompleted: Boolean!
}

type Mutation {
  # Create
  createTask(title: String!): Task
  
  # Update
  toggleTaskStatus(id: ID!, isCompleted: Boolean!): Task
  
  # Delete
  deleteTask(id: ID!): Boolean
}

6. Query Examples (Execution) #

1. Create Operation:

mutation AddNewTask($title: String!) {
  createTask(title: $title) {
    id
    title
    isCompleted
  }
}

2. Update Operation:

mutation MarkTaskDone($taskId: ID!) {
  toggleTaskStatus(id: $taskId, isCompleted: true) {
    id
    isCompleted
  }
}

3. Delete Operation: Instead of returning a Task object (since it no longer exists), delete operations commonly return a Boolean or a custom payload indicating success.

mutation RemoveTask($taskId: ID!) {
  deleteTask(id: $taskId)
}

7. Mutation Responses and UI Updates #

8. Multiple Mutations Sequence #

mutation {
  # This executes first
  createTask(title: "First Task") { id }
  
  # This waits for the first to finish, then executes
  createTask(title: "Second Task") { id }
}

9. Best Practices #

• Return the Modified Object: Always return the object that was just created or updated. This keeps the client's cache (like Apollo Client) perfectly in sync with the server.

• Use Specific Names: Instead of a generic updateTask mutation, consider intent-based names like markTaskCompleted or changeTaskTitle. This clarifies business logic.

• Use Input Types for Large Updates: As learned in the previous chapter, if you are updating a user profile with 10 different fields, wrap them in an input UserProfileUpdateInput type.

10. Common Mistakes #

• Forgetting the Selection Set: Just like a Query, if a Mutation returns an Object Type (like Task), you must use curly braces {} to specify which fields of the Task you want returned.

• Using Queries for Modifications: Technically, you *could* write database update logic inside a GraphQL query. This is a massive anti-pattern. Queries should be strictly read-only.

11. Mini Exercises #

1. 1. If a mutation creates a new user, what scalar field should it absolutely return in its selection set? (Hint: The database generates it).

1. 2. Look at this schema: deleteUser(id: ID!): Boolean. Does the client need to use curly braces {} when calling this mutation?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain why GraphQL enforces that multiple mutations in a single request execute sequentially rather than in parallel.

• Q: How should a delete mutation be structured in terms of its return type?

• Q: Is there any technical difference in how the server processes the payload of a Query vs a Mutation, or is it just a naming convention?

15. FAQs #

Q: What happens if one mutation fails in a sequential list of mutations? A: Usually, the server will process the mutations up until the failure. The failed mutation will return an error in the errors array, and subsequent mutations in the list will not execute.

16. Summary #

17. Next Chapter Recommendation #