Relationships - Kotlin SDK
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.
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 { 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 { var _id: ObjectId = ObjectId() lateinit var title: String val user: RealmResults<User> by backlinks(User::posts) }