The Query and Mutation Types in GraphQL Schema (original) (raw)

Last Updated : 23 Jul, 2025

Imagine an **API that responds exactly as we wish, providing just the data we need in a single request. **GraphQL makes this dream a reality by offering a **flexible and **efficient approach to querying and manipulating data.

With its intuitive **syntax and powerful **features, GraphQL explains how developers design and interact with APIs, offering a more customized and streamlined experience for both **developers and **users.

In this article, We will learn about, The Query and Mutation Types in GraphQL Schema along with the components like **Query and mutations with the implementation of examples and so on.

Basic Components of GraphQL

**GraphQLis a **query language for **APIs and a **runtime for **executing those queries by using a type system we define for our data. Unlike traditional **REST APIs, **where clients have limited control over the structure of the responses, GraphQL allows clients to request only the data they need, in the format they need it.

GraphQL has several basic components that are essential to understand when working with it which are defined below are as follows:

**Schema
**Queries
**Mutations

1. Query

A **GraphQL query is a type of **read operation.
It is a request for specific data from a server.
**Clients use queries to specify the **structure of the response they need.
The server processes the **query and **returns the **requested data.

Defining the Schema

Let's define a sample query for **Blog Posts, with small queries.

import graphene

class Author(graphene.ObjectType):
id = graphene.Int(required=True)
name = graphene.String(required=True)
email = graphene.String(required=True)

class Post(graphene.ObjectType):
id = graphene.Int(required=True)
title = graphene.String(required=True)
content = graphene.String(required=True)
author = graphene.Field(Author, required=True)
createdAt = graphene.String(required=True)

class Query(graphene.ObjectType):
get_all_posts = graphene.List(Post, required=True, resolver=resolver_get_posts)
get_post_by_id = graphene.Field(Post, required=True, params=GetPostParams, resolver=resolver_get_post_by_id)

**Explanation:

In this schema, we have two types: **Author and **Post.
The **Post type includes basic fields id, title, content, author, and createdAt.
The **Author type includes basic fields like id, name, and email.
The **Query type includes two queries: **getAllPosts to fetch all blog posts and **getPostById to fetch a specific post by using its ID, we've defined a resolver (method which is to be called when this API is triggered), this resolver can take input (if any), processes your request and provide required response.

Resolvers For Query

def resolver_get_post_by_id(root, info, params):
post_id = params.post_id

authors = {  
    "1": {  
        "id": 1,  
        "name": "Dillip Chowdary",  
        "email": "dillip_chowdary@techbytes.app"  
    },  
    "2": {  
        "id": 2,  
        "name": "Narendra Modi",  
        "email": "modi@techbytes.app"  
    }  
}

posts_details = {  
   "1":{  
      "id":1,  
      "title":"Post_1",  
      "content":"Post Body",  
      "author_id":1  
   },  
   "2":{  
      "id":2,  
      "title":"Post_2",  
      "content":"Post Body 2",  
      "author_id":2  
   }  
}

post_details = post[post_id]

post_object = Post(  
            id=post_details["id"],  
            title=post_details["title"],  
            content=post_details["content"],  
            author=Author(  
                id=authors[post_details['author_id']]["id"],  
                name=authors[post_details['author_id']]["name"],  
                email=authors[post_details['author_id']]["email"]  
            )  
    )

return post_object

def resolver_get_posts(root, info):
authors = {
"1": {
"id": 1,
"name": "Dillip Chowdary",
"email": "dillip_chowdary@techbytes.app"
},
"2": {
"id": 2,
"name": "Narendra Modi",
"email": "modi@techbytes.app"
}
}

posts_details = [  
    {  
        "id": 1,  
        "title": "Post_1",  
        "content": "Post Body",  
        "author_id": 1  
    },  
    {  
        "id": 2,  
        "title": "Post_2",  
        "content": "Post Body 2",  
        "author_id": 2  
    }  
]

posts = [  
    Post(  
        id=post["id"],  
        title=post["title"],  
        content=post["content"],  
        author=Author(  
            id=authors[post['author_id']]["id"],  
            name=authors[post['author_id']]["name"],  
            email=authors[post['author_id']]["email"]  
        )  
    )  
    for post in posts_details  
]

return posts

schema = graphene.Schema(query=Query)

**Explanation:

**resolver_get_posts: Will return all posts, this method will return List of **Post type, it doesn't expect any input params.
**resolver_get_post_by_id: This method will expect a param **post_id, and return the post details, as defined, this method will return **Post type

Sample Query

Here is the sample API call seeking for post details, using the **getPostById query we've defined above, offcourse we can define the query type for creating, Updating or modifying operations but that's not a good practice, we're following the similar rule for REST APIs as well.

Use query if we're requesting the data, and Mutation if you're creating, modifying or deleting the data.

query {
getPostById(postId: "123") {
id
title
content
author {
name
}
}
}

**Response:

gql-query-response-(1)

Post Details we got in response to query

2. Mutation

A mutation in GraphQL is used for write operations, such as creating, updating, or deleting data on the server. It allows clients to modify data.
While a query is used for read operations, a mutation is specifically designed for write operations. This distinction helps in clearly defining the intent of an operation.
Mutations can modify data in the server's database, unlike queries which only fetch data. They are used when you need to change the state of the server or persist new data.
It's considered a good practice to use mutations for write operations, even though queries can technically be used to modify data as well. Using mutations explicitly indicates that the operation is intended to change data.

Defining the Schema

Let's define a sample query for Blog Posts, with one Mutation to **createPost:

import graphene

class CreatePost(graphene.Mutation):
class Arguments:
params = CreatePostParams(required=True)

Output = Post

