Object Models & Schemas - Android SDK¶
An object schema is a configuration object that defines the fields and relationships of a Realm object type. Android Realm applications define object schemas with Java or Kotlin classes using Realm Object Models.
Object schemas specify constraints on object fields such as the data type of each field, whether a field is required, and default field values. Schemas can also define relationships between object types in a realm.
Modifying your application's Realm Object Model requires you to migrate data from older versions of your Realm Object Model to the new version.
Realm Apps¶
Every Realm app has a Realm Schema composed of a list of object schemas for each type of object that the realms in that application may contain.
MongoDB Realm guarantees that all objects in a realm conform to the schema for their object type and validates objects whenever they're created, modified, or deleted.
Realm apps that take advantage of Realm Sync can define schemas in two ways:
- object schemas using Kotlin and Java class declarations with Development Mode.
- JSON object schemas in your Realm app backend.
Primary Keys¶
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 a primary key.
You can create a primary key with any of the following types:
String
ObjectId
Integer
orint
Long
orlong
Short
orshort
Byte
orbyte[]
Using a String
as a primary key implicitly
indexes the field.
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 Database 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 Realm Sync, you cannot change the primary key field for an object after defining the primary key in your backend Realm Schema.
Embedded objects cannot contain primary keys.
Optionality¶
You can make a field required to disallow null
values in a field.
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
ObjectId
Integer
Long
Short
Byte
orbyte[]
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.
In Kotlin, types are non-nullable by default unless you explicitly
add a ?
suffix to the type. You can only annotate
nullable types. Using the
@Required
annotation on non-nullable types will fail compilation.
In Kotlin, fields are considered nullable only if a field is marked nullable with the Kotlin ? operator except for the following types:
String
Date
ObjectId
Decimal128
You can require any type that ends with the Kotlin ?
operator, such as Int?
.
The RealmList
type is non-nullable by default and cannot be
made nullable.
Relationships¶
You can model one-to-one relationships in realm with
RealmObject fields.
You can model one-to-many and many-to-one relationships
RealmList fields.
Inverse relationships are the opposite end of a one-to-many or
many-to-one relationship.
You can make inverse relationships traversable with the
@LinkingObjects
annotation on a RealmResults
field. In an instance of a RealmObject
, inverse relationship fields
contain the set of Realm objects that point to that object
instance through the described relationship. You can find the same set
of Realm objects with a manual query, but the inverse
relationship field reduces boilerplate query code and capacity for error.
Indexes¶
Indexes support the efficient execution of queries in Realm Database. Without indexes, Realm Database 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 Database 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 to a field makes writing slightly slower, but makes certain queries faster. Indexes require space in your realm file, so adding an index to a field will increase disk space consumed by your realm file.
You can index fields with the following types:
String
ObjectId
Integer
orint
Long
orlong
Short
orshort
Byte
orbyte[]
Boolean
orbool
Date
Realm creates indexes for fields annotated with @Index. Indexes speed up some queries, but have a negative impact on insert and update operation speed. Indexes also consume additional space on disk.
Modules¶
Realm Modules describe the set of Realm objects that can be stored in a realm. By default, Realm automatically creates a Realm Module that contains all Realm objects defined in your application. You can define a RealmModule to restrict a realm to a subset of classes defined in an application. If you produce a library that uses Realm, you can use a Realm Module to explicitly include only the Realm objects defined in your library in your realm. This allows applications that include your library to also use Realm without managing object name conflicts and migrations with your library's defined Realm objects.
Summary¶
- Realm objects are of a type defined as you would any other class.
- The Realm object's schema defines the fields of the object and which fields are optional, which fields have a default value, and which fields are indexed.
- You can define to-one, to-many, and inverse relationships in your schema. Inverse relationships automatically form backlinks.