Define an SDK Object Model

In C++, when opening a database, you must specify which models are available by passing the models to the template you use to open the database. Those models must have schemas, and this list of schemas becomes the database schema.

In C#, you can define object schemas by using the C# class declarations. When a database is initialized, it discovers the SDK objects defined in all assemblies that have been loaded and generates schemas accordingly. If you want to restrict a database to manage only a subset of the SDK models in the loaded assemblies, you can explicitly pass the models when configuring a database.

For more information, refer to Provide a Subset of Models to a Database.

In Dart, the database configuration takes a RealmSchema that has an iterable collection of SchemaObjects. These SchemaObjects represent the SDK object types that the database file can manage.

In Java, the SDK automatically adds all classes in your project that derive from an SDK object type to the database schema.

The JS SDK's database configuration has a schema property that takes an array of object schemas that the database instance can manage.

In Kotlin, the database configuration has a schema property that takes a set of classes that the database can manage.

In Java, the SDK automatically adds all classes in your project that derive from an SDK object type to the database schema.

In Objective-C, you don't have to explicitly specify the database schema when you configure the database. Swift SDK executables can automatically read and write any valid SDK object whose model is included in the executable. If you want to restrict a database to manage only a subset of the SDK models in the executable, you can explicitly pass the models when configuring a database.

For more information, refer to Provide a Subset of Models to a Database.

In Swift, you don't have to explicitly specify the database schema when you configure the database. Swift SDK executables can automatically read and write any valid SDK object whose model is included in the executable. If you want to restrict a database to manage only a subset of the SDK models in the executable, you can explicitly pass the models when configuring a database.

For more information, refer to Provide a Subset of Models to a Database.

The JS SDK's database configuration has a schema property that takes an array of object schemas that the database instance can manage.

The C++ SDK object model is a regular C++ class or struct that contains a collection of properties. When you define your C++ class or struct, you must also provide an object schema. The schema is a C++ macro that gives the SDK information about which properties to persist, and what type of database object it is.

You must define your SDK object model within the realm namespace.

In C#, SDK object models are regular C# classes that define the SDK data model.

In Dart, you can define the object model using the native class implementation. You must annotate the class model with the SDK object type definition. As a separate step, you must generate SDK object classes that contain additional methods and meta-information that makes it possible to store, retrieve, and work with the object.

In the Java SDK, unlike normal Java objects, which contain their own data, an SDK object doesn't contain data. Instead, SDK objects read and write properties directly to the database.

The Java SDK uses RealmProxy classes to ensure that database objects don't contain any data themselves. Instead, each class's RealmProxy accesses data directly in the database.

For every model class in your project, the SDK annotation processor generates a corresponding RealmProxy class. This class extends your model class and is returned when you call Realm.createObject(). In your code, this object works just like your model class.

Java SDK Object Limitations

SDK objects:

• cannot contain fields that use the final or volatile modifiers (except for inverse relationship fields).

• cannot extend any object other than RealmObject.

• must contain an empty constructor (if your class does not include any constructor, the automatically generated empty constructor will suffice)

Usage limitations:

• Because SDK objects are live and can change at any time, their hashCode() value can change over time. As a result, you should not use RealmObject instances as a key in any map or set.

Java SDK Incremental Builds

The bytecode transformer used by the Java SDK supports incremental builds, but your application requires a full rebuild when adding or removing the following from an SDK object field:

• an @Ignore annotation

• the static keyword

• the transient keyword

You can perform a full rebuild with Build > Clean Project and Build > Rebuild Project in these cases.

You can define SDK models as JavaScript classes that extend Realm.Object.

When you create objects, use an object literal. This lets you create an unmanaged object, and pass it to the database when it makes sense to do so.

Do not use new to construct a new object instance. If you use new with class-based models, this creates a new managed object, which has the following side effects:

• Constructing a new object calls the realm.create() method, which can only be used in a write transcation.

• Constructing a new object has complications when the object contains or is itself an embedded object.

For more information about object creation and managed objects, refer to Create Objects and Create Specific Object Types.

In the Kotlin SDK, you define your application's data model with regular Kotlin classes declared in your application code.

In the Java SDK, unlike normal Java objects, which contain their own data, an SDK object doesn't contain data. Instead, SDK objects read and write properties directly to the database.

The Java SDK uses RealmProxy classes to ensure that database objects don't contain any data themselves. Instead, each class's RealmProxy accesses data directly in the database.

For every model class in your project, the SDK annotation processor generates a corresponding RealmProxy class. This class extends your model class and is returned when you call Realm.createObject(). In your code, this object works just like your model class.

Java SDK Object Limitations

SDK objects:

• cannot contain fields that use the final or volatile modifiers (except for inverse relationship fields).

• cannot extend any object other than RealmObject.

• must contain an empty constructor (if your class does not include any constructor, the automatically generated empty constructor will suffice)

Usage limitations:

• Because SDK objects are live and can change at any time, their hashCode() value can change over time. As a result, you should not use RealmObject instances as a key in any map or set.

Java SDK Incremental Builds

The bytecode transformer used by the Java SDK supports incremental builds, but your application requires a full rebuild when adding or removing the following from an SDK object field:

• an @Ignore annotation

• the static keyword

• the transient keyword

You can perform a full rebuild with Build > Clean Project and Build > Rebuild Project in these cases.

In Objective-C, SDK object models are regular Objective-C classes that define the SDK data model.

Objective-C SDK objects must derive from one of the SDK object types.

In Swift, SDK object models are regular Swift classes that define the SDK data model.

Swift SDK objects must derive from one of the SDK object types.

let standaloneModelObject = MyModel(value: persistedModelObject)

You can define SDK models as TypeScript classes that extend Realm.Object.

When you create objects, use an object literal. This lets you create an unmanaged object, and pass it to the database when it makes sense to do so.

Do not use new to construct a new object instance. If you use new with class-based models, this creates a new managed object, which has the following side effects:

• Constructing a new object calls the realm.create() method, which can only be used in a write transcation.

• Constructing a new object has complications when the object contains or is itself an embedded object.

For more information about object creation and managed objects, refer to Create Objects and Create Specific Object Types.

In C++, schemas are managed through macros. The schema must list every property type that you want to persist. The SDK inspects the object model to determine the property types and other special information, such as whether a property is the object's primary key.

A schema must accompany every object model you want to persist, and it may be one of:

• REALM_SCHEMA

• REALM_EMBEDDED_SCHEMA

• REALM_ASYMMETRIC_SCHEMA

You must define the schema and your object model within the realm namespace.

In C#, when the SDK processes SDK object types, it generates a schema for each class based on the class properties. However, there may be times that you want to manually define the schema, and the .NET SDK provides a mechanism for doing so.

In Dart, the object schema is automatically generated as part of the SDK object model code generation step. You can view the schema as a static final schema property in the generated .realm.dart file.

In the Java SDK, the SDK automatically creates object schemas based on your SDK model classes.

When you create an SDK object model class, you define the type's name and properties in a static property called schema.

When the SDK model extends Realm.Object, you pass the model class directly to the database schema list, and it uses the schema property in your model class as a part of the database schema.

When the SDK model does not extend Realm.Object, as when it is an embedded object, you pass only the object's schema to the database schema list. You cannot pass the object itself directly to the database.

In the Kotlin SDK, you do not need to manually specify an object schema. The SDK automatically creates an object schema for every object type that inherits from the RealmObject class or its subclasses: EmbeddedRealmObject or AsymmetricRealmObject.

In the Java SDK, the SDK automatically creates object schemas based on your SDK model classes.

The Swift SDK does not require you to manually create object schemas. Instead, it uses reflection to automatically create schemas for your SDK object types.

Your project must not set SWIFT_REFLECTION_METADATA_LEVEL = none, or the SDK cannot discover properties in your models. Reflection is enabled by default if your project does not specifically set a level for this setting.

The Swift SDK does not require you to manually create object schemas. Instead, it uses reflection to automatically create schemas for your SDK object types.

Your project must not set SWIFT_REFLECTION_METADATA_LEVEL = none, or the SDK cannot discover properties in your models. Reflection is enabled by default if your project does not specifically set a level for this setting.

When you create an SDK object model class, you define the type's name and properties in a static property called schema.

When the SDK model extends Realm.Object, you pass the model class directly to the database schema list, and it uses the schema property in your model class as a part of the database schema.

When the SDK model does not extend Realm.Object, as when it is an embedded object, you pass only the object's schema to the database schema list. You cannot pass the object itself directly to the database.

In C++, the base object provides accessors and other methods to work with SDK objects, including things like:

• Checking whether an object is valid

• Getting its managing database instance

• Registering a notification token

Define a C++ struct or class as you would normally. Add a REALM_SCHEMA whose first value is the name of the struct or class. Add the names of the properties that you want the database to manage. Omit any fields that you do not want to persist.

In C#, to define a Realm object, inherit from the the IRealmObject interface and declare the class a partial class.

The following code block shows an object schema that describes a Dog. Every Dog object must include a Name and may optionally include the dog's Age, Breed and a list of people that represents the dog's Owners.

In Dart, to define a Realm object, create a class model and add the RealmModel annotation. Follow the Define an SDK Object Model procedure detailed on this page to generate the RealmObject model and schema definitions.

Then, use the generated RealmObject model in your application code.

In the Java SDK, to define a Realm object in your application, subclass RealmObject or implement RealmModel.

Create a JavaScript class that extends Realm.Object.

Define a static schema object of type ObjectSchema. This schema includes a name property, which becomes the table name in the database. The schema should include a properties array, which is an array of objects of type PropertiesTypes. Each object in this array contains a string key that becomes the name of the property, and a PropertySchema that provides additional details about the property, such as its type and any special behaviors it should have.

In the Kotlin SDK, to define a Realm object type, create a Kotlin class that implements the RealmObject interface.

In the Java SDK, to define a Realm object in your application, subclass RealmObject or implement RealmModel.

In Objective-C, to define a Realm object, create a class that inherits from RLMObject.

In Swift, to define a Realm object, create a class that inherits from Object.

Create a TypeScript class that extends Realm.Object.

Define a static schema object of type ObjectSchema. This schema includes a name property, which becomes the table name in the database. The schema should include a properties array, which is an array of objects of type PropertiesTypes. Each object in this array contains a string key that becomes the name of the property, and a PropertySchema that provides additional details about the property, such as its type and any special behaviors it should have.

In C++, you define an embedded object by providing a REALM_EMBEDDED_SCHEMA whose first argument is the struct or class name. Add the names of any properties that you want the database to persist.

Define a property as an embedded object on the parent object by setting a pointer to the embedded object's type.

In C#, to define an embedded object, inherit from the the IEmbeddedObject interface and declare the class a partial class. You can reference an embedded object type from parent object types in the same way as you would define a relationship.

Consider the following example where the Address is an Embedded Object. Both the Contact and the Business classes reference the Address as an embedded object.

In Dart, to define an embedded object, create a class model and add the RealmModel annotation. Pass ObjectType.embeddedObject to the @RealmModel() annotation.

Embedded objects must be nullable when defining them in the parent object's RealmModel. You can use the parent property to access the parent of the embedded object.

Follow the Define an SDK Object Model procedure detailed on this page to generate the RealmObject model and schema definitions.

Then, use the generated RealmObject model in your application code.

The following example shows how to model an embedded object in a Realm object schema. The _Address model is embedded within the _Person model.

To embed an object, set the embedded property of the @RealmClass annotation to true on the class that you'd like to nest within another class:

import io.realm.RealmObject;
import io.realm.annotations.RealmClass;
@RealmClass(embedded=true)
public class Fly extends RealmObject {
    private String name;
    public Fly(String name) {
        this.name = name;
    }
    public Fly() {} // RealmObject subclasses must provide an empty constructor
}

Then, any time you reference that class from another class, the SDK embeds the referenced class within the enclosing class, as in the following example:

In the JavaScript SDK, to define an embedded object, set embedded to true. You can reference an embedded object type from parent object types in the same way as you would define a relationship.

In the Kotlin SDK, to define an embedded object type, create a Kotlin class that implements the EmbeddedRealmObject interface.

To embed an object, set the embedded property of the @RealmClass annotation to true on the class that you'd like to nest within another class:

import io.realm.RealmObject
import io.realm.annotations.RealmClass
@RealmClass(embedded = true)
open class Fly : RealmObject {
    private var name: String? = null
    constructor(name: String?) {
        this.name = name
    }
    constructor() {} // RealmObject subclasses must provide an empty constructor
}

Then, any time you reference that class from another class, the SDK embeds the referenced class within the enclosing class, as in the following example:

In Objective-C, to define an embedded object, create a class that inherits from RLMEmbeddedObject. You can use your embedded object in another model as you would any other type.

In Swift, to define an embedded object, create a class that inherits from EmbeddedObject. You can use your embedded object in another model as you would any other type.

In the JavaScript SDK, to define an embedded object, set embedded to true. You can reference an embedded object type from parent object types in the same way as you would define a relationship.

In C++, define an asymmetric object the same way you would a regular C++ struct or class. Provide a REALM_ASYMMETRIC_SCHEMA with the struct or class name as the first argument. Add the names of any properties that you want the database to persist.

An asymmetric_object broadly has the same supported types as realm::object, with a few exceptions:

• Asymmetric objects can link to the following types: - object - embedded_object - std::vector<embedded_object>

In C#, to define a asymmetric object, inherit from the the IAsymmetricObject interface and declare the class a partial class.

In Dart, to define an asymmetric object, create a class model and add the RealmModel annotation. Pass ObjectType.asymmetricObject to the @RealmModel() annotation.

Follow the Define an SDK Object Model procedure detailed on this page to generate the RealmObject model and schema definitions.

Then, use the generated RealmObject model in your application code.

The Java SDK does not support Data Ingest or asymmetric objects. Use the Kotlin SDK for heavy insert-only workloads.

In JavaScript, to define an asymmetric object, set the asymmetric property on your object schema.

In the Kotlin SDK, to define an asymmetric object type, create a Kotlin class that implements the AsymmetricRealmObject interface:

The Java SDK does not support Data Ingest or asymmetric objects. Use the Kotlin SDK for heavy insert-only workloads.

In Objective-C, to define an embedded object, create a class that inherits from RLMAsymmetricObject.

RLMAsymmetricObject broadly supports the same property types as RLMObject, with a few exceptions:

• Asymmetric objects can only link to embedded objects

  • RLMObject and RLMArray<RLMObject> properties are not supported in Swift SDK versions 10.42.3 and earlier. In Swift SDK versions 10.42.4 and later, asymmetric objects can link to non-embedded objects.

  • RLMEmbeddedObject and RLMArray<RLMEmbeddedObject> are supported.

You cannot link to an RLMAsymmetricObject from within an RLMObject. Doing so throws an error.

In Swift, to define an asymmetric object, create a class that inherits from AsymmetricObject.

AsymmetricObject broadly supports the same property types as Object, with a few exceptions:

• Asymmetric objects can only link to embedded objects

  • Object and List<Object> properties are not supported in Swift SDK versions 10.42.3 and earlier. In Swift SDK versions 10.42.4 and later, asymmetric objects can link to non-embedded objects.

  • EmbeddedObject and List<EmbeddedObject> are supported.

You cannot link to an AsymmetricObject from within an Object. Doing so throws an error.

In TypeScript, to define an asymmetric object, set the asymmetric property on your object schema.

The C++ SDK does not currently support geospatial data.

In C#, to create a class that conforms to the GeoJSON spec:

1. Create an embedded object (a class that inherits from IEmbeddedObject).

2. At a minimum, add the two fields required by the GeoJSON spec:

   • A field of type IList<double> that maps to a "coordinates" (case sensitive) property in the object schema.

   • A field of type string that maps to a "type" property. The value of this field must be "Point".

The following example shows an embedded class named "CustomGeoPoint" that is used to persist GeoPoint data:

public partial class CustomGeoPoint : IEmbeddedObject
{
    [MapTo("coordinates")]
    public IList<double> Coordinates { get; } = null!;
    [MapTo("type")]
    private string Type { get; set; } = "Point";
    public CustomGeoPoint(double latitude, double longitude)
    {
        Coordinates.Add(longitude);
        Coordinates.Add(latitude);
    }
}

In Dart, to create a class that conforms to the GeoJSON spec, you:

1. Create an embedded object. For more information about embedded objects, refer to Define an SDK Object Model.

2. At a minimum, add the two fields required by the GeoJSON spec:

   • A field of type double[] that maps to a "coordinates" (case sensitive) property in the schema.

   • A field of type string that maps to a "type" property. The value of this field must be "Point".

The following example shows an embedded class named MyGeoPoint that is used to persist geospatial data:

// To store geospatial data, create an embedded object with this structure.
// Name it whatever is most convenient for your application.
@RealmModel(ObjectType.embeddedObject)
class _MyGeoPoint {
  // These two properties are required to persist geo data.
  final String type = 'Point';
  final List<double> coordinates = const [];
  // You can optionally implement convenience methods to simplify
  // creating and working with geospatial data.
  double get lon => coordinates[0];
  set lon(double value) => coordinates[0] = value;
  double get lat => coordinates[1];
  set lat(double value) => coordinates[1] = value;
  GeoPoint toGeoPoint() => GeoPoint(lon: lon, lat: lat);
}

The Java SDK does not support geospatial data. Use the Kotlin SDK to work with GeoJSON and location data.

In JavaScript, to create a class that conforms to the GeoJSON spec, you:

1. Create an embedded SDK object. For more information about embedded objects, refer to Define an Embedded Object.

2. At a minimum, add the two fields required by the GeoJSON spec:

   • A field of type double[] that maps to a "coordinates" (case sensitive) property in the object schema.

   • A field of type string that maps to a "type" property. The value of this field must be "Point".

To simplify geodata persistance, you can define a model that implements CanonicalGeoPoint, which already has the correct shape. The following example shows an embedded class named MyGeoPoint that is used to persist geospatial data:

class MyGeoPoint {
  type = "Point";
  constructor(long, lat) {
    this.coordinates = [long, lat];
  }
  static schema = {
    name: "MyGeoPoint",
    embedded: true,
    properties: {
      type: "string",
      coordinates: "double[]",
    },
  };
}

class Company extends Realm.Object {
  static schema = {
    name: "Company",
    properties: {
      _id: "int",
      location: "MyGeoPoint",
    },
    primaryKey: "_id",
  };
}

In the Kotlin SDK, to create a class that conforms to the GeoJSON spec, you:

1. Create an embedded object (a class that inherits from EmbeddedRealmObject).

2. At a minimum, add the two fields required by the GeoJSON spec:

   • A field of type String property that maps to a type property with the value of "Point": var type: String = "Point"

   • A field of type RealmList<Double> that maps to a coordinates property in the object schema containing a latitude/longitude pair: var coordinates: RealmList<Double> = realmListOf()

The following example shows an embedded class named CustomGeoPoint that is used to persist geospatial data:

class CustomGeoPoint : EmbeddedRealmObject {
    constructor(latitude: Double, longitude: Double) {
        coordinates.apply {
            add(longitude)
            add(latitude)
        }
    }
    // Empty constructor required by Realm
    constructor() : this(0.0, 0.0)
    // Name and type required by Realm
    var coordinates: RealmList<Double> = realmListOf()
    // Name, type, and value required by Realm
    private var type: String = "Point"
    @Ignore
    var latitude: Double
        get() = coordinates[1]
        set(value) {
            coordinates[1] = value
        }
    @Ignore
    var longitude: Double
        get() = coordinates[0]
        set(value) {
            coordinates[0] = value
        }
}

The Java SDK does not support geospatial data. Use the Kotlin SDK to work with GeoJSON and location data.

The SDK does not have an example of persisting GeoJSON data with Objective-C. Refer to the Swift language for details about persisting geospatial data with the Swift SDK.

To persist geospatial data with the Swift SDK, create a GeoJSON-compatible embedded class that you can use in your data model.

Your custom embedded object must contain the two fields required by the GeoJSON spec:

• A field of type String property that maps to a type property with the value of "Point": @Persisted var type: String = "Point"

• A field of type List<Double> that maps to a coordinates property containing a latitude/longitude pair: @Persisted private var coordinates: List<Double>

In TypeScript, to create a class that conforms to the GeoJSON spec, you:

1. Create an embedded SDK object. For more information about embedded objects, refer to Define an Embedded Object.

2. At a minimum, add the two fields required by the GeoJSON spec:

   • A field of type double[] that maps to a "coordinates" (case sensitive) property in the object schema.

   • A field of type string that maps to a "type" property. The value of this field must be "Point".

To simplify geodata persistance, you can define a model that implements CanonicalGeoPoint, which already has the correct shape. The following example shows an embedded class named MyGeoPoint that is used to persist geospatial data:

// Implement `CanonicalGeoPoint`
// for convenience when persisting geodata.
class MyGeoPoint implements CanonicalGeoPoint {
  coordinates!: GeoPosition;
  type = "Point" as const;
  constructor(long: number, lat: number) {
    this.coordinates = [long, lat];
  }
  static schema: ObjectSchema = {
    name: "MyGeoPoint",
    embedded: true,
    properties: {
      type: "string",
      coordinates: "double[]",
    },
  };
}

class Company extends Realm.Object<Company> {
  _id!: number;
  location!: MyGeoPoint;
  static schema: ObjectSchema = {
    name: "Company",
    properties: {
      _id: "int",
      location: "MyGeoPoint",
    },
    primaryKey: "_id",
  };
}

The C++ SDK does not currently support indexing a property.

You can index properties of these data types:

• bool

• byte

• short

• int

• long

• DateTimeOffset

• char

• string

• ObjectId

• UUID

To index a property, use the Indexed attribute. With the Indexed attribute, you can specify the type of index on the property by using the IndexType enum.

In the following example, we have a default ("General") index on the Name property:

You can index properties of these data types:

• bool

• int

• String

• ObjectId

• Uuid

• DateTime

• RealmValue

To create an index on the field, add the Indexed annotation to the property.

You can index properties of these data types:

• String

• UUID

• ObjectId

• Integer or int

• Long or long

• Short or short

• Byte or byte[]

• Boolean or bool

• Date

• RealmAny

To index a field, use the @Index annotation.

You can index properties of these data types:

• string

• integer

• boolean

• Date

• UUID

• ObjectId

To define an index for a given property, set indexed to true.

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

You can index properties of these data types:

• String

• Byte

• Short

• Int

• Long

• Boolean

• RealmInstant

• ObjectId

• RealmUUID

To create an index on a property, use the @Index annotation on the property.

You can index properties of these data types:

• String

• UUID

• ObjectId

• Integer or int

• Long or long

• Short or short

• Byte or byte[]

• Boolean or bool

• Date

• RealmAny

To index a field, use the @Index annotation.

You can index proeprties of these data types:

• string

• integer

• boolean

• NSDate

To index a property, override +[RLMObject indexedProperties] and return a list of indexed property names.

You can index properties of these data types:

• string

• integer

• boolean

• Date

• UUID

• ObjectId

• AnyRealmValue

To index a property, declare the property with indexed:true on the @Persisted notation.

You can index properties of these data types:

• string

• integer

• boolean

• Date

• UUID

• ObjectId

To define an index for a given property, set indexed to true.

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

The C++ SDK does not currently support Full-Text Search.

To index an FTS property, use the Indexed attribute with the IndexType.FullText enum. In the following example, we have a FullText index on the Biography property:

To create an FTS index on a property, use the @Indexed annotation and specify the RealmIndexType as fullText. This enables full-text queries on the property. In the following example, we mark the pattern and material properties with the FTS annotation:

The Java SDK does not support Full-Text Search. If you would like to use FTS, use the Kotlin SDK, instead.

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'.

To create an FTS index on a property, use the @FullText annotation.

The Java SDK does not support Full-Text Search. If you would like to use FTS, use the Kotlin SDK, instead.

The Swift SDK does not currently support Full-Text Search.

The Swift SDK does not currently support 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'.