Define a Realm Object Model - Node.js SDK

Specify an Optional Property

To mark a property as optional, append a question mark ? to its type.

The following Car schema defines an optional miles property of type int.

class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: { type: "objectId", default: () => new Realm.BSON.ObjectId() },
      make: "string",
      model: "string",
      miles: "int?",
    },
    primaryKey: "_id",
  };
}

Specify a Primary Key

To specify a property as an object type's primary key, set the schema's primaryKey field to the property name.

The following Car object schema specifies the _id property as its primary key.

class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: { type: "objectId", default: () => new Realm.BSON.ObjectId() },
      make: "string",
      model: "string",
      miles: "int?",
    },
    primaryKey: "_id",
  };
}

Index a Property

Realm supports indexing for string, integer, boolean, Date, UUID, and ObjectId properties. To define an index for a given property, set indexed to true.

The following Car object schema defines an index on the _id property.

class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: { type: "objectId", indexed: true },
      make: "string",
      model_name: { type: "string", mapTo: "modelName" },
      miles: { type: "int", default: 0 },
    },
    primaryKey: "_id",
  };
}

Set a Full-Text Search Index

In addition to standard indexes, Realm also supports Full-Text Search (FTS) indexes on string properties. While you can query a string field with or without a standard index, an FTS index enables searching for multiple words and phrases and excluding others.

For more information on querying FTS indexes, see Filter with Full-Text Search.

To create an FTS index, set the indexed type to 'full-text'. This enables full-text queries on the property. In the following example, we set the indexed type for the name property to 'full-text':

class Book extends Realm.Object<Book> {
  name!: string;
  price?: number;
  static schema: ObjectSchema = {
    name: "Book",
    properties: {
      name: { type: "string", indexed: "full-text" },
      price: "int?",
    },
  };
}

Define a Default Property Value

To define a default value, set the value of the property to an object with a type field and a default field.

The following Car object schema specifies a default value of 0 for the miles property:

class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: { type: "objectId", indexed: true },
      make: "string",
      model_name: { type: "string", mapTo: "modelName" },
      miles: { type: "int", default: 0 },
    },
    primaryKey: "_id",
  };
}

Map a Property or Class to a Different Name

By default, Realm uses the name defined in the model class to represent classes and fields internally. In some cases, you might want to change this behavior. For example:

• To make it easier to work across platforms where naming conventions differ. For example, if your Device Sync schema property names use snake case, while your project uses camel case.

• To change a class or field name without forcing a migration.

• To support multiple model classes with the same name in different packages.

• To use a class name that is longer than the 57-character limit enforced by Realm.

You can map a class or property name in your code to a different name to store in a realm. If you write to a synced realm, the Sync schema sees the values stored using the persisted class or property name.

Note that migrations must use the persisted class or property name, and any schema errors reported also use the persisted name.

class Task extends Realm.Object {
  static schema = {
    // Set the schema's `name` property to the name you want to store.
    // Here, we store items as `Todo_Item` instead of the class's `Task` name.
    name: "Todo_Item",
    properties: {
      _id: "int",
      name: "string",
      owner_id: "string?",
    },
    primaryKey: "_id",
  };
}
const config = {
  // Use the class name in the Configuration's `schema` property when
  // opening the realm.
  schema: [Task],
  sync: {
    user: anonymousUser,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(
          realm
            // Use the mapped name in Flexible Sync subscriptions.
            .objects(`Todo_Item`)
            .filtered(`owner_id == "${anonymousUser.id}"`)
        );
      },
    },
  },
};
const realm = await Realm.open(config);
realm.write(() => {
  // Use the mapped name when performing CRUD operations.
  realm.create(`Todo_Item`, {
    _id: 12342245,
    owner_id: anonymousUser.id,
    name: "Test the Todo_Item object name",
  });
});
// Use the mapped name when performing CRUD operations.
const assignedTasks = realm.objects(`Todo_Item`);

