Docs Menu

Docs HomeRealm

Define a Realm Object Schema - Java SDK

On this page

Tip

See also:

For conceptual information about schemas, as well as details about types and constraints, see Fundamentals: 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.

  • All Realm objects must use the public visibility modifier in Java or the open visibility modifier in Kotlin.

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.

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

Tip

See also:

With Device Sync, you can also define your relationships in the App Services UI.

Warning

Always Define Accessors and Mutators for Modifiable Fields

Realm objects use getters and setters to persist updated field values to your realms. Always use getters and setters for updates.

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

Important

To-one relationships must be optional

When you declare a to-one relationship in your object model, it must be an optional property. If you try to make a to-one relationship required, Realm throws an exception at runtime.

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 Sync, objects 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

The SDK ignores 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:

←  Usage Examples - Java SDKOpen & Close a Realm - Java SDK →
Share Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.