TL;DR
GraphQL で、サーバ側のデータを作成・変更・削除する操作。Query と同じく、ルートの操作型(Mutation 型)のフィールドとして定義する。
なぜ必要か
GraphQL の仕様では、トップレベルの Mutation のフィールド以外は、副作用がなく冪等でなければならないとしている。REST で GET を使ってデータを変更しないのと同じように、データを変える操作を Query と分けて明示できる。
仕組み
Mutation の引数にはスカラーだけでなく入力オブジェクト型(input)を使って構造化した値を渡せる。Mutation がオブジェクト型を返すときは、Query と同じく取得するフィールドを選ぶ。変更した対象に関係する型を返すのが慣習で、クライアントは書き込んだあとの状態をそのまま受け取れる。
1 つのリクエストに複数のフィールドを書いたとき、Query のフィールドは並行して実行されるが、Mutation のフィールドは順番に実行される。そのため、前の Mutation が終わってから次の Mutation が始まり、競合が起きない。
例
input ReviewInput {
stars: Int!
commentary: String
}
type Mutation {
createReview(episode: Episode, review: ReviewInput!): Review
}汎用的な updateHuman のようなフィールドより、updateHumanName(id: ID!, name: String!): Human のように用途に合わせたフィールドを作ることが勧められている。
注意点
Mutation を順番に実行しても、データベースのトランザクションにはならない。最初の Mutation が成功して 2 つ目が失敗しても、GraphQL には最初の変更を取り消す仕組みはない。