@staticmethod  
def mutate(root, info, params):  
    post_details = {  
        "title": params.post.title,  
        "content": params.post.content,  
        "author_id": params.post.author_id  
    }

    create_post(post_details=post_details)

schema = graphene.Schema(query=Query, mutation=Mutation)

**Explanation:

In this schema, we have two types: **Author and **Post similar to Query schema example.
and in the schema we defined all the Mutations in the Type **Mutation
The **Mutation type includes one query: **createPost to create a blog post, here we're expecting **CreatePostParams as input type and we're returning the **Post.

Sample Query

Here is the sample API call to create the post using the mutation.

mutation {
createPost(input: {
title: "Introduction to GraphQL | GeeksforGeeks",
content: "GraphQL is a query language for APIs...",
authorId: "123"
})
{
id
title
content
author {
id
name
}
}
}

**Response:

gql-mutation-response-(1)

Mutation response upon creating a post

Combined Schema With Query and **Mutations

Here is the schema with both query & mutation (overall code)

Suppose we want to design a GraphQL schema for managing **blog posts and **authors. The schema should include types for **authors and **posts, with fields for **ID, name, email, title, content, and **creation date. Additionally, implement a **mutation for creating **new posts. The schema should support **queries for **retrieving all posts and retrieving a post by its **ID. Use dummy data for authors and posts for testing purposes.

import graphene

Define the Author object type

class Author(graphene.ObjectType):
id = graphene.Int(required=True)
name = graphene.String(required=True)
email = graphene.String(required=True)

Define the Post object type

Define the CreatePost mutation

class CreatePost(graphene.Mutation):
class Arguments:
title = graphene.String(required=True)
content = graphene.String(required=True)
author_id = graphene.Int(required=True)

Output = Post

@staticmethod  
def mutate(root, info, title, content, author_id):  
    # In a real implementation, this function would create the post in the database  
    # and return the created post object  
    return Post(  
        id=1,  # Replace with actual post ID  
        title=title,  
        content=content,  
        author=Author(  
            id=author_id,  
            name="Author Name",  # Replace with actual author name  
            email="author@example.com"  # Replace with actual author email  
        ),  
        createdAt="2022-03-24"  # Replace with actual creation date  
    )

Define the Query object type

class Query(graphene.ObjectType):
get_all_posts = graphene.List(Post, required=True) # Get all posts query
get_post_by_id = graphene.Field(Post, required=True, post_id=graphene.Int()) # Get post by ID query

def resolve_get_all_posts(root, info):  
    # Dummy data for posts  
    posts_details = [  
        {  
            "id": 1,  
            "title": "Post_1",  
            "content": "Post Body",  
            "author_id": 1  
        },  
        {  
            "id": 2,  
            "title": "Post_2",  
            "content": "Post Body 2",  
            "author_id": 2  
        }  
    ]

    authors = {  
        1: {  
            "id": 1,  
            "name": "Dillip Chowdary",  
            "email": "dillip_chowdary@techbytes.app"  
        },  
        2: {  
            "id": 2,  
            "name": "Narendra Modi",  
            "email": "modi@techbytes.app"  
        }  
    }

    # Create a list of Post objects with author details  
    return [  
        Post(  
            id=post["id"],  
            title=post["title"],  
            content=post["content"],  
            author=Author(  
                id=authors[post["author_id"]]["id"],  
                name=authors[post["author_id"]]["name"],  
                email=authors[post["author_id"]]["email"]  
            ),  
            createdAt="2022-03-24"  # Replace with actual creation date  
        )  
        for post in posts_details  
    ]

def resolve_get_post_by_id(root, info, post_id):  
    # Dummy data for posts  
    posts_details = {  
        1: {  
            "id": 1,  
            "title": "Post_1",  
            "content": "Post Body",  
            "author_id": 1  
        },  
        2: {  
            "id": 2,  
            "title": "Post_2",  
            "content": "Post Body 2",  
            "author_id": 2  
        }  
    }

    authors = {  
        1: {  
            "id": 1,  
            "name": "Dillip Chowdary",  
            "email": "dillip_chowdary@techbytes.app"  
        },  
        2: {  
            "id": 2,  
            "name": "Narendra Modi",  
            "email": "modi@techbytes.app"  
        }  
    }

    post_details = posts_details.get(post_id)

    if post_details:  
        return Post(  
            id=post_details["id"],  
            title=post_details["title"],  
            content=post_details["content"],  
            author=Author(  
                id=authors[post_details["author_id"]]["id"],  
                name=authors[post_details["author_id"]]["name"],  
                email=authors[post_details["author_id"]]["email"]  
            ),  
            createdAt="2022-03-24"  # Replace with actual creation date  
        )  
    else:  
        return None

Define the Mutation object type

class Mutation(graphene.ObjectType):
create_post = CreatePost.Field(required=True) # Define the create post mutation

Create the schema with Query and Mutation types

schema = graphene.Schema(query=Query, mutation=Mutation)

**Explanation: The provided code defines a GraphQL schema with object types for Author and Post, along with a Query object type for retrieving posts and a Mutation object type for creating posts.

The **Authorobject type represents the author of a post, with fields for I****D, name, and **email.
The **Post**object type represents a post, with fields for **ID, title, content, author (an Author object), and **creation date.
The CreatePost mutation allows the creation of a new post with the specified title, **content and **author ID.
The **get_all_posts**query retrieves a list of all posts with their details.
The **get_post_by_id**query retrieves a single post by its **ID.

These components together define a **GraphQL API for managing posts and authors.

Conclusion

In this post we've learnt the basics of GraphQL and the key differences between Query, Mutation and it's purposes with an sample blog post example.In this post we've seen how to define query, mutation, and writing resolvers for them.