Navigation

Read & Write Data - Android SDK

Note

The examples on this page use the data model of a project management app that has two Realm object types: Project and Task. A Project has zero or more Tasks.

See the schema for these two classes, Project and Task, below:

ProjectTask.kt
import io.realm.RealmObject
import io.realm.annotations.PrimaryKey
import io.realm.annotations.Required
import org.bson.types.ObjectId
open class ProjectTask(
@PrimaryKey
var _id: ObjectId = ObjectId(),
@Required
var name: String = "",
var assignee: String? = null,
var progressMinutes: Int = 0,
var isComplete: Boolean = false,
var priority: Int = 0,
var _partition: String = ""
): RealmObject()
Project.kt
import io.realm.RealmList
import io.realm.RealmObject
import io.realm.annotations.PrimaryKey
import io.realm.annotations.Required
import org.bson.types.ObjectId
open class Project(
@PrimaryKey
var _id: ObjectId = ObjectId(),
@Required
var name: String = "",
var tasks: RealmList<ProjectTask> = RealmList(),
var _partition: String = ""
): RealmObject()

A read from a realm generally consists of the following steps:

All query, filter, and sort operations return a results collection. The results collections are live, meaning they always contain the latest results of the associated query.

Important
Synchronous Reads and Writes on the UI Thread

By default, you can only read or write to a realm in your application's UI thread using asynchronous transactions. That is, you can only use Realm methods whose name ends with the word Async in the main thread of your Android application unless you explicitly allow the use of synchronous methods.

This restriction exists for the benefit of your application users: performing read and write operations on the UI thread can lead to unresponsive or slow UI interactions, so it's usually best to handle these operations either asynchronously or in a background thread. However, if your application requires the use of synchronous realm reads or writes on the UI thread, you can explicitly allow the use of synchronous methods with the following SyncConfiguration options:

val config = SyncConfiguration.Builder(app.currentUser(), PARTITION)
.allowQueriesOnUiThread(true)
.allowWritesOnUiThread(true)
.build()
Realm.getInstanceAsync(config, object : Realm.Callback() {
override fun onSuccess(realm: Realm) {
Log.v("EXAMPLE", "Successfully opened a realm with reads and writes allowed on the UI thread.")
}
})
Tip

To find an object with a specific primary key value, open a realm and query the primary key field for the desired primary key value using the RealmQuery.equalTo() method:

val task = realm.where(ProjectTask::class.java)
.equalTo("_id", ObjectId.get()).findFirst()
Log.v("EXAMPLE", "Fetched object by primary key: $task")

The first step of any read is to get all objects of a certain type in a realm. With this results collection, you can operate on all instances on a type or filter and sort to refine the results.

Example

In order to access all instances of Project and Task, use the where() method to specify a class:

val tasksQuery = realm.where(ProjectTask::class.java)
val projectsQuery = realm.where(Project::class.java)

A filter selects a subset of results based on the value(s) of one or more object properties. Realm Database provides a full-featured query engine you can use to define filters. The most common use case is to find objects where a certain property matches a certain value. Additionally, you can compare strings, aggregate over collections of numbers, and use logical operators to build up complex queries.

Example

In the following example, we use the query engine's comparison operators to:

  • Find high priority tasks by comparing the value of the priority property value with a threshold number, above which priority can be considered high.
  • Find just-started or short-running tasks by seeing if the progressMinutes property falls within a certain range.
  • Find unassigned tasks by finding tasks where the assignee property is equal to null.
  • Find tasks assigned to specific teammates Ali or Jamie by seeing if the assignee property is in a list of names.
val tasksQuery = realm.where(ProjectTask::class.java)
Log.i(
"EXAMPLE", "High priority tasks: " + tasksQuery.greaterThan(
"priority",
5
).count()
)
Log.i(
"EXAMPLE", "Just-started or short tasks: " + tasksQuery.between(
"progressMinutes",
1,
10
).count()
)
Log.i(
"EXAMPLE",
"Unassigned tasks: " + tasksQuery.isNull("assignee").count()
)
Log.i(
"EXAMPLE", "Ali or Jamie's tasks: " + tasksQuery.`in`(
"assignee", arrayOf(
"Ali",
"Jamie"
)
).count()
)

A sort operation allows you to configure the order in which Realm Database returns queried objects. You can sort based on one or more properties of the objects in the results collection.

Realm Database only guarantees a consistent order of results when the results are sorted.

Example

The following code sorts the projects by name in reverse alphabetical order (i.e. "descending" order).

