Kotlin models a closed set of types as a sealed interface, and the compiler checks that a when over it handles every subtype. Storm maps a sealed interface onto one table, so that check covers the rows you read.
A pet table holds cats and dogs, with some shared columns and some per kind. The code should work with Cat and Dog types rather than one Pet with every field nullable, and a new kind should not compile until every place that handles pets handles it.
The sealed interface is the entity and the data classes are the subtypes. @Discriminator declares the column that tells the rows apart, dtype by default, holding the subtype name:
// The sealed interface is the entity; subtypes are data classes @Discriminator sealed interface Pet : Entity<Int> { val name: String // shared: a path of the Pet_ metamodel } data class Cat( @PK val id: Int = 0, override val name: String, val indoor: Boolean, ) : Pet data class Dog( @PK val id: Int = 0, override val name: String, val weight: Int, ) : Pet
All subtypes share the pet table. A shared field like name is one column; indoor and weight are NULL in the rows of the other subtype. A field the sealed interface declares is part of the Pet_ metamodel; a field only a subtype declares is part of that subtype's metamodel, such as Cat_.indoor.
The repository works on the sealed interface, and results come back as concrete subtypes. A when over a result is exhaustive, so adding a Bird turns every when that does not handle it into a compile error:
val pets = orm.entity(Pet::class) // Reads return the concrete subtypes for (pet in pets.findAll()) { when (pet) { is Cat -> render("${pet.name}, indoor=${pet.indoor}") is Dog -> render("${pet.name}, ${pet.weight}kg") } // add a Bird subtype and this stops compiling until handled } // Writes go through the same repository pets.insert(Cat(name = "Bella", indoor = true)) pets.update(Cat(id = 1, name = "Sir Whiskers", indoor = true))
-- one table; the discriminator column picks the subtype on read SELECT p.dtype, p.id, p.name, p.indoor, p.weight FROM pet p -- an insert writes the discriminator and the subtype's own columns INSERT INTO pet (dtype, name, indoor) VALUES (?, ?, ?) -- dtype = 'Cat' INSERT INTO pet (dtype, name, weight) VALUES (?, ?, ?) -- dtype = 'Dog'
On insert and update Storm reads the runtime class: an insert writes the discriminator and that subtype's columns. On select it reads the discriminator and constructs the matching type. There is no casting and no type column in your code.
Query the sealed type for all pets, or a subtype for one kind. A subtype of a single-table hierarchy is an entity of its own: orm.entity(Cat::class), or an EntityRepository<Cat, Int>, reads and writes the shared table, and every statement it runs selects the cats by the discriminator:
// A shared field filters the whole hierarchy val named = orm.entity(Pet::class).select() .where(Pet_.name like "B%") .resultList // List<Pet>: cats and dogs // A subtype is an entity of its own; its statements add the discriminator val indoorCats = orm.entity(Cat::class).select() .where(Cat_.indoor eq true) .resultList // List<Cat>
Subtypes may declare foreign keys as any entity does. A foreign key every subtype declares is joined with an inner join; one that only some subtypes declare is joined with a left join, since the other rows hold NULL.
This page covers the single-table strategy, the default. When subtypes have many fields of their own, the joined-table strategy (@Polymorphic(JOINED)) puts each subtype's columns in a table of its own; there, a subtype is not a repository or a FROM table of its own, so you query through the sealed type. See Polymorphism for the decision guide, discriminator options and polymorphic foreign keys.
The reference documentation covers the mechanics in depth: