Define a Realm Object Model - Kotlin SDK

Define a Realm Object Type

To define a Realm object type, create a Kotlin class that implements the RealmObject interface:

// Implements the `RealmObject` interface
class Frog : RealmObject { // Empty constructor required by Realm
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var age: Int = 0
    var species: String? = null
    var owner: String? = null
}

You can then use the object as a property to define relationships with other Realm objects.

Define an Embedded Object Type

An EmbeddedRealmObject is a special type of Realm object that models complex data about a specific object. Realm treats each embedded object as nested data inside of a single specific parent object.

Because of this, embedded objects have the following constraints:

• An embedded object requires a parent object and cannot exist as an independent Realm object. If the parent object no longer references the embedded object, the embedded object is automatically deleted.

• An embedded object inherits the lifecycle of its parent object. For example, if you delete the parent object, the embedded object is also deleted.

• Embedded objects have strict ownership with their parent object. You cannot reassign an embedded object to a different parent object, or share an embedded object between multiple parent objects.

• Embedded objects cannot have a primary key.

To define an embedded object type, create a Kotlin class that implements the EmbeddedRealmObject interface:

// Implements `EmbeddedRealmObject` interface
class EmbeddedAddress : EmbeddedRealmObject {
    // CANNOT have primary key
    var street: String? = null
    var city: String? = null
    var state: String? = null
    var postalCode: String? = null
    var propertyOwner: Contact? = null
}

Embedded object types are reusable and composable. You can use the same embedded object type in multiple parent object types inside other embedded object types.

After you define your embedded object type, you must define a relationship with a parent object in your data model. To learn how, refer to Define an Embedded Object.

Define an Asymmetric Object Type

An AsymmetricRealmObject is an insert-only object intended to be used with the Atlas Device Sync feature Data Ingest. For information on how to set up Data Ingest with your application, refer to Stream Data to Atlas - Kotlin SDK.

Asymmetric objects broadly support the same property types as RealmObject, with a few exceptions:

• Asymmetric objects can only be used in synced realms configured with Flexible Sync. However, you cannot create subscriptions to asymmetric objects.

• An AsymmetricRealmObject can contain EmbeddedRealmObject types, but cannot contain RealmObject types or other AsymmetricRealmObject types.

• AsymmetricRealmObject types cannot be used as properties in other Realm objects.

Additionally, asymmetric objects do not function in the same way as other Realm objects. You cannot add, read, update, or delete an asymmetric object from the realm. You can only create an asymmetric object, which then syncs unidirectionally to the Atlas database linked to your App with Device Sync. Realm then deletes this object after syncing.

To define an asymmetric object type, create a Kotlin class that implements the AsymmetricRealmObject interface:

// Implements the `AsymmetricRealmObject` interface
class WeatherSensor : AsymmetricRealmObject {
    @PersistedName("_id")
    @PrimaryKey
    var id: ObjectId = ObjectId()
    var deviceId: String = ""
    var temperatureInFarenheit: Float = 0.0F
    var barometricPressureInHg: Float = 0.0F
    var windSpeedInMph: Int = 0
}

In Kotlin SDK versions 1.11.1 and earlier, you cannot link from AsymmetricRealmObject types to RealmObject types. In SDK versions 1.12.0 and later, AsymmetricRealmObject types can link to RealmObject types in addition to EmbeddedRealmObject types.

Define a RealmList

To define a property as a RealmList, specify its type within the object schema as RealmList<E> and initialize the default value using realmListOf():

// RealmList<E> can be any supported primitive
// or BSON type, a RealmObject, or an EmbeddedRealmObject
class Frog : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
    // List of RealmObject type (CANNOT be nullable)
    var favoritePonds: RealmList<Pond> = realmListOf()
    // List of EmbeddedRealmObject type (CANNOT be nullable)
    var favoriteForests: RealmList<EmbeddedForest> = realmListOf()
    // List of primitive type (can be nullable)
    var favoriteWeather: RealmList<String?> = realmListOf()
}
class Pond : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
}

Define a RealmSet

To define a property as a RealmSet, specify its type within the object schema as RealmSet<E> and initialize the default value using realmSetOf():

// RealmSet<E> can be any supported primitive or
// BSON type or a RealmObject
class Frog : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
    // Set of RealmObject type (CANNOT be nullable)
    var favoriteSnacks: RealmSet<Snack> = realmSetOf()
    // Set of primitive type (can be nullable)
    var favoriteWeather: RealmSet<String?> = realmSetOf()
}
class Snack : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
}

Define a RealmDictionary/RealmMap

To define a property as a RealmDictionary, specify its type within the object schema as a RealmDictionary<K, V> and initialize the the default value using realmDictionaryOf():

// RealmDictionary<K, V> can be any supported
// primitive or BSON types, a RealmObject, or
// an EmbeddedRealmObject
class Frog : RealmObject {
    var _id: ObjectId = ObjectId()
    var name: String = ""
    // Dictionary of RealmObject type (value MUST be nullable)
    var favoriteFriendsByPond: RealmDictionary<Frog?> = realmDictionaryOf()
    // Dictionary of EmbeddedRealmObject type (value MUST be nullable)
    var favoriteTreesInForest: RealmDictionary<EmbeddedForest?> = realmDictionaryOf()
    // Dictionary of primitive type (value can be nullable)
    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"