class Task extends Realm.Object<Task> {
  _id!: number;
  name!: string;
  owner_id?: string;
  static schema: ObjectSchema = {
    // Set the schema's `name` property to the name you want to store.
    // Here, we store items as `Todo_Item` instead of the class's `Task` name.
    name: "Todo_Item",
    properties: {
      _id: "int",
      name: "string",
      owner_id: "string?",
    },
    primaryKey: "_id",
  };
}
const config: Realm.Configuration = {
  // Use the class name in the Configuration's `schema` property when
  // opening the realm.
  schema: [Task],
  sync: {
    user: anonymousUser,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(
          realm
            // Use the mapped name in Flexible Sync subscriptions.
            .objects(`Todo_Item`)
            .filtered(`owner_id == "${anonymousUser.id}"`)
        );
      },
    },
  },
};
const realm = await Realm.open(config);
realm.write(() => {
  // Use the mapped name when performing CRUD operations.
  realm.create(`Todo_Item`, {
    _id: 12342245,
    owner_id: anonymousUser.id,
    name: "Test the Todo_Item object name",
  });
});
// Use the mapped name when performing CRUD operations.
const assignedTasks = realm.objects(`Todo_Item`);

class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: { type: "objectId", indexed: true },
      make: "string",
      model_name: { type: "string", mapTo: "modelName" },
      miles: { type: "int", default: 0 },
    },
    primaryKey: "_id",
  };
}

Define a To-One Relationship Property

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

To define a to-one relationship property, specify the related object type name as the property type.

The following Manufacturer object schema specifies that a manufacturer may or may not make a single Car. If they do make a Car, Realm links to it through the car property:

class Manufacturer extends Realm.Object {
  static schema = {
    name: "Manufacturer",
    properties: {
      _id: "objectId",
      // A manufacturer that may have one car
      car: "Car?",
    },
  };
}
class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: "objectId",
      make: "string",
      model: "string",
      miles: "int?",
    },
  };
}

Define a To-Many Relationship Property

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

To define a to-many relationship property, specify the related object type name as a list.

An application could use the following object schemas to indicate that a Manufacturer may make multiple Car objects by including them in its cars property:

class Manufacturer extends Realm.Object {
  static schema = {
    name: "Manufacturer",
    properties: {
      _id: "objectId",
      // A manufacturer that may have many cars
      cars: "Car[]",
    },
  };
}
class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: "objectId",
      make: "string",
      model: "string",
      miles: "int?",
    },
  };
}

Define an Inverse Relationship Property

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

To define an inverse relationship property, set the property type to linkingObjects and specify the object type and property name that define the relationship to invert.

An application could use the following object schemas to indicate that a Manufacturer may make many Car objects and that each Car should automatically keep track of which Manufacturer makes it.

• The Manufacturer object's cars property is defined as a to-many relationship

  with Car objects and contains all of a given manufacturer's cars.

• The Car object's assignee property inverts the relationship and

  automatically updates to refer back to any Manufacturer object that contains the car in its cars property.

class Manufacturer extends Realm.Object {
  static schema = {
    name: "Manufacturer",
    properties: {
      _id: "objectId",
      // A manufacturer that may have many cars
      cars: "Car[]",
    },
  };
}
class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: "objectId",
      make: "string",
      model: "string",
      miles: "int?",
      // Backlink to the manufacturer. This is automatically updated whenever
      // this car is added to or removed from a manufacturer's cars list.
      assignee: {
        type: "linkingObjects",
        objectType: "Manufacturer",
        property: "cars",
      },
    },
  };
}

Define an Embedded Object Property

To define a Realm object model with an embedded object (nested Realm object), set embedded to true.

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. Embedded objects cannot have a primary key.

You can reference an embedded object type from parent object types in the same way as a relationship.

The following example requires two parent schemas, Manufacturer and Car. The application requires an embedded child schema Warranty. A Manufacturer object can embed a list of Warranty objects, whereas a Car object can only embed a single Warranty object.

class Manufacturer extends Realm.Object {
  static schema = {
    name: "Manufacturer",
    properties: {
      _id: "objectId",
      name: "string",
      // Embed an array of objects
      warranties: { type: "list", objectType: "Warranty" },
    },
  };
}
class Car extends Realm.Object {
  static schema = {
    name: "Car",
    properties: {
      _id: "objectId",
      make: "string",
      model: "string",
      miles: "int?",
      // Embed one object
      warranty: "Warranty",
    },
  };
}
class Warranty extends Realm.Object {
  static schema = {
    name: "Warranty",
    embedded: true,
    properties: {
      name: "string",
      termLength: "int",
      cost: "int",
    },
  };
}