Skip to main content

"GraphQL" Nested Mutations

🛑 NO! ⛔

"Nested mutations" is the practice of performing side-effects in child fields of the mutation fields. This is explicitly forbidden by the GraphQL spec:

the resolution of fields other than top-level mutation fields must always be side effect-free and idempotent

Therefore, a schema using "nested mutations" is not a GraphQL schema — it does not comply with the GraphQL specification.

There's a number of reasons for this, but the most convincing one for me is that GraphQL is client-focussed and it's important for clients to have a mental model of what the server will do. If the server might perform mutations/side-effects anywhere then the client can't safely cache anything. However, if the client knows that mutations/side-effects only happen in specific locations (currently only in root-level mutation fields) then it can use this knowledge to factor into its caching and re-rendering strategies.

There are some RFCs proposed to address some of the desires behind nested mutations:


The term "nested mutations" has also been used by some people to describe the practice where a single mutation field accepts as input a nested tree of (possibly lists of) input objects which define the mutations to occur. All mutations still happen within this single root-level Mutation field, and thus this pattern is valid GraphQL (and is not the subject of this article).

A better name for this pattern might be "mutation" or "mutation with nested input objects".