The Query and Mutation Types in GraphQL Schema

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

GraphQL is 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:

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:

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
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)

# 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 Author object type represents the author of a post, with fields for ID, 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.

Article Tags :

GraphQL