GraphQL Queries Improvements

In this section, we'll explore advanced techniques to optimize your GraphQL queries in Optimizely Graph. These optimizations can significantly improve performance, especially for complex queries or high-traffic applications.

Using item Instead of items for Single Elements

One of the simplest yet most effective ways to boost your GraphQL query performance is to use the item query when you need to fetch a single content item, rather than using items with filters.

The Problem with Using items for Single Elements

When you use the items query with filters to retrieve a single item, Optimizely Graph has to:

Scan through potentially many content items Apply the filter conditions Return only the matching item This process is inefficient when you already know the unique identifier of the item you want.

The Solution: Direct item Queries

Instead of:

query getPageByURL($locales: [Locales], $slug: String) {
  CMSPage(
    locale: $locales
    where: { _metadata: { url: { default: { eq: $slug } } } }
  ) {
    items {
      title
      shortDescription
      keywords
      _modified
      blocks {
        ...ItemsInContentArea
      }
    }
  }
}

Use:

query getPageByURL($locales: [Locales], $slug: String) {
  CMSPage(
    locale: $locales
    where: { _metadata: { url: { default: { eq: $slug } } } }
  ) {
    item {
      title
      shortDescription
      keywords
      _modified
      blocks {
        ...ItemsInContentArea
      }
    }
  }
}

This approach:

• Reduces processing time
• Decreases memory usage
• Improves overall query performance

More information about this: Optimizely Graph Cache: The Power of "Item"

Boosting Performance with Stored Templates

For more advanced performance optimization, Optimizely Graph offers Cached Templates.

How Cached Templates Work

Cached Templates significantly improve query performance by pre-processing and caching translated queries as templates. Here's how they work:

1. The first time you execute a query, the system generates a template with placeholders for variable values
2. This template is stored in the cache
3. Subsequent requests using the same query structure but different variables skip the translation step
4. The system simply inserts the new variable values into the cached template

This process eliminates the need for repeated query translation, resulting in substantial performance improvements, especially for complex queries.

How to Activate Cached Templates

Activating Cached Templates is straightforward:

1. Add the stored=true query string parameter to your GraphQL endpoint URL
2. Include the cg-stored-query: template header in your HTTP request

For example:

POST https://cg.optimizely.com/content/v2?auth=${OPTIMIZELY_SINGLE_KEY}&stored=true
Headers:
  cg-stored-query: template
  Content-Type: application/json

The service will automatically handle template generation and caching, improving the efficiency of subsequent requests with the same query structure.

Supported Variable Types

Cached Templates support the following variable types:

• Boolean
• Date
• DateTime
• String
• Int
• Float
• Locales
• [Locales]

Important: For Locales and [Locales] types, the variable name must be 'locale'. Any other variable types will result in a fallback to 'Cached Queries'.

Cached Templates vs. Cached Queries

While Cached Templates are the preferred optimization method, the system also supports Cached Queries:

• Cached Templates: Cache the query structure with placeholders for variables
• Cached Queries: Cache fully resolved queries (the complete query with specific variable values)

Cached Queries act as a backup for queries that are incompatible with the Cached Templates system, ensuring performance improvements even for edge cases.

When to Use Cached Templates

Note: Apply Cached Templates when you're facing performance issues with complex or frequently used queries. Later this year (2025), Cached Templates will be enabled by default for all requests in Optimizely Graph, but until then, you'll need to implement them manually for performance-critical operations.

Good candidates for Cached Templates include:

• Navigation menus
• Product detail pages
• Article listings
• Search results
• Any query that runs frequently with minimal changes

Implementation Strategy

1. Start by optimizing single-item lookups using the item query
2. Monitor performance and identify bottlenecks
3. For queries that still have performance issues, implement Cached Templates
4. Regularly review your most expensive queries for optimization opportunities

More information about Cached Templates : Boosting Graph Query Performance with Cached Templates

Performance Impact in Different Scenarios

By applying these techniques, you can improve the performance of your Optimizely Graph implementation, but the impact will vary depending on your project architecture:

Note: In projects where all pages use Static Site Generation (SSG) with on-demand revalidation triggered by content updates, the performance improvements will be more modest. You'll primarily see improvements in build time and in the time it takes for pages to revalidate after publish events, but these won't be dramatic improvements.

However, if your project makes GraphQL fetches client-side or uses server-side rendering (SSR), the performance improvements will be much more significant and directly impact user experience. In these scenarios, implementing these optimizations becomes especially valuable.

Consider your project's architecture and data fetching patterns when deciding which optimizations to prioritize. Even in SSG projects, these optimizations are still worth implementing as they can improve developer experience during builds and reduce the time it takes for content changes to appear on your site.