Docs Menu

Docs HomeRealm

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


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>

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.

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.


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.

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)
←  Primary Keys - Kotlin SDKRealmSet - Kotlin SDK →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.