Working with Projection Unions
Learn how to import entities from other projections by reference using unions. Understand when to use unions versus chaining, and how unions support shared type libraries and cross-projection references.
A projection union imports entities from another projection by reference, similar to how a SQL UNION combines result sets or how a TypeScript file imports types from another module. Unlike chaining (which sets the entire source to an upstream projection), a union selectively brings in specific entities from one or more external projections while the main projection continues to source from its own upstream.
Unions vs Chaining
Both unions and chaining allow projections to reference other projections, but they serve different purposes:
| Aspect | Chaining | Union |
|---|---|---|
| Source | Changes the projection's entire source to an upstream projection | Imports selected entities from other projections while keeping the current source |
| Direction | Vertical - builds layers on top of each other | Horizontal - combines entities from multiple peer projections |
| Use case | Multi-layer architectures (medallion, staging) | Shared type libraries, cross-domain references |
| Entity ownership | All entities come from the upstream source | Local entities coexist with imported entities |
| Modification | Can transform, rename, and reshape imported entities | Imported entities are read-only references |
| Multiplicity | One source per projection | Multiple unions per projection |
When to Use Unions
Creating a Union
Practical Example: Shared Type Library
Consider an organisation with multiple service teams, each maintaining their own projections. Common types like Address, Money, and DateRange are defined in a central type library projection.
Multiple Unions
A single projection can union from multiple source projections. This is useful when you need types from several different domains or libraries.