Defining the data model




ID and Indexes

A model may have one or more named indexes, to allow you to search and/or order by a specific value.

A model must have one unique ID, which can be of any type. This ID defines the default ordering of the models inside the collections. In essence, the ID works exactly like an index, except that it is unnamed. You can use UUID.randomUUID() if your model does not have a unique value.

Indexes and IDs can be composite, which means that they can contain multiple values. A composite index allows you to:

  • Get models ordered by first value, then second, then third, then…​

  • Look for all models with the first value, then second, then third, then…​

With annotations

When targeting only the JVM, you can simply use annotations:

A simple model
data class User(
    @Id val uid: String,
    val firstName: String,
    @Index("lastName") val lastName: String
When using @Id or @Index, Kodein-DB converts String values to byte array using the ASCII charset. Therefore, only ASCII characters are allowed.

Using this configuration, when getting all users by index "lastName", they will be ordered first by lastName, then by uid. If you want the results to be ordered by lastName then firstName (then uid), you can use a composite index:

Same model with composite index
data class User(
    @Id val uid: String,
    val firstName: String,
    val lastName: String
) {
    @Index("name") fun nameIndex() = listOf(lastName, firstName)

With the model

The model itself can define its metadata by implementing either the Metadata or HasMetadata interface:

Model is metadata
data class User(
    override val id: String, (1)
    val firstName: String,
    val lastName: String
) : Metadata {
    override fun indexes() = mapOf("lastName" to listOf(lastName, firstName)) (2)
1 The id property override is mandatory
2 The indexes function override is optional (no index by default)
Model has metadata
data class User(
    val id: String,
    val firstName: String,
    val lastName: String
) : HasMetadata {
    override fun getMetadata(db: ModelDB, vararg options: Options.Write) =
            Metadata(id, "lastName" to listOf(lastName, firstName))

With an extractor

If you don’t own the models, or if you don’t want to mark them for Kodein-DB, you can use register a MetadataExtractor when you open the database:

Registering a metadata extractor
val db ="path/to/db",
    MetadataExtractor {
        when (it) {
            is User -> Metadata(, "lastName" to listOf(it.lastName, it.firstName))
            else -> error("Unknown model $it")

Using ID as an index

If we consider the User model we have just defined, we have defined the ID to be a UUID, meaning that the order in which they will be stored and retrieved is completely random.
Because the ID must be unique, we cannot use the name to be the ID. However, we can create a composite ID. Consider this updated model:

Model with a composite ID
data class User(
    val uid: String,
    val firstName: String,
    val lastName: String
) : Metadata {
    override val id get() = listOf(lastName, firstName, uid)

Because uid is unique, the tuple (lastName, firstName, uid) is unique (if only because it contains uid). Therefore, the id property is always unique, but the order in which the models will be stored are defined first by lastName, then by firstName, then only by id.

While using a composite ID can be very useful, it makes the creation of key from ID values more complex.

Key & References

If a model contains another model, it will be serialized into the same document. If you need to reference another document, then you need to store a Key:

A model with a reference to another model
data class User(
    override val id: String,
    val name: Name, (1)
    val address: Key<Address> (2)
) : Metadata {
    override fun indexes() = mapOf("lastName" to listOf(name.last, name.first))
1 Will be included as part of this model’s document.
2 References another model with its own document.

IDs and indexes values

While models are stored in the database as serialized blobs, IDs and indexes are stored as Value.

A Value is a serializable entity where the serialized bytes define the ordering of IDs and indexes.

Types usable as Value

By default, the Kodein-DB understands the following types to be used as values: ByteArray, ReadBuffer, Boolean, Short, Int, Long, ASCII Char, ASCII CharSequence (such as String), Kodein-Memory UUID (not java.util.UUID).

in order to keep the database efficient and indexes ordering semantic, Char and CharSequence are stored as ASCII characters (i.e. using only one byte per character). You should not use non-ascii characters in IDs or indexes values.

Adding new types as value

You can configure Kodein-DB to accept more types as values (and therefore use these types in IDs and indexes). You simply need to add a ValueConverter to the database when creating it:

a sample ValueConverter for KotlinX LocalDateTime:
val db ="path/to/db",
    ValueConverter.forClass<LocalDateTime> {


The problem

By default, Kodein-DB inserts each model in the document collection that corresponds to its real type.

Considering the following insertions:

Multiple insertions
open class Person(@Id val name: String)
class Child(name: String, val parents: List<Key<Person>>): Person(name)

val janeKey = db.put(Person("Jane"))
val johnKey = db.put(Person("John"))

val parents = listOf(janeKey, johnKey)
db.put(Child("Jill", parents))
db.put(Child("Jack", parents))

Using the preceding code, there will be two different collections, one Person, one Child, meaning if you were to look for all Person models, you would only get Jane & John.

Children are person too (even when they keep asking you when’s the end of this documentation…​) so, you probably want to put every Child model into the Person collection. To do that, you need to enable polymorphism: the fact that a collection can hold multiple types of models.

JVM only annotation

The simpler way to define a polymorphic document is to use the @Polymorphic annotation. However, as usual for annotations, it only works for the JVM.

Children are Persons
@Polymorphic(Person::class) (1)
class Child(name: String, val parents: List<Key<Person>>): Person(name)
1 This @Polymorphic annotation instructs Kodein-DB to put Child models into the Person collection.

Type Table

In Kodein-DB, the Type Table is responsible for defining which model type belongs to which collection.

Using a Type Table is compatible with multiplatform!

You can define a TypeTable when opening the database:

Defining a Type Table
val db ="path/to/db",
    TypeTable {
        root<Person>() (1)
            .sub<Child>() (2)
1 Defines the root collection Person.
2 Defines that all Child models will be put in the Person collection.