Docs Menu

Model Relationships - Swift SDK

On this page

  • Key Concept: Relationships
  • To-One Relationship
  • To-Many Relationship
  • Inverse Relationship
  • Declare Relationship Properties
  • Define a To-One Relationship Property
  • Define a To-Many Relationship Property
  • Define an Inverse Relationship Property
  • Define an Embedded Object Property

Realm Database doesn't use bridge tables or explicit joins to define relationships as you would in a relational database. Realm Database handles relationships through embedded objects or reference properties to other Realm Database objects. You read from and write to these properties directly. This makes querying relationships as performant as querying against any other property.

Realm Database supports to-one, to-many, and inverse relationships.

A to-one relationship means that an object relates to one other object. You define a to-one relationship for an object type in its object schema. Specify a property where the type is the related Realm object type. For example, a dog might have a to-one relationship with a favorite toy.

Tip

To learn how to define a to-one relationship, see Define a To-One Relationship Property.

A to-many relationship means that an object relates to more than one other object. In Realm Database, a to-many relationship is a list of references to other objects. For example, a person might have many dogs.

A List represents the to-many relationship between two Realm types. Lists are mutable: within a write transaction, you can add and remove elements to and from a list. Lists are not associated with a query and are usually declared as a property of an object model.

Tip

To learn how to define a to-many relationship, see Define a To-Many Relationship Property.

Relationship definitions in Realm Database are unidirectional. An inverse relationship links an object back to an object that refers to it. You must explicitly define a property in the object's model as an inverse relationship. Inverse relationships can link back to objects in a to-one or to-many relationship.

A LinkingObjects collection represents the inverse relationship between two Realm types. You cannot directly add or remove items from a LinkingObjects collection.

Inverse relationships automatically update themselves with corresponding backlinks. You can find the same set of Realm objects with a manual query, but the inverse relationship field reduces boilerplate query code and capacity for error.

For example, consider a task tracker with the to-many relationship "User has many Tasks". This does not automatically create the inverse relationship "Task belongs to User". To create the inverse relationship, add a User property on the Task that points back to the task's owner. When you specify the inverse relationship from task to user, you can query on that. If you don't specify the inverse relationship, you must run a separate query to look up the user to whom the task is assigned.

Important

You cannot manually set the value of an inverse relationship property. Instead, Realm Database updates implicit relationships when you add or remove an object in the relationship.

Relationships can be many-to-one or many-to-many. So following inverse relationships can result in zero, one, or many objects.

Tip

To learn how to define an inverse relationship, see Define an Inverse Relationship Property.

Tip
See also:

With Device Sync, you can also define your relationships in the App Services UI.

A to-one relationship maps one property to a single instance of another object type. For example, you can model a person having at most one companion dog as a to-one relationship.

Setting a relationship field to null removes the connection between objects. Realm does not delete the referenced object, though, unless it is an embedded object.

Important
To-one relationships must be optional

When you declare a to-one relationship in your object model, it must be an optional property. If you try to make a to-one relationship required, Realm throws an exception at runtime.

Tip
See also:

For more information about to-one relationships, see: Key Concept: To-One Relationship.

If your app uses Device Sync, see the Model Data with Device Sync page for information on how the to-one relationship in Swift object models translates to Atlas documents.

A to-many relationship maps one property to zero or more instances of another object type. For example, you can model a person having any number of companion dogs as a to-many relationship.

Tip
See also:

For more information about to-many relationships, see: Key Concept: To-Many Relationship.

If your app uses Device Sync, see the Model Data with Device Sync page for information on how the to-many relationship in Swift object models translates to Atlas documents.

An inverse relationship property is an automatic backlink relationship. Realm Database automatically updates implicit relationships whenever an object is added or removed in a corresponding to-many list or to-one relationship property. You cannot manually set the value of an inverse relationship property.

Tip
See also:

For more information about inverse relationships, see: Key Concept: Inverse Relationship.

If your app uses Device Sync, see the Model Data with Device Sync page for information on how the inverse relationship in Swift object models translates to Atlas documents.

An embedded object exists as nested data inside of a single, specific parent object. It inherits the lifecycle of its parent object and cannot exist as an independent Realm object. Realm automatically deletes embedded objects if their parent object is deleted or when overwritten by a new embedded object instance.

Note
Realm Uses Cascading Deletes for Embedded Objects

When you delete a Realm object, any embedded objects referenced by that object are deleted with it. If you want the referenced objects to persist after the deletion of the parent object, your type should not be an embedded object at all. Use a regular Realm object with a to-one relationship instead.

Tip
See also:

If your app uses Device Sync, see the Model Data with Device Sync page for information on how embedded objects in Swift object models translate to Atlas documents.

←  Object Models - Swift SDKSupported Types - Swift SDK →
Give Feedback
© 2022 MongoDB, Inc.

About

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