Define a Realm Object Model - Kotlin SDK

On this page

Overview

Object Types & Schemas
Realm Schema
Define a New Object Type
Property Annotations
Required and Optional Properties
Default Field Values
Specify a Primary Key
Map a Property to a Different Name
Ignore Properties from Realm Schema
Index Properties
Define Relationship Properties

Overview

Realm applications model data as objects composed of field-value pairs that each contain one or more data types or other Realm objects.

The Kotlin SDK memory maps Realm objects directly to native Kotlin objects, so there's no need to use a special data access library. You define your application's data model via regular Kotlin classes declared in your application code object.

To learn about how to make changes to your Realm objects after defining your Realm object model, refer to Change an Object Model.

Object Types & Schemas

Realm objects are regular Kotlin classes, and you can work with them as you would any other class instance.

Every Realm object has an object type that refers to the object's class.
Objects of the same type share an object schema, which defines the properties and relationships for objects of that type.

You define object schemas by using Kotlin class declarations.

Example

The following schema defines a Car object type with make, model, and miles properties:

class Car : RealmObject {
    var make: String = ""
    var model: String = ""
    var miles: Int = 0
}

Realm Schema

A realm schema is a list of valid object schemas that a realm may contain. Every Realm object must conform to an object type that's included in its realm's schema.

If a realm already contains data when you open it, Realm Database validates each object to ensure that an object schema was provided for its type and that it meets all of the constraints specified in the schema.

Define a New Object Type

To define a Realm object type:

Create a uniquely named Kotlin class that implements the RealmObject or EmbeddedRealmObject interface.
Add fields to your class. You can add any supported data types as a field in your class.
Add any property annotations to give Realm additional information about a property, including whether Realm should ignore the property or should be indexed.

// Defines a `Cat` object type
// with several properties
class Cat : RealmObject {
    var name: String = ""
    var color: String? = null
    var age: Int = 0
}

Note

Class names are limited to a maximum of 57 UTF-8 characters.

Once you've defined your object model, you can pass the class to the schema property of the RealmConfiguration when you open the realm.

val config = RealmConfiguration.Builder(
    schema = setOf(Cat::class) // Pass the defined class as the object schema
)
    .build()
val realm = Realm.open(config)

Property Annotations

Use annotations to add functionality to properties in your Realm object models.

Required and Optional Properties

In Kotlin, value types are implicitly non-nullable. You can make properties optional (nullable) using the built-in ? Kotlin operator.

class Cat : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId() // Primary key
    @Index
    var name: String = "" // Indexed property
    var color: String? = null // Optional property
    var age: Int = 0 // 0 is default value
    @Ignore
    var tempId: Int = 0 // Ignored property
    @PersistedName("latin_name") // Remapped property
    var species: String? = null
}

Default Field Values

You can assign a default value to a property in the property declaration.

class Cat : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId() // Primary key
    @Index
    var name: String = "" // Indexed property
    var color: String? = null // Optional property
    var age: Int = 0 // 0 is default value
    @Ignore
    var tempId: Int = 0 // Ignored property
    @PersistedName("latin_name") // Remapped property
    var species: String? = null
}

Specify a Primary Key

You can specify a property as the object type's primary key. The primary key is a unique identifier for an object in a realm.

To specify a property as a primary key, use the @PrimaryKey annotation. For more information, refer to Primary Keys.

class Cat : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId() // Primary key
    @Index
    var name: String = "" // Indexed property
    var color: String? = null // Optional property
    var age: Int = 0 // 0 is default value
    @Ignore
    var tempId: Int = 0 // Ignored property
    @PersistedName("latin_name") // Remapped property
    var species: String? = null
}

Map a Property to a Different Name

To persist a field under a different property name, use the @PersistedName annotation. This is useful when you open a Realm across different bindings where code style conventions can differ. For more information, refer to Remap a Property.

class Cat : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId() // Primary key
    @Index
    var name: String = "" // Indexed property
    var color: String? = null // Optional property
    var age: Int = 0 // 0 is default value
    @Ignore
    var tempId: Int = 0 // Ignored property
    @PersistedName("latin_name") // Remapped property
    var species: String? = null
}

Ignore Properties from Realm Schema

By default, Realm manages properties defined in your Realm object model.

Managed properties are stored or updated in the database.
Ignored properties are not stored to the database.

You can mix managed and ignored properties within a class.

To ignore a property, use the @Ignore annotation. For more information, refer to Ignore a Field.

class Cat : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId() // Primary key
    @Index
    var name: String = "" // Indexed property
    var color: String? = null // Optional property
    var age: Int = 0 // 0 is default value
    @Ignore
    var tempId: Int = 0 // Ignored property
    @PersistedName("latin_name") // Remapped property
    var species: String? = null
}

Index Properties

To create an index on a property, use the @Index annotation. For more information, refer to Index a Field.

class Cat : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId() // Primary key
    @Index
    var name: String = "" // Indexed property
    var color: String? = null // Optional property
    var age: Int = 0 // 0 is default value
    @Ignore
    var tempId: Int = 0 // Ignored property
    @PersistedName("latin_name") // Remapped property
    var species: String? = null
}

Define Relationship Properties

You can define relationships between Realm objects in your schema. The Realm Kotlin SDK supports to-one relationships, to-many relationships, inverse relationships, and embedding objects within other objects.

To learn more about how to define relationships in your Realm object schema, refer to Relationships.

← Frozen Architecture - Kotlin SDK Change an Object Model - Kotlin SDK →