A Storm projection is a read-only type over a table, a database view or a SQL query. It has a repository without write methods, takes typed predicates, and nests in other types.
A reporting screen reads a database view the DBA maintains. An owners list reads three columns of a wide owner table. A dashboard lists owners with their number of pets. None of them writes.
JPA's mapped type is the entity, and an entity is read-write. Hibernate's @Immutable marks one read-only, which is the usual mapping for a view:
// An entity over a view, read-only through a Hibernate annotation @Entity @Immutable @Table(name = "owner_address_view") class OwnerAddressView( @Id var id: Int? = null, var fullName: String = "", var address: String = "", var city: String = "", )
@Immutable is Hibernate's, not JPA's. Hibernate does not write changes to such an entity, and its instances are still managed by the persistence context. A Spring Data repository over it offers save() unless you declare a narrower one with only the find methods. For a subset of a table, Spring Data's interface and class projections shape the result of a repository method. For a read model backed by SQL, Hibernate has @Subselect.
Storm has a type for it. An Entity is read-write; a Projection is read-only. A projection can map a database view:
// The class name maps to the view: OwnerAddressView -> owner_address_view data class OwnerAddressView( @PK val id: Int, val fullName: String, val address: String, val city: String, ) : Projection<Int>
Or a subset of a table's columns:
// Three columns of the owner table, read-only @DbTable("owner") data class OwnerSummary( @PK val id: Int, val firstName: String, val lastName: String, ) : Projection<Int>
A subset projection is a second type to keep in step with the table, so start with the entity and add one where the width of the entity shows in the slow statement log or the performance log.
A projection's repository has the read API: findAll, findById, counting, pages, slices, scrolling and the query builder. It has no insert, update or remove, so a write does not compile:
val ownerSummaries = orm.projection(OwnerSummary::class) val all = ownerSummaries.findAll() val smiths = ownerSummaries.findAll(OwnerSummary_.lastName eq "Smith")
-- findAll(): the projection's columns only SELECT os.id, os.first_name, os.last_name FROM owner os -- findAll(OwnerSummary_.lastName eq "Smith") SELECT os.id, os.first_name, os.last_name FROM owner os WHERE os.last_name = ?
The results are immutable data classes, not proxies, and OwnerSummary_.lastName is a path in the generated metamodel.
An entity or another projection can reference a projection through @FK. Storm joins it into the same statement, and a predicate follows the path:
@DbTable("pet") data class PetView( @PK val id: Int, val name: String, @FK val owner: OwnerSummary, // a projection inside a projection ) : Projection<Int> // The predicate follows the path into the nested projection val smithsPets = orm.projection(PetView::class) .findAll(PetView_.owner.lastName eq "Smith")
-- the nested projection is joined into the same statement SELECT pv.id, pv.name, os.id, os.first_name, os.last_name FROM pet pv INNER JOIN owner os ON pv.owner_id = os.id WHERE os.last_name = ?
Within one query, equal owner rows hydrate into one OwnerSummary instance, so a thousand pets of fifty owners hold fifty owner objects. The N+1 tutorial shows the same sharing for entities.
@ProjectionQuery backs a projection with SQL of its own. Storm reads that SQL as a derived table, so a typed predicate applies to its columns, the aggregate included:
@ProjectionQuery(""" SELECT o.id, o.first_name, o.last_name, COUNT(p.id) AS pet_count FROM owner o LEFT JOIN pet p ON p.owner_id = o.id GROUP BY o.id, o.first_name, o.last_name """) data class OwnerWithPetCount( @PK val id: Int, val firstName: String, val lastName: String, val petCount: Int, ) : Projection<Int> // A typed predicate on the aggregate val ownersWithThreePets = orm.projection(OwnerWithPetCount::class) .findAll(OwnerWithPetCount_.petCount greaterEq 3)
-- the projection query is the derived table; the predicate applies on top SELECT owpc.id, owpc.first_name, owpc.last_name, owpc.pet_count FROM ( SELECT o.id, o.first_name, o.last_name, COUNT(p.id) AS pet_count FROM owner o LEFT JOIN pet p ON p.owner_id = o.id GROUP BY o.id, o.first_name, o.last_name ) owpc WHERE owpc.pet_count >= ?
| JPA with Hibernate | Storm | |
|---|---|---|
| Read-only type | An entity with Hibernate's @Immutable | Projection: its repository has no write methods |
| Database view | An entity mapped over the view | A projection named after the view |
| Subset of a table | An interface or class projection per repository method | A projection with @DbTable and its own repository |
| SQL-backed read model | Hibernate's @Subselect | @ProjectionQuery, filtered as a derived table |
| Instances | Managed entities, or projection proxies | Immutable data classes |
The reference documentation covers the mechanics in depth: