Define a Realm Object Model - Kotlin SDK

Realm Schema

A realm schema is a list of valid object schemas that a realm may contain. Every Realm object must conform to an object type that's included in its realm's schema.

If a realm already contains data when you open it, Realm validates each object to ensure that an object schema was provided for its type and that it meets all of the constraints specified in the schema.

Property Types

The Kotlin SDK supports Kotlin data types, a limited subset of BSON types, UUID, and Realm-specific types.

To learn more about the available property types, refer to the Supported Types page.

Property Annotations

Annotations add functionality to properties in your Realm object models. You can use annotations for things like marking a property as nullable, setting a primary key, ignoring a property, and more.

To learn more about the available property annotations, refer to Property Annotations.

Define an Inverse Relationship Property

You can define a backlink property as a BacklinksDelegate or EmbeddedBacklinksDelegate to the parent object using the backlinks() method.

• A BacklinksDelegate<T> property is defined as a RealmResults list of the parent RealmObject type:

  val child: RealmResults<ParentObjectType> by backlinks(ParentObjectType::children)

• An EmbeddedBacklinksDelegate<T> property is defined as the parent RealmObject type:

  val embeddedChild: ParentObjectType by backlinks(ParentObjectType::embeddedChildren)

You then reference the backlinks in collections in the parent RealmObject:

var children: RealmSet<ChildObjectType> = realmSetOf()
var embeddedChildren: RealmList<EmbeddedChildType> = realmListOf() // RealmSets cannot contain embedded objects
var embeddedChildrenDictionary: RealmDictionary<EmbeddedChildType?> = realmDictionaryOf()

Define a RealmSet

To define a property as a RealmSet, specify its type within the schema as RealmSet<T>, where T is any of the supported data types or a RealmObject. If a RealmSet's value is a RealmObject, the value cannot have null elements.

Instantiate an unmanaged RealmSet by setting the field's default value using the realmSetOf() method.

In the following example, we define a Frog schema with a favoriteSnacks field that is a RealmSet of Snack objects:

class Frog : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var favoriteSnacks: RealmSet<Snack> = realmSetOf()
}
class Snack : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
}

Define a RealmDictionary/RealmMap

To define a RealmDictionary, specify its type within the schema as RealmDictionary<T>, where T is any Realm primitive type, a RealmObject, or an EmbeddedRealmObject. If a RealmDictionary's value is a RealmObject or EmbeddedRealmObject, the value must be declared nullable.

class Frog : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var favoritePondsByForest: RealmDictionary<String> = realmDictionaryOf()
}

Realm disallows the use of . or $ characters in map keys. You can use percent encoding and decoding to store a map key that contains one of these disallowed characters.

// Percent encode . or $ characters to use them in map keys
val mapKey = "Hundred Acre Wood.Northeast"
val encodedMapKey = "Hundred Acre Wood%2ENortheast"

Data Classes

The Realm Kotlin SDK does not support using data classes to model data. Typically, data classes are used for immutable data. This goes against how the Realm Kotlin SDK models data.

Inheritance

Realm Kotlin SDK classes may only inherit from Realm Object types. For example, your class may inherit from RealmObject or EmbeddedRealmObject, but not from custom classes that do not implement a Realm object interface.

// SUPPORTED
// You can inherit from Realm Object types directly
class MyBaseClass: RealmObject {
    var name: String = ""
}
// NOT SUPPORTED
// You can not inherit from classes that implement Realm object types
// This form of inheritance is not supported in the Realm Kotlin SDK
class Person: MyBaseClass {
    var age: Int
}

Single Primary Constructor

The Realm Kotlin SDK does not support having a single primary constructor. The SDK requires an empty constructor to create objects. As a workaround, you can do something similar to the following:

// SUPPORTED
// Realm requires an empty constructor to create objects
class Person(var name: String, var age: Int): RealmObject {
    constructor(): this("", 0) // Empty constructor required by Realm
}
// NOT SUPPORTED
// The Realm Kotlin SDK does not support having a single primary constructor
class Person(var name: String, var age: Int) RealmObject {
}