Quick Start - Kotlin SDK

On this page

Define Your Object Model

Open a Realm
Create, Read, Update, and Delete Objects
Complete Example

This page contains information to quickly get Realm Database integrated into your app. Before you begin, ensure you have installed the Kotlin SDK for your platform:

Define Your Object Model

Your application's data model defines the structure of data stored within Realm Database. You can define your application's data model via Kotlin classes in your application code with Realm Object Models.

To define your application's data model, add the following class definition to your application code:

class Task : RealmObject {
    var name: String = "new task"
    var status: String = "Open"
}

Open a Realm

Use RealmConfiguration to control the specifics of the realm you would like to open, including the name, location, and schema. Pass your configuration to the Realm factory constructor to generate an instance of that realm:

val config = RealmConfiguration.Builder(schema = setOf(Task::class))
    .build()
val realm: Realm = Realm.open(config)

Create, Read, Update, and Delete Objects

Once opened, you can create objects within a realm in a write transaction block.

To create a new Task, instantiate an instance of the Task class and add it to the realm in a write transaction block:

realm.writeBlocking {
    copyToRealm(Task().apply {
        name = "Do work"
        status = "Open"
    })
}

You can retrieve a collection of all tasks in the realm with query.find():

// all tasks in the realm
val tasks: RealmResults<Task> = realm.query<Task>().find()

You can also filter a collection to retrieve a more specific collection of objects:

// tasks in the realm whose name begins with the letter 'D'
val tasksThatBeginWIthD: RealmResults<Task> =
    realm.query<Task>("name BEGINSWITH $0", "D")
        .find()
val openTasks: RealmResults<Task> =
    realm.query<Task>("status == $0", "Open")
        .find()

Note

Realm Query Language

You can find more information about string Realm Database queries in Realm Query Language.

To modify a task, update its properties in a write transaction block:

// change the first task with open status to in progress status
realm.writeBlocking {
    findLatest(openTasks[0])?.status = "In Progress"
}

Finally, you can delete a task by calling mutableRealm.delete() in a write transaction block:

// delete the first task in the realm
realm.writeBlocking {
    val writeTransactionTasks = query<Task>().find()
    delete(writeTransactionTasks.first())
}

Complete Example

If you're running this project in a fresh KMM template project, you can copy and paste into the Greeting.greeting() method in the commonMain module.

val config = RealmConfiguration.Builder(schema = setOf(Task::class))
    .build()
val realm: Realm = Realm.open(config)
realm.writeBlocking {
    copyToRealm(Task().apply {
        name = "Do work"
        status = "Open"
    })
}
// all tasks in the realm
val tasks: RealmResults<Task> = realm.query<Task>().find()
// tasks in the realm whose name begins with the letter 'D'
val tasksThatBeginWIthD: RealmResults<Task> =
    realm.query<Task>("name BEGINSWITH $0", "D")
        .find()
val openTasks: RealmResults<Task> =
    realm.query<Task>("status == $0", "Open")
        .find()
// change the first task with open status to in progress status
realm.writeBlocking {
    findLatest(openTasks[0])?.status = "In Progress"
}
// delete the first task in the realm
realm.writeBlocking {
    val writeTransactionTasks = query<Task>().find()
    delete(writeTransactionTasks.first())
}

← Install (Kotlin Multiplatform) - Kotlin SDK Realm Database - Kotlin SDK →