Getting Started with GraphQL Queries in Sitecore: A Practical Guide

Introduction

GraphQL in Sitecore provides a powerful and flexible way to interact with content programmatically. In this guide, we'll explore how to set up GraphQL in Sitecore and implement various query operations for building efficient headless applications.

Sitecore GraphQL API framework:

•       Queries (reading data)

•       Mutations (altering data)

•       Subscriptions (subscribing to real-time updates of data)



Setting Up GraphQL in Sitecore

•       Navigate to the `App_config` folder in your Sitecore root directory

•       Locate the `Services.GraphQL` folder

•       Rename the file “Sitecore.Services.GraphQL.Content.Master.config.example” to “Sitecore.Services.GraphQL.Content.Master.config”.

Add Authentication

Enable GraphQL using API Key

•       Open AppConfig\Sitecore\Services.GraphQL\Sitecore.Services.GraphQL.config

•       In security section make the following changes


Enable site-neutral paths

•       Browsing Sitecore instance URL may give Authentication error as below

•       modify the Sitecore.Owin.Authentication.Config file to include site-neutral paths.

•       go to the Sitecore installation folder path

•       :\inetpub\wwwroot[SC installed folder]\App_Config\Sitecore\Owin.Authentication.

•       find the Sitecore.Owin.Authentication.Config file to edit.

•       search “siteNeutralPaths” node and add the path “/sitecore/api/graph/items/” underneath it and save the changes.


Check GraphQL query in playground

•       Open the Rendering

•       Go to GraphQL section

•       Click “Open Xgraph Browser”



To execute query, we need to add two things

HTTP HEADERS: pass the API key

QUERY VARIABLE: pass contextItem path

Adding API Key to Sitecore

•       Go to the location /sitecore/system/Settings/Services/API Keys

•       Right click on the API Keys folder and insert a new API Key

•       Give API Key a unique name

•       Insert * in CORS Origins and Allowed Controllers fields


Template and content structure for example

We defined a structure of Leaders and Team members as below to perform query operations




Settings and Queries:


HTTP HEADERS 
{
     "sc_apikey":"{00000000-0000-0000-0000-000000000000}"
}
QUARY VARIABLE 
{
     "datasource":"/sitecore/content/Home/DemoProject/Home/About"
}


1. Get Name and Value for all the fields including standard fields 

query GQLAllFieldsNameValueQuery($datasource: String!) {
  item(path: $datasource, language: "en") {
    fields
    {
      name
      value
    }
  }
}




2. Get own fields - to get only own template fields/excludes standard fields

query GQLGetOnlyTemplateFieldsQuery($datasource: String!) {
  item(path: $datasource, language: "en") {
    fields(ownFields: true) {
      id
      name
      value
    }
  }
}

3. Query to get mentioned fields of the template item

query GetItemTemplateFieldsGQLQuery($datasource: String!) {
  responseData: item(path: $datasource, language: "en") {
    id
    name
    ... on About {
      title {
        value
      }
      subtitle {
        value
      }
      image {
        alt
        src
      }
      link {
        url
      }
      date {
        value
      }
      isTrue {
        value
      }
    }
  }
}


4. Get children based on given template 

query GQLFilterByTemplateQuery($datasource: String!) {
  item(path: $datasource, language: "en") {
    children {
      ... on Leader {
        id
        name
        department{
           value
         }
        module{
           value
         }
      }
    }
  }
}

5. Get Multilist/treelist fields

