Define a Realm Object Schema - Java SDK
On this page
- Define a Realm Object
- Extend
RealmObject - Implement
RealmModel - Lists
- Define a Relationship Field
- Many-to-One
- Many-to-Many
- Inverse Relationships
- Define an Embedded Object Field
- Annotations
- Primary Key
- Required Fields
- Optional Fields
- Default Field Values
- Index a Field
- Ignore a Field
- Rename a Field
- Rename a Class
- Omit Classes from your Realm Schema
For conceptual information about schemas, as well as details about types and constraints, see Fundametals: Object Models & Schemas.
Define a Realm Object
To define a Realm object in your application, create a subclass of RealmObject or implement RealmModel.
All Realm objects must provide an empty constructor.
Extend RealmObject
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.
Implement RealmModel
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:
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:
Lists
Realm objects can contain lists of non-Realm-object data types:
Define a Relationship Field
If you're using Realm Sync, you can also define your relationships in the App Services UI.
Realm objects use getters and setters to persist updated field values to your realms. Always use getters and setters when changing fields of a Realm object.
Many-to-One
To set up a many-to-one or one-to-one relationship, create a field whose type is a Realm object in your application:
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.
Many-to-Many
RealmList s are containers of RealmObject s, but otherwise behave
like a regular collection. You can use the same object in multiple
RealmList s.
Inverse Relationships
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>:
Inverse relationship fields must be marked final.
Define an Embedded Object Field
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:
Annotations
Use annotations to customize your Realm object models.
Primary Key
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.
Required Fields
Optional Fields
Fields are only optional if they can hold a value of null and they
are not marked with the Required annotation.
Default Field Values
To assign a default value to a field, use the built-in language features to assign default values.
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.
Index a Field
To index a field, use the @Index annotation:
Ignore a Field
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:
Fields marked static or transient are always ignored, and do
not need the @Ignore annotation.
Rename a Field
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:
Rename a Class
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:
Omit Classes from your Realm Schema
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: