Known limitations and workarounds
Understand Optimizely Graph platform constraints and recommended workarounds for query design, sync behavior, and data modeling.
Understand platform constraints that affect query design, synchronization behavior, and data modeling. Each limitation includes a recommended workaround.
Content and synchronization constraints
Content synchronization latency
Content synchronization is not instant. Typical latency: 5 to 15 minutes for scheduled sync, 1 to 3 seconds for event-driven sync on small changes (longer for bulk updates).
Workaround
Use event-driven synchronization for near-real-time updates. Set appropriate expectations for content editors. Implement cache-warming strategies for critical content. Use webhooks to trigger front-end rebuilds after sync. See Manage webhooks.
Schema update delays
Schema changes (new content types or fields) require synchronization and take several minutes to propagate.
Workaround
Plan schema changes during maintenance windows. Test schema changes in non-production environments first. Wait 5 to 10 minutes after schema changes before deploying dependent code. Verify schema updates using introspection queries before deployment.
Large content items
Content items larger than 1 MB cause performance issues or timeouts.
Workaround
Paginate large rich text content. Store large media files separately and reference them by URL. Use content references instead of embedding large child content. Split large content items into smaller linked items.
Multi-language content behavior
Fallback language behavior does not match CMS fallback exactly in all scenarios.
Workaround
Review Fallback languages. Query for specific locales explicitly when fallback behavior is critical. Test multi-language scenarios thoroughly in non-production environments.
Read-only API (no mutations)
Optimizely Graph is read-only. It does not support GraphQL mutations for writing or updating data.
Workaround
Use CMS APIs to create or update content. Content changes in CMS synchronize to Graph automatically. For external data, use the content synchronization API.
Search and integration constraints
No real-time subscriptions
Optimizely Graph does not support GraphQL subscriptions for real-time push updates.
Workaround
Use webhooks to trigger updates in your application. Implement polling for near-real-time updates (with rate-limiting consideration). Use an event-driven architecture for real-time requirements.
File and media limits
Media files (images, PDFs, and videos) are referenced by URL only. Binary content is not stored in Graph. Media metadata is limited.
Workaround
Store media in a CDN or media library. Reference media URLs in Graph content. Query media metadata fields separately if needed. Use CMS APIs for full media information.