Navigation

Realm Objects

Overview

MongoDB Realm applications model data as objects composed of field-value pairs that each contain one or more primitive data types or other Realm objects. Realm objects are essentially the same as regular objects, but they also include additional features like real-time updating data views and reactive change event handlers.

Every Realm object has an object type that refers to the object’s class. Objects of the same type share an object schema that defines the properties and relationships of those objects. In most languages you define object schemas using the native class implementation.

Example

The following code block shows an object schema that describes a Dog. Every Dog object must include a name and age and may optionally include the dog’s breed and a reference to a Person object that represents the dog’s owner.

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

Key Concepts

Live Object

Objects in Realm clients are live objects that update automatically to reflect data changes, including synced remote changes, and emit notification events that you can subscribe to whenever their underlying data changes. You can use live objects to work with object-oriented data natively without an ORM tool.

Live objects are direct proxies to the underlying stored data, which means that a live object doesn’t directly contain data. Instead, a live object always references the most up-to-date data on disk and lazy loads property values when you access them from a collection. This means that a realm can contain many objects but only pay the performance cost for data that the application is actually using.

Valid write operations on a live object automatically persist to the realm and propagate to any other synced clients. You do not need to call an update method, modify the realm, or otherwise “push” updates.

Object Schema

An object schema is a configuration object that defines the fields, relationships of a Realm object type. Realm client applications define object schemas with the native class implementation in their respective language using the Realm Object Model.

Object schemas specify constraints on object properties such as the data type of each property, whether or not a property is required, and the default value for optional properties. Schemas can also define relationships between object types in a realm.

Every Realm app has a Realm Schema composed of a list of object schemas for each type of object that the realms in that application may contain.

MongoDB Realm guarantees that all objects in a realm conform to the schema for their object type and validates objects whenever they’re created, modified, or deleted.

Primary Key

A primary key is a String or Integer property that uniquely identifies an object. You may optionally define a primary key for an object type as part of the object schema. Realm Database automatically indexes primary key properties, which allows you to efficiently read and modify objects based on their primary key.

If an object type has a primary key, then all objects of that type must include the primary key property with a value that is unique among objects of the same type in a realm. You cannot change the primary key property for an object type after any object of that type is added to a realm.

Property Schema

A property schema is a field-level configuration that defines and constrains a specific property in an object schema. Every object schema must include a property schema for each property in the object. At minimum, a property schema defines a property’s data type and indicates whether or not the property is required.

You can configure the following constraints for a given property:

Parameter Description
Type

Every property in a Realm object has a strongly defined data type. A property’s type can be a primitive data type or an object type defined in the same realm. The type also specifies whether the property contains a single value or a list of values.

Realm Database supports the following primitive data types:

  • bool for boolean values
  • int, float, and double, which map to JavaScript number values
  • string
  • date, which maps to Date
  • data, which maps to ArrayBuffer
  • objectId, which maps to ObjectId
Optional

Optional properties may contain a null value or be entirely omitted from an object. By default, all properties are required unless explicitly marked as optional. To mark a property as optional, append a question mark (?) to its name.

Example

The following schema defines an optional string property, breed:

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

If a client application creates a new object that does not have a value for a defined property, the object uses the default value instead.

You can specify a default value on a property by using the object-form property specification. For example, the following schema defines a Car with a default value of 0 for its miles property:

const CarSchema = {
  name: 'Car',
  properties: {
    make:  'string',
    model: 'string',
    miles: {type: 'int', default: 0},
  }
};
Indexed

A property index significantly increases the speed of certain read operations at the cost of additional overhead for write operations. Indexes are particularly useful for equality comparison, such as querying for an object based on the value of a property.

To enable an index on a given property, set indexed to true in the long-form property specification. The following example defined a BookSchema with an index on the name property:

const BookSchema = {
name: 'Book',
  properties: {
    name: { type: 'string', indexed: true },
    price: 'float'
  }
};

Summary

  • Realm objects are of a type defined by a schema.
  • Realm objects are live: they always reflect the latest version on disk and update automatically when the underlying object changes.
  • A Realm object type may have a primary key property to uniquely identify each instance of the object type.
  • The Realm object’s schema defines the properties of the object and which properties are optional, which properties have a default value, and which properties are indexed.
←   Realms Embedded Objects  →