Unlocking the Power of GraphQL in Sitecore: A Practical Guide to Queries, Mutations, and Fragments – Part 2

Hi Sitecore folks!,
Welcome back, fellow developers! In the previous post of our GraphQL series, we dived into the basics of querying for component data in Sitecore. If you missed it, be sure to check out [Unlocking the Power of GraphQL in Sitecore: A Guide to Useful Queries – Part 1].

In this second installment, we're going to take a deeper dive into some of the more advanced features of GraphQL: mutations, fragments, and some common queries. These powerful tools allow you to extend your GraphQL usage in Sitecore, making your development work more efficient and dynamic.

We'll walk through how to harness these features, explore real-life examples, and explain how they can streamline your content management workflows. Whether you’re new to GraphQL or a seasoned pro looking to sharpen your skills, this guide will provide you with the essentials to elevate your GraphQL game.

GraphQL Mutations: Modifying Data on the Server

GraphQL isn't just a tool for reading data—it also allows you to modify data via mutations. In Sitecore, mutations empower you to create, update, or delete items, templates, media, and more directly through GraphQL queries.

Unlike REST, which typically uses GET requests to retrieve data, GraphQL uses mutations to make changes to data. This distinction ensures that your data-modifying operations are organized and explicit, reducing the potential for confusion or errors.

Create Data with Mutations

Let's start by exploring a mutation for creating new items. This is useful when you're working with content that's frequently updated or needs to be programmatically generated. Here’s an example mutation for creating a new item in Sitecore:

mutation CreateItem {
  createItem(
    name: "Created MutationsItem"
    template: "{4330C04F-5CAA-4E93-A2B2-634900395E51}"
    parent: "{C081F940-3F38-4E10-8F43-B80AA63BC1BA}"
    language: "en"
    fields: [
      { name: "title", value: "New Item Created with Mutations" }
      { name: "subtitle", value: "This is a new Sitecore item created using mutations." }
    ]
  ) {
    path
    id
  }
}

This mutation will create a new item with a specific template, assign it to a parent item, and populate its fields (e.g., title and subtitle). The result will return the path and ID of the newly created item.

Update Data with Mutations

Next, let’s look at a mutation for updating an existing item. For example, if you need to update an item's title and subtitle, the mutation would look like this:

mutation UpdateItem {
  updateItem(
    path: "/sitecore/content/Home/MySampleProject/MutationsItem/CreatedMutationsItem"
    language: "en"
    version: 1
    fields: [
      { name: "title", value: "Updated Item Title" }
      { name: "subtitle", value: "Updated subtitle content for the item." }
    ]
  ) {
    title { value }
    subtitle { value }
  }
}

This mutation targets a specific item and updates its fields with the new values. The query also returns the updated title and subtitle fields.

Delete Data with Mutations

Mutations aren't just for creating and updating—they’re also powerful for deleting content. Here's an example of a mutation that deletes an item:

mutation DeleteItem {
  deleteItem(
    path: "/sitecore/content/Home/MySampleProject/MutationsItem/CreatedMutationsItem"
  )
}

Once executed, the specified item is removed from Sitecore’s content tree.

Fragments: Modularizing Queries for Reusability

As your queries become more complex, you may notice a lot of repetition in your field selections. This is where fragments come into play. A fragment allows you to define a set of fields once and reuse them across multiple queries. This makes your queries more modular, cleaner, and easier to maintain.

In Sitecore, you might be dealing with nested content types, so creating reusable fragments for fields like title and subtitle is incredibly helpful.

Here's an example where we define two fragments: RelatedItems and SubRelatedItems. Each fragment specifies the fields we need for those content types:

fragment RelatedItems on RelatedItems {
  title { value }
  subtitle { value }
}

fragment SubRelatedItems on SubRelatedItems {
  title { value }
  subtitle { value }
}

Now, you can use these fragments in your main query to fetch content in a cleaner, more efficient way:

query ContentCardQuery($datasource: String!) {
  datasource: item(path: $datasource, language: "en") {
    name
    newsItems: children(
      includeTemplateIDs: ["{B5D116DE-BFE8-4A06-A3FE-90C84320ECCB}"]
    ) {
      name
      ...RelatedItems
    }
    blogItems: children(
      includeTemplateIDs: ["{02CDBE64-254B-424B-90C3-E74FDBA02572}"]
    ) {
      name
      ...SubRelatedItems
    }
  }
}

By using inline fragment spreads (...RelatedItems and ...SubRelatedItems), this query is now much cleaner and more maintainable. The fragments handle the repetitive fields for you, and you only need to call them where necessary.

Fetching and Organizing Data Efficiently

GraphQL shines when it comes to fetching specific data. You can retrieve exactly what you need, reducing unnecessary requests and optimizing your application. Here’s an example where we query multiple data sources under a parent item, and we fetch only the required fields for news and blog items:

query ContentCardQuery($datasource: String!) {
  datasource: item(path: $datasource, language: "en") {
    name
    newsItems: children(
      includeTemplateIDs: ["{B5D116DE-BFE8-4A06-A3FE-90C84320ECCB}"]
    ) {
      name
      ... on RelatedItems {
        title { value }
        subtitle { value }
      }
    }
    blogItems: children(
      includeTemplateIDs: ["{02CDBE64-254B-424B-90C3-E74FDBA02572}"]
    ) {
      name
      ... on SubRelatedItems {
        title { value }
        subtitle { value }
      }
    }
  }
}

In this query, we use child item queries to pull news and blog items based on their specific templates. We then use fragments to ensure we fetch only the required fields for each item.

Conclusion: GraphQL’s Full Potential in Sitecore

GraphQL in Sitecore isn’t just a powerful tool for reading data; it offers a comprehensive way to manage and interact with content. By leveraging mutations for data creation, updates, and deletions, along with fragments for cleaner, reusable queries, you can optimize your Sitecore applications and workflows.

In this part of the series, we've covered the essential techniques for handling mutations and fragments, but we’re just scratching the surface. Stay tuned for Part 3, where we’ll dive into complex queries, variables, and directives—all the advanced tools you’ll need to become a GraphQL pro in Sitecore.

Until then, get hands-on with what we've covered, and experiment with mutations and fragments in your own projects. The more you practice, the easier it will get!

I hope you enjoy this Sitecore blog. Stay tuned for more Sitecore related articles.

Till that happy Sitecoring :)

Please leave your comments or share this article if it’s useful for you.