The difference between Mutation and Query

Question

I'm reading GraphQL Docs about Query and Mutation. However, there is a lack of real examples which shows the difference and most importantly — when is it appropriate to use them.

Many thanks for the explanations.

Answer 1

Short

Conventionally:

• Query — for querying data (SELECT operations)
• Mutation — for creating new and updating/deleting existing data (INSERT, UPDATE, DELETE)

Detailed

Technically any GraphQL query could be implemented to cause a data write. But there is a convention that any operations that cause writes should be sent explicitly via a mutation.

Besides the difference in the semantic, there is one important technical difference:

Query fields can be executed in parallel by the GraphQL engine while Mutation top-level fields MUST execute serially according to the spec:

If the operation is a mutation, the result of the operation is the result of executing the mutation’s top level selection set on the mutation root object type. This selection set should be executed serially.

It is expected that the top level fields in a mutation operation perform side‐effects on the underlying data system. Serial execution of the provided mutations ensures against race conditions during these side‐effects.

Source: https://graphql.github.io/graphql-spec/draft/#sec-Mutation