val projectsQuery = realm.where(Project::class.java)
val results = projectsQuery.sort("name", Sort.DESCENDING).findAll()

Consider the following relationship between classes Person and Dog. This arrangement allows each person to own a single dog:

import io.realm.RealmObject
import io.realm.annotations.PrimaryKey
import org.bson.types.ObjectId
open class Person(var name : String? = null) : RealmObject() {
@PrimaryKey
var _id : ObjectId = ObjectId()
var dog: Dog? = null
}
import io.realm.RealmList
import io.realm.RealmObject
import io.realm.RealmResults
import io.realm.annotations.LinkingObjects
import io.realm.annotations.PrimaryKey
import org.bson.types.ObjectId
open class Dog(var name : String? = null): RealmObject() {
@PrimaryKey
var _id : ObjectId = ObjectId()
var owner: RealmList<Person>? = null
}

To query this relationship, use dot notation in a query to access any property of the linked object:

val config = SyncConfiguration.Builder(app.currentUser(), PARTITION)
.allowQueriesOnUiThread(true)
.allowWritesOnUiThread(true)
.build()
Realm.getInstanceAsync(config, object : Realm.Callback() {
override fun onSuccess(realm: Realm) {
Log.v(
"EXAMPLE",
"Successfully opened a realm with reads and writes allowed on the UI thread."
)
realm.executeTransaction { transactionRealm ->
val owner = transactionRealm.where<Person>().equalTo("dog.name", "henry").findFirst()
val dog = owner?.dog
Log.v("EXAMPLE", "Queried for people with dogs named 'henry'. Found $owner, owner of $dog")
}
realm.close()
}
})

Consider the following relationship between classes Dog and Person. In this example, all dogs link to their owner (or multiple owners, if multiple person objects refer to the same dog). Realm calculates the owners of each dog for you based on the field name you provide to the @LinkingObjects annotation:

import io.realm.RealmList
import io.realm.RealmObject
import io.realm.RealmResults
import io.realm.annotations.LinkingObjects
import io.realm.annotations.PrimaryKey
import org.bson.types.ObjectId
open class Dog(var name : String? = null): RealmObject() {
@PrimaryKey
var _id : ObjectId = ObjectId()
var owner: RealmList<Person>? = null
}
import io.realm.RealmObject
import io.realm.annotations.PrimaryKey
import org.bson.types.ObjectId
open class Person(var name : String? = null) : RealmObject() {
@PrimaryKey
var _id : ObjectId = ObjectId()
var dog: Dog? = null
}

To query this relationship, use dot notation in a query to access any property of the linked object:

val config = SyncConfiguration.Builder(app.currentUser(), PARTITION)
.allowQueriesOnUiThread(true)
.allowWritesOnUiThread(true)
.build()
Realm.getInstanceAsync(config, object : Realm.Callback() {
override fun onSuccess(realm: Realm) {
Log.v(
"EXAMPLE",
"Successfully opened a realm with reads and writes allowed on the UI thread."
)
realm.executeTransaction { transactionRealm ->
val dog = transactionRealm.where<Dog>().equalTo("owner.name", "dwayne").findFirst()
val owner = dog?.owner?.first()
Log.v("EXAMPLE", "Queried for dogs with owners named 'dwayne'. Found $dog, owned by $owner")
}
realm.close()
}
})
val tasksQuery = realm.where(ProjectTask::class.java)
/* Aggregate operators do not support dot-notation, so you cannot directly operate on a property of all of the objects in a collection property. You can operate on a numeric property of the top-level object, however: */Log.i("EXAMPLE", "Tasks average priority: " + tasksQuery.average("priority"))

All write operations to a realm must occur within a write transaction. For more information about how to perform a write transaction, see Write Transactions.

Important
Realm Object Writes are File Writes

Whenever you create, update, or delete a Realm object, your changes update the representation of that object in Realm Database and emit notifications to any subscribed listeners. As a result, you should only write to Realm objects when necessary to persist data.

Important
Synchronous Reads and Writes on the UI Thread

By default, you can only read or write to a realm in your application's UI thread using asynchronous transactions. That is, you can only use Realm methods whose name ends with the word Async in the main thread of your Android application unless you explicitly allow the use of synchronous methods.

This restriction exists for the benefit of your application users: performing read and write operations on the UI thread can lead to unresponsive or slow UI interactions, so it's usually best to handle these operations either asynchronously or in a background thread. However, if your application requires the use of synchronous realm reads or writes on the UI thread, you can explicitly allow the use of synchronous methods with the following SyncConfiguration options:

