In Sitecore Content Hub, content management and entity modeling rely on a well-defined schema. The schema represents the structure of content entities, their properties, and relationships.
However, content modeling needs to be dynamic and adaptable without causing downtime or inconsistency.
This flexibility is achieved through the Graph Server, which maintains an in-memory graph model of the system’s entity data.
The Graph Server ensures that:
- Changes to entity definitions, properties, or relations are reflected in real-time.
- Descendant entities automatically adapt based on inheritance or dependency configurations.
- System-wide consistency is maintained during schema evolution.
In this technical guide, we will explore:
- Different types of schema changes and their impact on the Graph Server.
- How inheritance models work inside Sitecore Content Hub (taxonomy, path, topology, content, completion, security).
- How system behavior changes based on whether a change affects the entity model or not.
- A practical modeling example showing how schema changes, such as adding new fields to an entity definition, are instantly available across the system, including entity creation pages and portal components.
Components of the Graph Server
The Graph Server in Sitecore Content Hub maintains a live, in-memory graph of entities, their relationships, and inheritance structures. It ensures real-time updates without downtime whenever the schema or content changes.
Two main workers interact with the Graph Server:
Elasticsearch Graph Worker
- Updates search service documents when entity structure changes.
- Exports updated entities to ElasticSearch for search indexing.
- Triggered by content changes that affect the graph model.
Business Audit Graph Worker
- Captures audit entries for all system events, whether structural or not.
- Records changes like validation updates, relation modifications, and entity operations.
- Triggered by every system event.
Worker Responsibilities Summary
Deep Dive into Schema Change Types
Schema changes in Sitecore Content Hub are classified into four types.
Each type affects how the Graph Server updates and how the system reacts.
1. Content Changes
Direct modifications to entity definitions (properties, relations, inheritance).
Impact:
- May trigger Graph Server reload.
- Descendant entities may also be affected.
Examples: Adding a new property, changing a relation flag.
2. Validation Changes
Updates to validation rules (mandatory flags, regex, conditions).
Impact:
- No graph reload.
- Affects only runtime validation.
Examples: Making a field mandatory, setting validation regex.
3. Representation Changes
Changes affecting how entities are exposed via APIs (e.g., nesting, permissions).
Impact:
- No graph reload.
- Affects API and external system view only.
Examples: Marking a relation as navigable, setting nested permissions.
4. Entity Changes
Changes to the actual data values of entities.
Impact:
- Updates specific entity instances.
- Descendants affected only if inheritance is configured.
Examples: Updating a Title, linking an Asset to a Campaign.
Graph Reload Behavior by Change Type
The Graph Server behavior depends on the type of change made to the schema or entity data.
Here’s how the system reacts:
Changes that Reload the Graph Model
| Scenario | What Happens |
|---|---|
| Content changes affecting descendants | Full graph reload for the entity and its descendants. |
| Content changes not affecting descendants | Partial reload for the entity and direct children. |
| Entity data changes (e.g., property updates) | Targeted updates for the entity and dependent descendants. |
Changes that Do Not Reload the Graph Model
| Scenario | What Happens |
|---|---|
| Validation changes | No graph reload. Only validation rules update. |
| Representation changes | No graph reload. Only external API behavior changes. |
| Non-structural events (e.g., audit entries) | No impact on the graph structure. |
Practical Example: Modeling a Schema Change and Observing Behavior
We want to create a new custom entity definition called MarketingCampaign.
This entity will:
- Have a few basic properties.
- Create a relation to
M.Asset(to manage related marketing assets).
We will then observe how the Graph Server reacts.
Note:
For the detailed steps to create a new custom definition, follow my guide here:
🔗 How to Create a New Definition in Sitecore Content Hub
What Happens Internally?
| Step | System Reaction |
|---|---|
| Entity Definition Created | Graph updated, search reindex needed |
| Properties Added | Graph updated |
| Relation Added | Graph updated |
| Save Triggered | Workers perform search export and audit logging |
GraphQL Query to Fetch MarketingCampaign Data
Use the following query to retrieve the newly created MarketingCampaign entities and their fields:query getMarketingCampaign {
allMarketingCampaign {
total
results {
id
campaignName
campaignStatusActive
startDate
endDate
location
marketingAssets {
results {
id
fileName
}
}
}
}
}
Note:
The above query fetches data after creating a few entities with the new custom entity definition MarketingCampaign, using the out-of-box component in Sitecore Content Hub.
To learn how to create entities from a new custom definition and display them through the portal, refer to this blog: 🔗 Displaying Entities Created from New Custom Definition
After executing the query, the results appear with fields like campaignName, campaignStatusActive, startDate, endDate, location and marketingAssets, similar to what is shown in the following screenshot from the GraphQL playground:
Important Note: Schema Changes and Query Behavior
When a new property or relation is added to an entity definition, it is categorized as a Content Change.
The Portal UI reflects these changes immediately by reading from the live Graph Server model.
However, the GraphQL Preview API uses a separately generated schema, and new fields or relations are not immediately available.
GraphQL schema exposure depends on internal cache refresh or background jobs.
Best Practices and Cautions for Schema Changes
Here are key best practices:
1. Plan Content Changes Carefully
- Schema changes affecting descendants (like altering relations) trigger full graph reloads.
- Always assess the impact before updating high-hierarchy entity definitions (e.g.,
M.Asset,M.Project).
2. Prefer Incremental Changes in Production
- Apply schema changes in small, manageable batches.
- Avoid making multiple critical changes at once (e.g., adding fields + removing relations together).
3. Schedule Heavy Changes Outside Business Hours
- Large schema updates (especially for top-level entities) can load the Graph Server heavily.
- Perform during planned maintenance windows to avoid portal slowness or search inconsistencies.
4. Understand Validation vs Content Impact
- Validation rule changes (e.g., making a field mandatory) do not reload the graph.
- Content model changes (e.g., new properties, changing inheritance) do impact graph behavior.
5. Monitor Search Indexing After Structural Changes
- After structural updates, verify that new fields or relations are searchable.
- ElasticSearch Worker updates indexes automatically, but confirm through portal search tests and GraphQL queries.
✍ Conclusion
Managing schema changes in Sitecore Content Hub requires a clear understanding of how different types of changes impact the system.
Not every change behaves the same:
- Content changes modify the entity model and can trigger a Graph Server reload.
- Validation and representation changes adjust system behavior without altering the graph structure.
- Entity data changes affect individual instances, sometimes impacting descendants depending on inheritance settings.
The Graph Server, along with the ElasticSearch Worker and Business Audit Worker, ensures real-time consistency without downtime — dynamically updating search indexes, preserving audit trails, and maintaining data integrity.
Real-world modeling — like creating a custom MarketingCampaign entity — demonstrates how schema updates propagate instantly, and how GraphQL queries validate the new structure live.
A successful Content Hub implementation depends not just on building flexible schemas but also on carefully managing changes, testing their impacts, and following best practices to keep the system fast, reliable, and scalable.