Best practices and troubleshooting

Optimize your Optimizely Graph queries and frontend performance by following these best practices. This section covers techniques such as using cached templates to reduce server load and improving query efficiency by selecting item instead of items when fetching single results. Implementing these strategies helps your application load content faster and reduces unnecessary data processing.

Performance Best Practices

1. 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
};

2. Use "item" vs "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 }
    }
  }
}

Troubleshooting

Follow these steps to troubleshoot common issues when working with Optimizely Graph and SaaS CMS, helping you quickly identify and resolve authentication, data, schema, and browser-related problems.

Common Issues

Authentication Error (401)

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

No Data Returned

• Verify content is published in the SaaS CMS 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

SaaS CMS Specific Tips

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