Define a Realm Object Model - Kotlin SDK

Realm Objects

Realm objects are uniquely named instances of Kotlin classes that you can work with as you would any other class instance.

Each object class represents an object type. Objects of the same type share an object schema, which defines the properties and relationships for objects of that type. The SDK guarantees that all objects in a realm conform to the schema for their object type and validates objects whenever they are created, modified, or deleted.

However, note that Realm objects have the following constraints:

• Realm objects must inherit from the RealmObject class or its subclasses: EmbeddedRealmObject or AsymmetricRealmObject. The Kotlin SDK does not support inheritance from custom base classes.

• The Kotlin SDK requires that Realm objects have an empty constructor. Refer to the workaround example noted in the next section.

• Class names are limited to a maximum of 57 UTF-8 characters.

Additionally, the Kotlin SDK does not support using Kotlin data classes to model data. This is because data classes are typically used for immutable data, which goes against how the Realm Kotlin SDK models data.

Define a New Object Type

To define a new object type, you must create a uniquely named Kotlin class that implements either the RealmObject, EmbeddedRealmObject, or AsymmetricRealmObject interface.

Then, you specify your object's properties, including:

• The data type for each property. The Kotlin SDK supports the following data types:

  • Kotlin primitive types

  • a limited subset of BSON types

  • Realm-specific types, which you can use for unique identifiers, timestamps, counters, and collections

• Any property annotations, which add functionality to properties in your Realm objects. You can use annotations to:

  • Designate a property as a primary key

  • Mark a property as indexable

  • Ignore a property

  • Map a property or class name to another name

• Any relationships with other Realm objects.

After you've defined your Realm object model, you can pass the set of object classes to the realm's configuration when you open a realm, and then work with those objects in the realm.

class Person(var name: String, var age: Int): RealmObject {
   constructor(): this("", 0) // Empty constructor required by Realm
}

// 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
}

// 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
}

// 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
}

Define Collection Properties

A collection is an object that contains zero or more instances of a supported data type. Realm collections are homogenous (all objects in a collection are of the same type) and are backed by their corresponding built-in Kotlin classes. For more information on the collection types used in the Kotlin SDK and their supported data types, refer to Collection Types.

The Kotlin SDK offers several collection types that you can use as properties in your data model: RealmList, RealmSet, and RealmDictionary.

Collections also let you define to-many relationships between Realm objects. Refer to Relationships - Kotlin SDK for more information.

// 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 = ""
}

// 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 = ""
}

// 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()
}

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

Define Unstructured Data

Starting in Kotlin SDK version 2.0.0, you can store collections of mixed data within a RealmAny property. You can use this feature to model complex data structures, such as JSON or MongoDB documents, without having to define a strict data model.

Unstructured data is data that doesn't easily conform to an expected schema, making it difficult or impractical to model to individual data classes. For example, your app might have highly variable data or dynamic data whose structure is unknown at runtime.

Storing collections in a mixed property offers flexibility without sacrificing functionality, including performant synchronization when using Device Sync. And you can work with them the same way you would a non-mixed collection:

• You can nest mixed collections up to 100 levels.

• You can query on and react to changes on mixed collections.

• You can find and update individual mixed collection elements.

However, storing data in mixed collections is less performant than using a structured schema or serializing JSON blobs into a single string property.

To model unstructured data in your app, define the appropriate properties in your schema as RealmAny types. You can then set these RealmAny properties as a RealmList or a RealmDictionary collection of RealmAny elements. Note that RealmAny cannot represent a RealmSet or an embedded object.