val config = SyncConfiguration.Builder(app.currentUser(), PARTITION)
.allowQueriesOnUiThread(true)
.allowWritesOnUiThread(true)
.build()
Realm.getInstanceAsync(config, object : Realm.Callback() {
override fun onSuccess(realm: Realm) {
Log.v("EXAMPLE", "Successfully opened a realm with reads and writes allowed on the UI thread.")
}
})

Instantiate Realm objects as you would any other object. In a transaction, you can add the object to the realm if the realm's schema includes the object type. When you add an instance to the realm, it becomes managed by that realm.

With the Java and JavaScript SDKs, instead use the realm's factory method in a transaction to instantiate your class. This automatically inserts the instance into the realm.

Example

This code demonstrates how to create an object with createObject():

realm.executeTransaction { r: Realm ->
// Instantiate the class using the factory function.
val turtle = r.createObject(Turtle::class.java, ObjectId())
// Configure the instance.
turtle.name = "Max"
// Create a TurtleEnthusiast with a primary key.
val primaryKeyValue = ObjectId()
val turtleEnthusiast = r.createObject(
TurtleEnthusiast::class.java,
primaryKeyValue
)
}

You can also insert objects into a realm from JSON. Realm supports creating objects from String, JSONObject, and InputStream types. Realm ignores any properties present in the JSON that are not defined in the Realm object schema.

Example

This code demonstrates how to create a single object from JSON with createObjectFromJson() or multiple objects from JSON with createAllFromJson():

// Insert from a string
realm.executeTransaction { realm ->
realm.createObjectFromJson(
Frog::class.java,
"{ name: \"Doctor Cucumber\", age: 1, species: \"bullfrog\", owner: \"Wirt\" }"
)
}
// Insert multiple items using an InputStream
realm.executeTransaction { realm ->
try {
val inputStream: InputStream =
FileInputStream(File("path_to_file"))
realm.createAllFromJson(Frog::class.java, inputStream)
} catch (e: IOException) {
throw RuntimeException(e)
}
}

Within a transaction, you can update a Realm object the same way you would update any other object in your language of choice. Just assign a new value to the property or update the property.

Example

This code changes the turtle's name to "Archibald" and sets Archibald's age to 101 by assigning new values to properties:

realm.executeTransaction { r: Realm ->
// Get a turtle to update.
val turtle = r.where(Turtle::class.java).findFirst()
// Update properties on the instance.
// This change is saved to the realm.
turtle!!.name = "Archibald"
turtle.age = 101
}

An upsert is a write operation that either inserts a new object with a given primary key or updates an existing object that already has that primary key. We call this an upsert because it is an "update or insert" operation. This is useful when an object may or may not already exist, such as when bulk importing a dataset into an existing realm. Upserting is an elegant way to update existing entries while adding any new entries.

Example

This code demonstrates how to upsert an object with realm. We create a new turtle enthusiast named "Drew" and then update their name to "Andy" using insertOrUpdate():

realm.executeTransaction { r: Realm ->
val id = ObjectId()
val drew = TurtleEnthusiast()
drew._id = id
drew.name = "Drew"
drew.age = 25
// Add a new turtle enthusiast to the realm. Since nobody with this id
// has been added yet, this adds the instance to the realm.
r.insertOrUpdate(drew)
val andy = TurtleEnthusiast()
andy._id = id
andy.name = "Andy"
andy.age = 56
// Judging by the ID, it's the same turtle enthusiast, just with a different name.
// As a result, you overwrite the original entry, renaming "Drew" to "Andy".
r.insertOrUpdate(andy)
}

You can also use copyToRealmOrUpdate() to either create a new object based on a supplied object or update an existing object with the same primary key value. Use the CHECK_SAME_VALUES_BEFORE_SET ImportFlag to only update fields that are different in the supplied object:

Example

This code demonstrates how to insert an object or, if an object already exists with the same primary key, update only those fields that differ:

realm.executeTransaction { r: Realm ->
val id = ObjectId()
val drew = TurtleEnthusiast()
drew._id = id
drew.name = "Drew"
drew.age = 25
// Add a new turtle enthusiast to the realm. Since nobody with this id
// has been added yet, this adds the instance to the realm.
r.insertOrUpdate(drew)
val andy = TurtleEnthusiast()
andy._id = id
andy.name = "Andy"
// Judging by the ID, it's the same turtle enthusiast, just with a different name.
// As a result, you overwrite the original entry, renaming "Drew" to "Andy".
r.copyToRealmOrUpdate(andy,
ImportFlag.CHECK_SAME_VALUES_BEFORE_SET)
}

Realm Database supports collection-wide updates. A collection update applies the same update to specific properties of several objects in a collection at once.

Example

The following code demonstrates how to update a collection. Thanks to the implicit inverse relationship between the Turtle's owner property and the TurtleEnthusiast's turtles property, Realm Database automatically updates Josephine's list of turtles when you use setObject() to update the "owner" property for all turtles in the collection.

realm.executeTransaction { r: Realm ->
// Create a turtle enthusiast named Josephine.
val josephine = realm.createObject(
TurtleEnthusiast::class.java,
ObjectId()
)
josephine.name = "Josephine"
// Get all turtles named "Pierogi".
val turtles = r.where(Turtle::class.java)
.equalTo("name", "Pierogi")
.findAll()
// Give all turtles named "Pierogi" to Josephine
turtles.setObject("owner", josephine)
}

Because realm collections always reflect the latest state, they can appear, disappear, or change while you iterate over a collection. To get a stable collection you can iterate over, you can create a snapshot of a collection's data. A snapshot guarantees the order of elements will not change, even if an element is deleted or modified.

Iterator objects created from RealmResults use snapshots automatically. Iterator objects created from RealmList instances do not use snapshots. Use RealmList.createSnapshot() or RealmResults.createSnapshot() to manually generate a snapshot you can iterate over manually:

Example

The following code demonstrates how to iterate over a collection safely using either an implicit snapshot created from a RealmResults Iterator or a manual snapshot created from a RealmList:

val frogs = realm.where(Frog::class.java)
.equalTo("species", "bullfrog")
.findAll()
// Use an iterator to rename the species of all bullfrogs
realm.executeTransaction {
for (frog in frogs) {
frog.species = "Lithobates catesbeiana"
}
}
// Use a snapshot to rename the species of all bullfrogs
realm.executeTransaction {
val frogsSnapshot = frogs.createSnapshot()
for (i in frogsSnapshot.indices) {
frogsSnapshot[i]!!.species = "Lithobates catesbeiana"
}
}

To delete an object from a realm, use either the dynamic or static versions of the deleteFromRealm() method of a RealmObject subclass.

Important
Do not use objects after delete

Realm Database throws an error if you try to use an object after it has been deleted.

Example

The following code shows how to delete one object from its realm with deleteFromRealm():

realm.executeTransaction { r: Realm ->
// Get a turtle named "Tony".
var tony = r.where(Turtle::class.java)
.equalTo("name", "Tony")
.findFirst()
tony!!.deleteFromRealm()
// discard the reference
tony = null
}

To delete an object from a realm, use the deleteAllFromRealm() method of the RealmResults instance that contains the objects you would like to delete. You can filter the RealmResults down to a subset of objects using the where() method.

Example

The following code demonstrates how to delete a collection from a realm with deleteAllFromRealm():

realm.executeTransaction { r: Realm ->
// Find turtles older than 2 years old.
val oldTurtles = r.where(Turtle::class.java)
.greaterThan("age", 2)
.findAll()
oldTurtles.deleteAllFromRealm()
}

Sometimes, you have dependent objects that you want to delete when you delete the parent object. We call this a cascading delete. Realm Database does not delete the dependent objects for you. If you do not delete the objects yourself, they will remain orphaned in your realm. Whether or not this is a problem depends on your application's needs.

Currently, the best way to delete dependent objects is to iterate through the dependencies and delete them before deleting the parent object.

Example

The following code demonstrates how to perform a cascading delete by first deleting all of Ali's turtles, then deleting Ali:

realm.executeTransaction { r: Realm ->
// Find a turtle enthusiast named "Ali"
val ali = r.where(TurtleEnthusiast::class.java)
.equalTo("name", "Ali").findFirst()
// Delete all of ali's turtles
ali!!.turtles!!.deleteAllFromRealm()
ali.deleteFromRealm()
}

Realm Database supports deleting all instances of a Realm type from a realm.

Example

The following code demonstrates how to delete all Turtle instances from a realm with delete():

realm.executeTransaction { r: Realm ->
r.delete(Turtle::class.java)
}

It is possible to delete all objects from the realm. This does not affect the schema of the realm. This is useful for quickly clearing out your realm while prototyping.

Example

The following code demonstrates how to delete everything from a realm with deleteAll():

realm.executeTransaction { r: Realm ->
r.deleteAll()
}
Give Feedback