Mutations

Key points

• Anything that changes state goes under type Mutation, never under Query.
• Top-level mutation fields run in series, in document order - queries may run in parallel.
• Return the modified object so the client can update its cache without a second round trip.
• A payload type carrying both the result and user-facing errors beats throwing for expected failures.
• Use input types for arguments: they are reusable and keep signatures readable.

Example

input PlaceOrderInput {
  customerId: ID!
  product: String!
  quantity: Int! = 1
}

type PlaceOrderPayload {
  order: Order              # null when it failed
  errors: [UserError!]!     # expected, user-facing problems
}

type Mutation {
  placeOrder(input: PlaceOrderInput!): PlaceOrderPayload!
}

Return the changed object: it turns a write plus a refetch into a single round trip.