Mutations — How Writes Work in GraphQL

What you'll walk away with

Explain the core ideas behind Mutations — How Writes Work in GraphQL
Run the sample GraphQL query or code and verify its output
Apply the technique correctly to the Tutorial Platform and production scenarios

Build the mental model

GraphQL separates reads with the `query` operation type from writes with `mutation`. Top-level query fields can execute in parallel, but top-level mutation fields execute serially, one after another, keeping side-effect order predictable. By convention, a mutation should return the object it just changed so the client sees the updated state immediately without a follow-up query.

Connect it to a real scenario

When an author publishes a tutorial on the Tutorial Platform, the frontend calls `publishTutorial(id: $id)` and immediately gets back the updated `status` and `publishedAt`, so it can apply an optimistic UI update right away.

query reads, mutation writes
Top-level mutation fields execute serially
A mutation should return the object it changed

Try the working example

graphql

mutation PublishTutorial($id: ID!) {
  publishTutorial(id: $id) {
    id
    status
    publishedAt
  }
}

# variables: { "id": "42" }

You should see

You can write a mutation operation and read back the state it changed.

5-minute try-it

Design an `archiveTutorial(id: ID!)` mutation and write a selection set that returns the updated `status` field.

One important caution

Do not perform side effects inside a `query` operation's fields — the GraphQL spec assumes query fields are side-effect-free, idempotent reads.

GraphQL — Queries and Mutations — GraphQL

Easy traps

Do not perform side effects inside a `query` operation's fields — the GraphQL spec assumes query fields are side-effect-free, idempotent reads.
Validate sample queries and mutations on a local or test server with recoverable data before applying them to production.

Exercise

Design an `archiveTutorial(id: ID!)` mutation and write a selection set that returns the updated `status` field.

You'll know it worked when: You can write a mutation operation and read back the state it changed.