Writing Mutations with Input Types

Mutations are the GraphQL operation for creating, updating, or deleting data. Unlike queries, mutations are executed serially when multiple are sent in one request, guaranteeing ordered side effects. Every mutation should return the affected resource so clients can update their local cache without refetching. Using a single input object type as the argument (rather than individual scalar arguments) makes mutations forward-compatible—new optional fields can be added to the input type without changing the mutation signature.

Example

# Schema
input CreatePostInput {
  title: String!
  body: String!
  authorId: ID!
  tags: [String!]
  publishNow: Boolean = false
}

input UpdatePostInput {
  title: String
  body: String
  tags: [String!]
}

type MutationResult {
  success: Boolean!
  message: String
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
  deletePost(id: ID!): MutationResult!
  publishPost(id: ID!): Post!
}

# Client mutation with variables
mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    author { name }
    createdAt
  }
}

# Variables:
# {
#   "input": {
#     "title": "GraphQL Mutations",
#     "body": "Mutations write data...",
#     "authorId": "3",
#     "tags": ["graphql", "api"],
#     "publishNow": true
#   }
# }

HTML

Full Editor

Related Resources

GraphQL Reference

Complete tag & property list

GraphQL How-To Guides

Step-by-step practical guides

GraphQL Exercises

Practice what you've learned