query GQLGetMultilistItemsQuery($datasource: String!) {
  responseData: item(path: $datasource, language: "en") {
    id
    name
    ... on About {
      title {
        value
      }
      subtitle {
        value
      }
      image {
        alt
        src
      }
      multiListItems {
        id
        name
        targetItems {
          id
          name
          ... on Leader {
            department {
              value
            }
            leaders {
               id
               name
               targetItems {
                id
                name
                ... on LeaderDetailsHead{
                  type{
                    value
                  }
                  bio{
                    value
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

6. Get field values using Alias

query GQLGetFieldWithAliasQuery($datasource: String!) {
  responseData: item(path: $datasource, language: "en") {
    RootItemId: id
    ... on About {
      Title: subtitle {
        value
      }
      Subtitle: description {
        value
      }
    }
  }
}



7. Search based on a field value

{
  search(fieldsEqual:[{name:"Name", value:"Nidhi" }]  
    rootItem: "/sitecore/content/Home/DemoProject/Home/About/Leaders/PM") {
    results {
      items {
        item {
          id
          name
          path
          url
          FirstName: field(name  : "Name") {
           value
          }
         Designation: field(name  : "Designation") {
           value
          }
          Bio: field(name  : "Bio") {
           value
          }
        }
      }
      totalCount
    }
  }
}

8. Search based on a keyword

{
  search(keyword:"TL"
  rootItem:"/sitecore/content/Home/DemoProject/Home"
  ) {
    results {
      totalCount,
      items{
        id
        name
        path
      }
    }
  }
}

9. Getting multiple data source items data

query GetDataFromMultipleSourceQuery($datasource: String!) {
  responseData: item(path: $datasource, language: "en") {
    name
    Leaders: children(
      includeTemplateIDs: ["{B5D116DE-BFE8-4A06-A3FE-90C84320ECCB}"]
    ) {
      name
      ... on Leader{
        department{
          value
        }
      }
    }
    Team: children(
      includeTemplateIDs: ["{1D1B624B-3D93-496C-9E0F-D5417B4B3CA0}"]
    ) {
      name
      ... on Team{
        department{
          value
        }
      }
    }
  }
}


10. To see full layout - Experience edge only

query {
  layout(site: "DemoProject", routePath: "/", language: "en") {
     item {
      rendered
    }
  }
}


When implementing GraphQL queries in Sitecore, take care of below points:

 1. Security

   - Always implement proper authentication

   - Use API keys securely

   - Restrict access to sensitive data

 

2. Performance

   - Monitor query performance

   - Implement proper caching strategies

   - Optimize query structure

 

3. Error Handling

   - Implement comprehensive error handling

   - Validate input data

   - Handle null values appropriately

 

4. Content Modeling

   - Follow Sitecore's best practices

   - Use appropriate field types

   - Structure content hierarchically

 

Next Steps

This guide covers the fundamentals of GraphQL queries in Sitecore. In upcoming posts, we'll explore:

- Mutations for content manipulation

- Using Fragments for query optimization

- Advanced search operations

- Integration with frontend frameworks

 

Stay tuned for more detailed explorations of these topics!


Comments

Post a Comment

Popular posts from this blog

Setting Up Sitecore Headless with Next.js in Disconnected Mode

Image
Sitecore Headless CMS offers a flexible way to integrate with different frontend technologies. For developers working with frameworks like Next.js, Sitecore provides various ways to set up the environment, including four distinct modes: Disconnected Mode , Connected Mode , Integrated Mode , and API Mode . Each mode offers unique features for different stages of development and production needs. What Is Disconnected Mode? Disconnected Mode is designed for local development and testing without requiring a direct connection to the Sitecore platform. In this mode, data is typically retrieved from static files (like YAML or JSON), and content updates are done manually. This mode is ideal for frontend developers who want to focus on building the user interface and the site’s functionality without waiting for backend integration. In Disconnected Mode , the data flow is not dependent on the Sitecore CMS. Instead, content is stored locally in static files, which are easier to manage and qu...
Read more

Translating Sitecore items’ field values into different language with PowerShell and Translate API

Image
Recently, we encountered a situation where we needed to translate multiple Sitecore field values across numerous items into different languages. Manually handling each item and field was both time-consuming and complex—especially since actual translation was required, not just copying values between language versions. We explored various approaches to streamline the process. While AI-based solutions seemed promising, but client side Compliances for AI usage ruled out that option. Another practical alternative was to use spreadsheets like Excel or CSV files containing translated content and then import those values into Sitecore using PowerShell scripts. During our exploration, we discovered a freely accessible translation API that doesn't require an API key. By leveraging this in our PowerShell script, we were able to automate the translation process and directly apply the translated content to the appropriate language versions of the Sitecore items—saving both time and effort. ...
Read more

Create Sitecore Ribbon Button using Sitecore PowerShell Extensions

Image
Creating a custom Ribbon button in Sitecore using Sitecore PowerShell Extensions (SPE) involves several steps, which I'll guide you through below. The general process includes Create PowerShell Script Module and Add Integration Point Setup the PowerShell script Library and Add PowerShell script Configuring the Ribbon button and Sync Verify the button in the Ribbon Here's how we can achieve that: Pre-Requisites: Running Sitecore Instance PowerShell ISE to run PowerShell script (Install compatible Sitecore.PowerShell.Extensions if it’s not there) Step-1: Create PowerShell Script Module and Add Integration Point Create PowerShell Script Module: Go to Content Editor . In the content tree, navigate to: System > Modules > PowerShell > Script Library . Right-click on Script Library and select Insert > PowerShell Script Module . Give it a name, su...
Read more