Known limitations and workarounds

Queries with excessive depth or breadth are rejected or time out.

Workaround
Limit query depth to five levels or fewer. Use pagination for large result sets. Break complex queries into multiple focused queries. Use cached templates for frequently used queries.

Maximum query size is 10,000 characters. Maximum query depth is 10 levels (five or fewer recommended). Maximum execution time is 30 seconds.

Workaround
Break large queries into smaller, focused queries. Use pagination to limit result sizes. Flatten deeply nested data structures.

API requests are subject to rate limiting based on your plan: 100 requests per minute for standard plans, custom limits for enterprise contracts.

Workaround
Implement request batching where possible. Use caching to reduce query frequency. Implement exponential backoff for 429 responses. Contact support for rate limit increases if needed.

For error handling patterns, see Error handling and rate limits.

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 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.

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.

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.

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.

Maximum query length is 1,000 characters. Common words (stopwords) are filtered. Some special characters are not indexed.

Workaround
Review Stopwords. Use filters in combination with search for more precise results. Implement client-side filtering for very specific requirements.

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.

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.