Navigation

Realms - Android SDK

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.

When opening a realm, you can configure many properties of the realm.

It's sometimes useful to ship a prepared realm file with your app that contains shared data that does not frequently change. You can use the readOnly() method when configuring your realm to make it read-only. This can prevent accidental writes to the realm and causes the realm to throw an IllegalStateException if a write occurs.

Warning IconCreated with Sketch.Warning
Read-Only Realm Files are Writeable

Read-only realms are only enforced as read-only in process; the realm file itself is still writeable. As a result, it is still possible for other process to write to a read-only realm.

Bulb IconTip

To create a realm that runs entirely in memory without being written to a file, use the inMemory() method when configuring your realm.

Important With Circle IconCreated with Sketch.Important
In-Memory Realms May Persist to Disk Under High Memory Pressure

When memory runs low on an Android device, in-memory realms may swap temporarily from main memory to disk space. However, all files created by an in-memory realm are deleted when that realm closes or all references to that realm fall out of scope.

Bulb IconTip

Conventional realms define a schema using RealmObject subclasses or the RealmModel interface. A DynamicRealm uses strings to define a schema at runtime. Opening a dynamic realm uses the same configuration as a conventional realm, but dynamic realms ignore all configured schema, migration, and schema versions.

Important With Circle IconCreated with Sketch.Important
Dynamic Realms Lack Type-Safety

Dynamic realms offer flexibility at the expense of type safety and performance. As a result, only use dynamic realms when that flexibility is required, such as during migrations, manual client resets, and when working with string-based data like CSV files or JSON.

Bulb IconTip

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.

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.

Beaker IconExample

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 }
}
}
]

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.

  • 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.
  • Modules let you selectively include subsets of the Realm objects defined in your application schema when opening a realm.
Give Feedback