Navigation

Relationships

Overview

MongoDB Realm allows you to define explicit relationships between the types of objects in a Realm app. A relationship is an object property that references another Realm object rather than a scalar or embedded object. You define relationships by setting the type of an object property to another object type in the property schema.

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 as they come in, so querying a relationship is just as performant as reading a regular property.

There are three primary types of relationships between objects:

Key Concepts

To-One Relationship

A to-one relationship means that an object is related in a specific way to no more than one other object. You define a to-one relationship for an object type in its object schema by specifying a property where the type is the related Realm object type.

Example

An application could use the following object schemas to indicate that a Person may or may not own a single Dog by including it in its dog property:

const Person = {
  name: "Person",
  properties: {
    name: "string",
    birthdate: "date",
    dog: "Dog?"
  }
};

const Dog = {
  name: "Dog",
  properties: {
    name: "string",
    age: "int",
    breed: "string?"
  }
};

To-Many Relationship

A to-many relationship means that an object is related in a specific way to multiple objects. You define a to-many relationship for an object type in its object schema by specifying a property where the type is a list or array of the related Realm object type.

Example

An application could use the following object schemas to indicate that a Person may own multiple Dogs by including them in its dog property:

const Person = {
  name: "Person",
  properties: {
    name: "string",
    birthdate: "date",
    dogs: "Dog[]"
  }
};

const Dog = {
  name: "Dog",
  properties: {
    name: "string",
    age: "int",
    breed: "string?"
  }
};

Inverse Relationship

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 Tasks” does not automatically create the inverse relationship “Task belongs to User”. If you don’t specify the inverse relationship in the object model, you would need to run a separate query to look up the user that is assigned to a given task.

To define an inverse relationship, define a linkingObjects property in your object model. The linkingObjects definition specifies the object type and property name of the relationship that it inverts.

Realm Database automatically updates implicit relationships whenever an object is added or removed in the specified relationship. You cannot manually set the value of an inverse relationship property.

Example

An application could use the following object schemas to indicate that a User may be assigned many Tasks and that each Task should automatically keep track of which User it’s assigned to.

  • The User object’s tasks property is defined as a to-many relationship with Task objects and contains all of a given user’s assigned tasks.
  • The Task object’s assignee property inverts the relationship and automatically updates to refer back to any User object that contains the Task in its tasks property.
class User {
  public _id: ObjectId = "";
  public _partition: string = "";
  public name: string = "";
  public tasks: Realm.List<Task>;

  public static schema: Realm.ObjectSchema = {
    name: "User",
    primaryKey: "_id",
    properties: {
      _id: "objectId",
      _partition: "string",
      name: "string",
      tasks: "Task[]"
    }
  };
}

class Task {
  public _id: ObjectId = "";
  public _partition: string = "";
  public text: string;
  public assignee: Realm.Results<User>;

  public static schema: Realm.ObjectSchema = {
    name: "Task",
    primaryKey: "_id",
    properties: {
      _id: "objectId",
      _partition: "string",
      text: "string",
      assignee: {
        type: 'linkingObjects',
        objectType: 'User',
        property: 'tasks'
      }
    }
  };
};
const User = {
  name: "User",
  primaryKey: "_id",
  properties: {
    _id: "objectId",
    _partition: "string",
    name: "string",
    tasks: "Task[]"
  }
};

const Task = {
  name: "Task",
  primaryKey: "_id",
  properties: {
    _id: "objectId",
    _partition: "string",
    text: "string",
    assignee: {
      type: 'linkingObjects',
      objectType: 'User',
      property: 'tasks'
    }
  }
};

Summary

  • A relationship is an object property that allows an object to reference other objects of the same or another object type.
  • Relationships are direct references. You can access related objects directly through a relationship property without writing any type of join.
  • Realm Database supports to-one, to-many, and inverse relationships.