Best practices

To ensure optimal performance and reliability with Optimizely Graph, it is important to understand query structuring and how to diagnose common integration issues. This section provides recommended best practices for improving query performance, including the use of cached templates and appropriate result shapes. It also outlines common troubleshooting steps for Optimizely Graph and Optimizely Content Management System (SaaS).

Performance best practices

Use cached templates

Use cached templates to improve query performance.

// In Apollo Client
const { data, loading, error } = useQuery(MY_QUERY, {
  variables: { stored: true } // Enable cached templates
});

var request = new GraphQLRequest 
{ 
    Query = query,
    Variables = new { stored = true } // Enable cached templates
};

Use "item" instead of "items" for single results

Inefficient cache behavior for single results.

query GetSingleLandingPage {
  LandingPage(where: { _metadata: { key: { eq: "specific-key" } } }) {
    items {  # Bad: uses items for single result
      _metadata { displayName }
    }
  }
}

Efficient cache behavior for single results.

  query GetSingleLandingPage {
  LandingPage(where: { _metadata: { key: { eq: "specific-key" } } }) {
    item {  # Good: uses item for single result
      _metadata { displayName }
    }
  }
}

Troubleshoot

Follow these steps to troubleshoot common issues when working with Optimizely Graph and CMS (SaaS).

Common issues

Authentication error (401)

• Verify that your API key is correct in the URL parameter or in the header.
• Check that your CMS (SaaS) instance is active and accessible.

No data returned

• Verify content is published in the CMS (SaaS) Visual Builder.
• Query _Content first to view available content.
• Verify that content type names match the schema exactly.

Field not found errors

• Use _metadata for system fields instead of direct properties.
• Content structure differs from traditional CMS 12.
• Explore the schema first with introspection queries.

CORS issues (browser)

• Use server-side rendering or API routes for production.
• Configure the proxy in your development environment.

CMS (SaaS)-specific tips

• Content types are created through the visual interface in CMS (SaaS).
• All content inherits from _Content with _metadata fields.
• URLs are managed automatically by the platform.
• Visual Builder provides real-time preview capabilities.