Why synchronization matters
Section titled “Why synchronization matters”Optimizely Graph serves content through a search-optimized index, not directly from the CMS database. For frontends to receive up-to-date content, every publish action in the CMS must propagate to the Graph index. The synchronization pipeline handles this automatically, keeping the two systems in sync with minimal delay.
Understanding this pipeline helps you diagnose delivery delays, plan for content volume, and build reactive frontends that respond to content changes.
How the sync pipeline works
Section titled “How the sync pipeline works”Event-driven architecture
Section titled “Event-driven architecture”The pipeline follows a publish-subscribe pattern. When an author publishes, unpublishes, or deletes content in the CMS, the system generates a sync event. Graph consumes that event and updates its index accordingly.
The flow:
- Author action — A page is published, updated, or deleted in CMS
- CMS emits sync event — The CMS packages the content item with all its properties, metadata, and relationships
- Graph receives the payload — The sync service validates the payload against the current schema
- Index update — Graph writes the content into its search-optimized store
- Content becomes queryable — Frontend applications receive the updated content on their next query
This process completes in seconds under normal conditions. Most content changes become queryable within 2-5 seconds of publishing.
What gets synced
Section titled “What gets synced”Graph indexes every published content item that matches the configured content types. This includes:
- Property values — All content type properties (strings, numbers, dates, rich text, content areas)
- Metadata — Publication dates, status, locale, content GUID, URL slugs
- Relationships — Content references, content area items, linked content
- Binary metadata — File names, sizes, and MIME types for media (not the binary data itself)
- Ancestry — Parent-child relationships in the content tree
Rich text fields are indexed both as structured HTML and as plain text for full-text search.
Incremental vs full sync
Section titled “Incremental vs full sync”The pipeline supports two synchronization modes:
| Mode | Trigger | Scope | Duration |
|---|---|---|---|
| Incremental | Content publish/unpublish/delete | Single item + dependencies | Seconds |
| Full sync | Manual trigger or schema change | All published content | Minutes to hours |
Incremental sync is the default for everyday publishing. Full sync rebuilds the entire index and is necessary after schema changes, data migrations, or when recovering from sync errors.
Webhook notifications
Section titled “Webhook notifications”Graph can notify external systems when content changes occur. Webhooks fire after the index update completes, so the notified system can immediately query for the updated content.
{
"type": "content/updated",
"timestamp": "2026-03-25T14:30:00Z",
"source": "optimizely-graph",
"data": {
"contentKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contentType": "ArticlePage",
"locale": "en",
"action": "published",
"url": "/articles/getting-started"
}
}Common webhook use cases:
- Static site rebuilds — Trigger a Next.js or Gatsby rebuild when content changes
- Cache invalidation — Purge CDN caches for updated pages
- Notification systems — Alert teams when specific content types are updated
- Search index warming — Pre-fetch updated content for client-side search
See Set Up Webhooks for configuration steps.
Resync triggers
Section titled “Resync triggers”Several scenarios require a manual resync:
- Schema changes — Adding or removing content type properties that affect the Graph schema
- Bulk content imports — Loading large volumes of content outside the normal editorial workflow
- Index corruption — Rare cases where the index diverges from the CMS source of truth
- Environment provisioning — Setting up a new Graph environment against an existing CMS
curl -X POST \
https://cg.optimizely.com/api/content/v3/sync \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic {base64(AppKey:Secret)}' \
-d '{"action": "full"}'Sync monitoring and troubleshooting
Section titled “Sync monitoring and troubleshooting”Monitor sync health through the Graph admin API. The status endpoint returns the current sync state, last sync timestamp, and any pending items.
| Symptom | Likely cause | Resolution |
|---|---|---|
| Content not appearing | Sync event not fired | Verify content status is Published, not Draft |
| Stale content after publish | Incremental sync delayed | Check Graph service health; wait 30 seconds and retry |
| Missing properties | Schema out of date | Trigger a full resync after content type changes |
| Partial content tree | Full sync interrupted | Re-trigger the full sync job |
Design considerations for architects
Section titled “Design considerations for architects”Sync latency expectations — Plan for 2-5 second delays between publishing and queryability. Do not build frontends that assume instant consistency. Use webhooks to know when content is ready.
Content volume planning — Full resyncs scale linearly with content volume. A site with 10,000 content items may take 5-10 minutes for a full resync. Plan maintenance windows accordingly.
Multi-environment sync — Each Graph environment maintains its own index. Content synced to a staging Graph instance does not automatically appear in production. Promote content through your standard deployment pipeline.