Define a Realm Object Model - Java SDK

Extend RealmObject

The following code block shows a Realm object that describes a Frog. This Frog class can be stored in Realm 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 because it implements the RealmModel class and uses the @RealmClass annotation:

Primary Key

Realm treats fields marked with the @PrimaryKey annotation as primary keys for their corresponding object schema. Primary keys are subject to the following limitations:

• You can define only one primary key per object schema.

• Primary key values must be unique across all instances of an object in a realm. Attempting to insert a duplicate primary key value results in a RealmPrimaryKeyConstraintException.

• Primary key values are immutable. To change the primary key value of an object, you must delete the original object and insert a new object with a different primary key value.

• Embedded objects cannot define a primary key.

You can create a primary key with any of the following types:

• String

• UUID

• ObjectId

• Integer or int

• Long or long

• Short or short

• Byte or byte[]

Non-primitive types can contain a value of null as a primary key value, but only for one object of a particular type, since each primary key value must be unique. Attempting to insert an object with an existing primary key into a realm will result in a RealmPrimaryKeyConstraintException.

Realm automatically indexes primary key fields, which allows you to efficiently read and modify objects based on their primary key.

You cannot change the primary key field for an object type after adding any object of that type to a realm. If you are using Sync, you cannot change the primary key field for an object after defining the primary key in your backend schema.

Embedded objects cannot contain primary keys.

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

Required Fields

Optional Fields

Fields marked with Java object types and Kotlin nullable types (ending with ?) are nullable by default. All other types (primitives, non-nullable Kotlin object types) are required by default. You can mark a nullable field with the @Required annotation to prevent that field from holding a null value. RealmLists are never nullable, but you can use the @Required annotation to prevent objects in a list from holding a null value, even if the base type would otherwise allow it. You cannot mark a RealmList of RealmObject subtypes as required.

You can make any of the following types required:

• String

• UUID

• ObjectId

• Integer

• Long

• Short

• Byte or byte[]

• Boolean

• Float

• Double

• Date

• RealmList

Primitive types such as int and the RealmList type are implicitly required. Fields with the RealmObject type are always nullable, and cannot be made required.

Default Field Values

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

Index a Field

Indexes support the efficient execution of queries in Realm. Without indexes, Realm must perform a collection scan, i.e. scan every document in a collection, to select those documents that match a query. If an appropriate index exists for a query, Realm can use the index to limit the number of documents that it must inspect.

Indexes are special data structures that store a small portion of a realm's data in an easy to traverse form. The index stores the value of a specific field ordered by the value of the field. The ordering of the index entries supports efficient equality matches and range-based query operations.

Adding an index can speed up some queries at the cost of slightly slower write times and additional storage and memory overhead. Indexes require space in your realm file, so adding an index to a property will increase disk space consumed by your realm file. Each index entry is a minimum of 12 bytes.

You can index fields with the following types:

• String

• UUID

• ObjectId

• Integer or int

• Long or long

• Short or short

• Byte or byte[]

• Boolean or bool

• Date

• RealmAny

Realm creates indexes for fields annotated with @Index.

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:

Rename a Field

By default, Realm 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 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 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.

• To change a class name in Kotlin without forcing a migration.

Use the @RealmClass annotation to rename a class: