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(input: {
    id: 5,
    title: "New title"
  }) {
    status
    errors {
      __typename
      ...on ErrorPayload {
        message
      }
    }
    post {
      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(by: {id: 5}) {
    update(input: {
      title: "New title"
    }) {
      status
      post {
        title
      }
    }
  }
}

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

mutation {
  createPost(input: {
    title: "First title"
  }) {
    status
    postID
    post {
      update(input: {
        title: "Second title",
        contentAs: { html: "Some content" }
      }) {
        status
        post {
          title
          content
          addComment(input: {
            commentAs: { html: "My first comment" }
          }) {
            status
            commentID
            comment {
              content
              date
            }
          }
        }
      }
    }
  }
}

Simplified root type

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

Visualizing mutation fields

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