Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Mutations in Apollo Kotlin

Mutations are GraphQL s that modify back-end data. As a convention in GraphQL, queries are read s and s are write operations.

Defining a mutation

You define a in your app just like you define a query, except you use the mutation keyword. Here's an example for upvoting a post:

mutation UpvotePost($postId: Int!) {
upvotePost(postId: $postId) {

And here's an example snippet that supports this :

type Mutation {
upvotePost(postId: Int!): Post
type Post {
id: Int!
votes: Int!
content: String!

The s of the Mutation type (such as upvotePost above) usually describe the actions that s can perform. These s usually take one or more s, which specify the data to create or modify.

Mutation return types

The return type of a Mutation usually includes the backend data that's been modified. This provides the requesting client with immediate information about the result of the .

In the example above, upvotePost returns the Post object that's just been upvoted. Here's an example response:

"data": {
"upvotePost": {
"id": "123",
"votes": 5

For more information on return types, see Designing mutations.

Generating mutation classes

Similar to queries, s are represented by instances of generated classes, conforming to the Mutation interface. Constructor s are used to define s. You pass a mutation object to ApolloClient#mutation(mutation) to send the to the server, execute it, and receive typed results:

val upvotePostMutation = UpvotePostMutation(postId = 3)
val response = try {
} catch(e: ApolloException) {
// handle error

Using fragments in mutation results

In many cases, you'll want to use results to update your UI. Fragments are a great way to share result handling between queries and s:

mutation UpvotePost($postId: Int!) {
upvotePost(postId: $postId) {

Passing input objects

The GraphQL type system includes input objects as a way to pass complex values to s. Input objects are often used for s, because they provide a compact way to pass in objects to be created:

mutation CreateReviewForEpisode($episode: Episode!, $review: ReviewInput!) {
createReview(episode: $episode, review: $review) {
val reviewInput = ReviewInput(stars = 5, commentary = "This is a great movie!")
try {
val response = apolloClient.mutation(CreateReviewForEpisodeMutation(episode = Episode.NEWHOPE, review = reviewInput)).execute()
} catch (e: ApolloException) {
// handle exception
Edit on GitHubEditForumsDiscord