Relationships - Kotlin SDK

On this page

To-One Relationship

To-Many Relationship
Inverse Relationships

A relationship is an object property that references another Realm object.

Relationships are direct references to other objects in a realm, which means that you don't need bridge tables or explicit joins to define a relationship like you would in a relational database. Instead, you can access related objects by reading and writing to the property that defines the relationship. Realm Database executes read operations lazily, so querying objects with relationship fields doesn't slow queries.

There are two primary types of relationships between objects:

To-One Relationship
To-Many Relationship

Tip

One-to vs. Many-to Relationships

In Realm Database, there is no way to limit object references from other objects within the same realm. As a result, there is no way to restrict a relationship to "one to one/one to many" instead of "many to one/many to many".

You can define relationships in your object schema using the following types:

RealmObject
RealmList <? extends RealmObject>

To-One Relationship

A to-one relationship means that an object is related to no more than one other object. Setting a relationship field to null removes the connection between objects, but Realm Database does not delete the referenced object.

To set up a many-to-one or one-to-one relationship, create a field whose type is a Realm object in your application:

class SushiPlatter : RealmObject {
    val _id: ObjectId = ObjectId()
    val name: String = ""
    val fish: Fish? = null
}

Each Sushi references either zero Fish instances or one other Fish instance. Nothing prevents multiple Frog instances from referencing the same Frog as a best friend; the distinction between a many-to-one and a one-to-one relationship is up to your application.

To-Many Relationship

A to-many relationship means that an object is related in a specific way to multiple objects. You can create a relationship between one object and any number of objects using a field of type RealmList<T> where T is a Realm object in your application:

class Sushi : RealmObject {
    val _id: ObjectId = ObjectId()
    val name: String = ""
    val fishes: RealmList<Fish> = realmListOf<Fish>()
}

RealmLists are containers of RealmObjects, but otherwise behave like a regular collection. The same object can occur in multiple to-many relationships; the distinction between a many-to-many and a one-to-many relationship is up to your application.

Note

The child objects in a to-many relationship must be a RealmList or a RealmSet. For instance, if a "Sushi" object has many "Fish" objects, you must specify the "Sushi.fishes" as a RealmList or RealmSet of Fish objects.

Inverse Relationships

An inverse relationship links an object back to any other objects that refer to it in a defined to-one or to-many relationship. Relationship definitions are unidirectional, so you must explicitly define a property in the object's model as an inverse relationship.

For example, the to-many relationship "User has many Posts" does not automatically create the inverse relationship "Post belongs to User".

Realm Database automatically updates implicit relationships whenever an object is added or removed in the specified relationship. You cannot manually add or remove items from a backlinks collection.

Because relationships are many-to-one or many-to-many, following inverse relationships can result in zero, one, or many objects.

Consider the following class defining a User with a RealmList of posts:

class User: RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    lateinit var name: String
    val posts: RealmList<Post>? = null
}

You can provide a link in the opposite direction, from Post to User. This allows you filter data about the user who the post belongs to like any other RealmResults.

class Post: RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    lateinit var title: String
    val user: RealmResults<User> by backlinks(User::posts)
}

← Primary Keys - Kotlin SDK RealmSet - Kotlin SDK →