Best practices and troubleshooting

Optimize Optimizely Graph queries and diagnose common integration issues in Optimizely Content Management System (SaaS). This article covers cached templates, single-item result shapes, and troubleshooting steps for authentication, missing data, field errors, and CORS issues.

Performance best practices

Apply the following techniques to reduce query latency and improve cache efficiency when working with Optimizely Graph in CMS (SaaS).

Use cached templates

Cached templates store the query shape on the server so repeat requests reuse the parsed query. Enable the stored flag in your client 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

When the query targets a single content item, request the item field rather than items. The item field returns one object, which the cache layer fingerprints more efficiently than a single-element array.

The following query has inefficient cache behavior for single results.

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

The following query has 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

Use the following checks to resolve common issues when working with Optimizely Graph and CMS (SaaS).

Common issues

The following checks address the most frequent failure modes during integration.

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

The following points describe behavior specific to CMS (SaaS) that affects how you author and query content.

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