Working with Entity Reference Revisions
Entity Reference Revisions preserves both the target entity and the exact revision used by the host. That makes nested, revisionable content possible, but it also creates lifecycle and query complexity.
Understand ownership
The host revision owns a reference to a specific child revision. Publishing, reverting, translating, and deleting the host can affect which child revisions remain meaningful. Treat the aggregate as one editorial unit.
Avoid accidental loading storms
Deep trees can trigger many entity loads and large render arrays. Use view modes, correct cacheability, and bounded structures. Bulk background processing should load in chunks and release references between batches.
Respect revision context
Do not replace revision-aware references with ordinary entity reference queries when reconstructing historical content. Test revisions, translations, moderation transitions, and cloning together.
A reference points to a specific revision
The important difference from an ordinary entity reference is that the host records both the referenced entity and the revision that belongs to that host revision. When an editor changes a Paragraph inside a revisionable node, the historical node revision can continue to represent the earlier Paragraph state.
That is what makes revision-aware nested content practical, but it also means code should not casually replace the referenced revision with whatever happens to be the latest version of the child entity.
Test the editorial lifecycle, not only storage
Publishing, moderation, translation, cloning, reverting, and deletion all exercise the relationship differently. A custom migration or bulk update that appears correct on the default revision can still damage historical content if it ignores the revision context.
Tests should include the operations editors actually perform, especially when the referenced entities form a deep component tree.
Render the aggregate efficiently
Nested entities can produce large render trees. Use appropriate view modes and allow Drupal's cache metadata to bubble from the referenced components. Avoid repeatedly loading the same entities in loops when the storage API can load them together.
For large background operations, process bounded batches and avoid retaining unnecessary entity objects between iterations.
Key Takeaways
- Treat host and referenced revisions as an aggregate.
- Test revision and translation workflows together.
- Bound deep structures and batch large processing.