9. Introducing mutations
3m

Overview

So far, we've only dealt with retrieving data from our API. Now it's time to switch gears and work on modifying our data.

Each track in our app displays the number of times it's been viewed. We want to increment this number every time a user visits the track page from the homepage. We'll do this using !

http://localhost:3000/track/c_0

The track page, highlighting the track's number of views we wish to increment

In this lesson, we will:

  • Learn what a is
  • Test a in Explorer

The Mutation type

So far, our app has only used one type of : queries. These are read-only operations to retrieve data. To modify data, we need to use another type of GraphQL operation: mutations, which are write operations.

Much like the Query type, the Mutation type serves as an entry point to our schema. It follows the same syntax as the , or , that we've been using so far.

Schema syntax

In the schema of the , the Mutation type is declared using the type keyword, then the name Mutation. Inside the curly braces are the entry points: the we can use to mutate our data.

Illustration showing the schema syntax for adding a mutation

often start with a verb that describes the specific action of our update (such as add, delete, or create), followed by whatever data the acts on. Because mutations typically modify a specific object, they often require . The return type of the mutation comes after the colon.

The response should include the data that the mutation updated, so that our client can update its UI without having to run a followup to fetch those details!

We can take a closer look at our API's Mutation type by returning to the Schema page in Sandbox, and selecting Mutation from the left-hand menu.

http://studio.apollographql.com/sandbox/schema/reference

The Schema Reference page in Sandbox opened to the Mutation type

We can see that to increment the number of views on a specific track, this takes that track's id as an . It returns a type called IncrementTrackViewsResponse. Let's click on that type to take a closer look.

http://studio.apollographql.com/sandbox/schema/reference

The Schema Reference page in Sandbox, opened to the IncrementTrackViewsReponse type

The on this type show us the data we'll be able to when the completes. We can see the code, success, and message that results from the , and we also get access to the entire Track object that was modified under the track .

Working with mutations

To get going with this , let's return to the Mutation page and scroll down to the incrementTrackViews . To open this in the Explorer, let's click on the play icon to the right of the field's description.

https://studio.apollographql.com/sandbox/schema/reference

Screenshot of the Mutation field, incrementTrackViews, with the play button highlighted

This takes us to the Explorer page, with the sidebar open and ready for us to start building our first .

https://studio.apollographql.com/sandbox/explorer

Screenshot of Explorer with an empty Operation panel, ready for us to start building our query

Click the plus button () beside incrementTrackViews to add it to our Operation panel. This pre-fills some information for us!

mutation IncrementTrackViews($incrementTrackViewsId: ID!) {
incrementTrackViews(id: $incrementTrackViewsId) {
}
}

✍️ Building a GraphQL mutation

We start with the mutation keyword, and then the name of the (which the Explorer has named IncrementTrackViews for us). Inside the brackets, we've got a denoted by the $ symbol called incrementTrackViewsId, which is of type ID and required.

This is set in the Variables section below. Right now it's set to null, so let's change it to the same track ID we've been working with: c_0.

{
"incrementTrackViewsId": "c_0"
}
https://studio.apollographql.com/sandbox/explorer

Screenshot of Explorer with the mutation operated added, and a track Id variable filled in

Back to the in the Operation panel!

Inside the curly braces is where we list our entry point: incrementTrackViews. It takes in an id , which we set to the incrementTrackViewsId, the same one we just set to c_0.

Now inside the second pair of curly braces we can start to add the available in our response object. These fields are in the sidebar, making it really easy to build this by clicking on the plus button () button beside the .

We want to see the code, the success boolean, the message, and the track object itself.

Inside the track object, we want the id and the numberOfViews. The number of views is what we're updating, so we want to see the newly updated value after the is hopefully successful. The id will be used by our cache, which we'll cover a little later when we get to the frontend implementation.

https://studio.apollographql.com/sandbox/explorer

The complete mutation operation built out in the Explorer

The should look like this:

mutation IncrementTrackViews($incrementTrackViewsId: ID!) {
incrementTrackViews(id: $incrementTrackViewsId) {
code
success
message
track {
id
numberOfViews
}
}
}

Let's go ahead and run it!

On the right-hand side you can see the we expected: code is 200, the success flag is true, the message says it was successful and we get our newly updated track back.

https://studio.apollographql.com/sandbox/explorer

Screenshot of the Explorer showing a successful response to the IncrementTrackViews mutation

When we run the again and again, we can see that the number of views is going up!

Let's see what happens when we change the incrementTrackViewsId to our silly string "DOESNTEXIST".

{
"incrementTrackViewsId": "DOESNTEXIST"
}

When we run this , we see the response has code 404, success is false, and the message says Could not find track with specified ID. The track is also set to null with no data available.

https://studio.apollographql.com/sandbox/explorer

Screenshot of the Explorer showing a 404 response to the IncrementTrackViews mutation

Our looks great and it's doing what it's supposed to! It's time to bring this functionality into our app.

Practice

Mutations vs Queries
Queries and mutations are both types of GraphQL
 
. Queries are 
 
operations that always 
 
 data. Mutations are
 
 operations that always 
 
data. Similar to Query fields, fields of the 
 
 type are also 
 
 into a GraphQL API.

Drag items from this box to the blanks above

  • endpoints

  • create

  • write

  • assignments

  • Mutation

  • delete

  • retrieve

  • modify

  • entry points

  • read

  • operations

When writing a GraphQL mutation, which keyword should it start with?

Key takeaways

  • are write- that let us change data.
  • Like the Query type, the Mutation type acts as an entrypoint to our schema.

Up next

Our is built and running as we expect. Now for the final step: bringing it into our client-side code, and seeing our changes reflected in the UI!

Previous

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.