As opposed to queries, mutations in GraphQL represent operations that modify server-side data and/or cause side effects on the server. For example, you can have a mutation that creates a new instance in your application or a mutation that sends an email. Like in queries, they accept parameters and can return anything a regular field can, including new types and existing object types. This can be useful for fetching the new state of an object after an update.
Let’s improve our books project from the Getting started tutorial and implement a mutation that is supposed to add a book:
Like queries, mutations are defined in a class that is then passed to the Schema
function. Here we create an
addBook mutation that accepts a title and an
author and returns a
We would send the following GraphQL document to our server to execute the mutation:
addBook mutation is a simplified example. In a real-world application
mutations will often need to handle errors and communicate those errors back to
the client. For example we might want to return an error if the book already
You can checkout our documentation on dealing with errors to learn how to return a union of types from a mutation.
Mutations without returned data
It is also possible to write a mutation that doesn’t return anything.
This is mapped to a
Void GraphQL scalar, and always returns
Mutations with void-result go against this community-created guide on GQL best practices .
The Input Mutation Extension
It is usually useful to use a pattern of defining a mutation that receives a
single input type argument called
Strawberry provides a helper to create a mutation that automatically creates an input type for you, whose attributes are the same as the args in the resolver.
For example, suppose we want the mutation defined in the section above to be an
input mutation. We can add the
InputMutationExtension to the field like this:
That would generate a schema like this:
To avoid a graph becoming too large and to improve discoverability, it can be helpful to group mutations in a namespace, as described by Apollo's guide on Namespacing by separation of concerns .
Since all GraphQL operations are fields, we can define a
and add mutation fields to it like we could add mutation fields to the root
Fields on the root `Mutation` type are resolved serially. Namespace types introduce the potential for mutations to be resolved asynchronously and in parallel because the mutation fields that mutate data are no longer at the root level.
To guarantee serial execution when namespace types are used, clients should use
aliases to select the root mutation field for each mutation. In the following
addFruit execution is complete,