Using nested mutations

Nested mutations enable to perform mutations on a type other than the root type in GraphQL.

The query below executes a standard mutation, using the mutation field updatePost from the root type:

mutation {
updatePost(id: 5, title: "New title") {
title
}
}

The query from above can also be executed through a nested mutation, where the post object is first queried through field post, and then mutation field update, which belongs to type Post, is applied on the post object:

mutation {
post(id: 5) {
update(title: "New title") {
title
}
}
}

Mutations can also be nested, modifying data on the result from another mutation:

mutation {
createPost(title: "First title") {
id
update(title: "Second title", content: "Some content") {
title
content
addComment(comment: "My first comment") {
id
content
date
}
}
}
}

Simplified root type permalink

Nested mutations change the root type, from QueryRoot and MutationRoot, to a single Root type handling both queries and mutations:

Nested mutations in the schema docs
Nested mutations in the schema docs

Visualizing mutation fields permalink

Use the Voyager client to visualize which are the mutation fields.

With nested mutations, every type in the schema can contain both query and mutation fields. To differentiate them, the mutation field's description is prepended with label "[Mutation] ".

For instance, these are the fields for type Root:

Description for type Root in the GraphiQL docs
Description for type Root in the GraphiQL docs

Using nested mutations permalink

There are 2 levels in which we can define if the schema will use nested mutations or not. In order of priority:

1. On the schema configuration permalink

Making a custom endpoint or persisted query use nested mutations, can be defined through the corresponding schema configuration:

Mutation scheme in the schema configuration
Mutation scheme in the schema configuration

2. Default mode, defined in the Settings permalink

If the schema configuration has value "Default", it will use the mode defined in the Settings:

Settings for nested mutations
Settings for nested mutations

Configuring nested mutations permalink

There are three behaviors we can choose for the schema:

1. Do no enable nested mutations permalink

This option disables nested mutations (using the standard behavior instead) for the schema.

2. Enable nested mutations, keeping all mutation fields in the root permalink

When nested mutations are enabled, mutation fields may be added two times to the schema:

  • once under the Root type
  • once under the specific type

For instance:

  • Root.updatePost
  • Post.update

With this option, the "duplicated" mutation fields from the root type are kept.

3. Enable nested mutations, removing the redundant mutation fields from the root permalink

Same option as above, but removing the "duplicated" mutation fields from the root type.

For instance:

  • Root.updatePost is removed
  • Post.update is available

GraphQL spec permalink

This functionality is currently not part of the GraphQL spec, but it has been requested: