Navigation

Define a Realm Object Schema - Android SDK

On this page

Tip

For conceptual information about schemas, as well as details about types and constraints, see Fundametals: Object Models & Schemas.

To define a Realm object in your application, create a subclass of RealmObject or implement RealmModel.

Important

All Realm objects must provide an empty constructor.

Example

The following code block shows a Realm object that describes a Frog. This Frog class can be stored in Realm Database because it extends the RealmObject class.

Example

The following code block shows a Realm object that describes a Frog. This Frog class can be stored in Realm Database because it implements the RealmModel class and uses the @RealmClass annotation:

Tip
Using RealmObject Methods

When you create a Realm object by extending the RealmObject class, you can access RealmObject class methods dynamically on instances of your Realm object. Realm objects created by implementing RealmModel can access those same methods statically through the RealmObject class:

Realm objects can contain lists of non-Realm-object data types:

Tip

To set up a many-to-one or one-to-one relationship, create a field whose type is a Realm object in your application:

Each Frog references either zero Frog instances or one other Frog instance. Nothing prevents multiple Frog instances from referencing the same Frog as a best friend; the distinction between a many-to-one and a one-to-one relationship is up to your application.

RealmList s are containers of RealmObject s, but otherwise behave like a regular collection. You can use the same object in multiple RealmList s.

By default, Realm Database relationships are unidirectional. You can follow a link from one class to a referenced class, but not in the opposite direction. Consider the following class defining a Toad with a list of frogFriends:

You can provide a link in the opposite direction, from Frog to Toad, with the @LinkingObjects annotation on a final (in Java) or val (in Kotlin) field of type RealmResults<T>:

Important

Inverse relationship fields must be marked final.

Realm Database provides the ability to nest objects within other objects. This has several advantages:

  • If using Realm Sync, objects will translate into MongoDB documents that follow a denormalized data model.
  • When you delete an object that contains another object, the delete operation removes both objects from the realm, so unused objects don't accumulate in your realm file, taking up valuable space on user's mobile devices.

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:

Then, any time you reference that class from another class, Realm Database will embed the referenced class within the enclosing class, as in the following example:

Use annotations to customize your Realm object models.

You may optionally define a primary key for an object type as part of the object schema with the @PrimaryKey annotation:

Only one field in a RealmObject can use the @PrimaryKey annotation.

Fields are only optional if they can hold a value of null and they are not marked with the Required annotation.

To assign a default value to a field, use the built-in language features to assign default values.

Note
Default Values and Nullability

While default values ensure that a newly created object cannot contain a value of null (unless you specify a default value of null), they do not impact the nullability of a field. To make a field non-nullable, see Required Fields.

To index a field, use the @Index annotation:

If you don't want to save a field in your model to a realm, you can ignore a field.

Ignore a field from a Realm object model with the @Ignore annotation:

Note
Ignoring static and transient Fields

Fields marked static or transient are always ignored, and do not need the @Ignore annotation.

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

  • To make it easier to work across platforms, since naming conventions differ.
  • To change a field name in Kotlin without forcing a migration.

Choosing an internal name that differs from the name used in model classes has the following implications:

  • Migrations must use the internal name when creating classes and fields.
  • Schema errors reported will use the internal name.

Use the @RealmField annotation to rename a field:

Alternatively, you can also assign a naming policy at the module or class levels to change the way that Realm Database interprets field names.

You can define a naming policy at the module level, which will affect all classes included in the module:

You can also define a naming policy at the class level, which overrides module level settings:

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

  • To support multiple model classes with the same simple name in different packages.
  • To make it easier to work across platforms, since naming conventions differ.
  • To use a class name that is longer than the 57 character limit enforced by Realm Database.
  • To change a class name in Kotlin without forcing a migration.

Use the @RealmClass annotation to rename a class:

By default, your application's Realm Schema includes all classes that extend RealmObject. If you only want to include a subset of classes that extend RealmObject in your Realm Schema, you can include that subset of classes in a module and open your realm using that module:

Give Feedback

On this page