Navigation

Realms

Overview

A realm is a set of related objects that conform to a pre-defined schema and share user-level access permissions. Realms may contain more than one type of data as long as a schema exists for each type.

A realm allows you to partition data according to who uses it and when they use it. Every realm stores data in a separate realm file that contains a binary encoding of each object in the realm. You can automatically synchronize realm across multiple devices and set up reactive event handlers that call a function any time an object in a realm is created, modified, or deleted.

Comparison with Other Databases

The MongoDB Realm data model is similar to both relational and document databases but has distinct differences from both. To underscore these differences, it’s helpful to highlight what a realm is not:

A realm is not a single, application-wide database.
Unlike other applications, which store all of their data in a single database, Realm apps often split data across multiple realms to organize data more efficiently and to enforce access controls.
A realm is not a table.
Tables typically only store one kind of information, such as street addresses or items in a store inventory, whereas a realm can contain any number of object types.
A realm is not a collection of schemaless documents.
Application objects are similar to documents, but every object in a realm conforms to a defined schema for its object type. An object cannot contain a field that is not described by its schema.

Key Concepts

Realm Schema

A Realm Schema is a list of valid object schemas that each define an object type that a Realm app may persist. All objects in a realm must conform to the Realm Schema.

Client applications provide a Realm Object Model when they open a realm. If a realm already contains data, then Realm Database validates each existing object to ensure that an object schema was provided for its type and that it meets all of the constraints specified in the schema.

Example

A realm that contains basic data about books in libraries might use a schema like the following:

[
  {
    "type": "Library",
    "properties": {
      "address": "string",
      "books": "Book[]"
    }
  },
  {
    "type": "Book",
    "primaryKey": "isbn",
    "properties": {
      "isbn": "string",
      "title": "string",
      "author": "string",
      "numberOwned": { "type": "int?", "default": 0 },
      "numberLoaned": { "type": "int?", "default": 0 }
    }
  }
]

Schema Version

A schema version identifies the state of a Realm Schema at some point in time. Realm Database tracks the schema version of each realm and uses it to map the objects in each realm to the correct schema.

Schema versions are ascending integers that you can optionally include in the realm configuration when you open a realm. If a client application does not specify a version number when it opens a realm then the realm defaults to version 0.

Increment Versions Monotonically

Migrations must update a realm to a higher schema version. Realm Database will throw an error if a client application opens a realm with a schema version that is lower than the realm’s current version or if the specified schema version is the same as the realm’s current version but includes different object schemas.

Realm Permissions

A permission is a boolean flag that indicates that a user is authorized to access, modify, or manage a realm. Permissions are defined individually for each realm and either apply to a specific user or configure the default permission for all users that don’t have permissions specified on the realm.

All realms are private by default, which means that the owner has full permissions and no other user has any permissions unless explicitly granted by the owner or a user with manage permissions on the realm.

MongoDB Realm supports the following permissions:

Permission Description
mayRead

If true, the user has read access to all objects in the realm.

Read access does not imply write access, so a user may not be able to modify a realm that they can read.

mayWrite

If true, the user has read and write access to all objects in the realm.

Write access requires read access, so the mayWrite permission also sets mayRead to true for the user.

mayManage

If true, the user has read and write access to all objects in the realm and can set permissions on the realm for other users.

Manage access requires write access, so the mayManage permission also sets mayWrite and mayRead to true for the user.

Realms are Partitions of Atlas Data

Each realm corresponds to a subset of the data in your Realm app’s synced MongoDB Atlas cluster. You can customize the partitioning of data using your application’s partition key. Unique values of the partition key, known as partition values, correspond to individual realms.

You can customize permissions for these partitions of data using Realm Rules.

Summary

  • A realm is a collection of objects that conform to a schema. It is not a single, application-wide database. There can and usually will be more than one realm per application.
  • A Realm Schema is a versioned specification of the object types used in a Realm app.
  • Realm Rules define who can read or write the realm and apply to the realm as a whole.
  • A partition value is a realm’s unique identifier.