MongoDB Realm Android SDK¶

The MongoDB Realm Android SDK allows you to use Realm Database and backend Realm apps from Android applications written in Java or Kotlin.

Note

The Android SDK does not support Java or Kotlin applications written for environments other than Android.

Local Realm Database¶

With the MongoDB Realm Android SDK, you can access objects stored in a local instance of Realm Database. With Realm Database, you can:

Define an Object Schema¶

Define your object schema with annotated Kotlin or Java classes:

import io.realm.RealmObject
open class Frog(var name: String = "",
                var age: Int = 0,
                var species: String? = null,
                var owner: String? = null): RealmObject()

Query Realm Database¶

Query for stored objects using Android-native queries:

val config = RealmConfiguration.Builder()
    .allowQueriesOnUiThread(true)
    .allowWritesOnUiThread(true)
    .build()
val realm = Realm.getInstance(config)
val frogsQuery = realm.where(Frog::class.java)
val numTadpoles =
    frogsQuery.lessThan("age", 2).count()
Log.i("EXAMPLE",
    "Tadpoles: $numTadpoles")
val numFrogsNamedJasonFunderburker =
    frogsQuery.equalTo("name", "Jason Funderburker").count()
Log.i("EXAMPLE",
    "Frogs named Jason Funderburker: $numFrogsNamedJasonFunderburker")
val numFrogsWithoutOwners =
    frogsQuery.isNull("owner").count()
Log.i("EXAMPLE",
    "Frogs without owners: $numFrogsWithoutOwners")

Update Live Objects¶

Update objects in Realm Database by updating field values on an instance of the object within a transaction:

val config =
    RealmConfiguration.Builder()
        .build()
val realm = Realm.getInstance(config)
// start a write transaction
realm.executeTransactionAsync { transactionRealm: Realm ->
    // get a frog from the database to update
    val frog = transactionRealm.where(Frog::class.java)
        .equalTo("name", "Benjamin Franklin").findFirst()
    // change the frog's name
    frog?.name = "George Washington"
    // change the frog's species
    frog?.species = "American bullfrog"
} // when the transaction completes, the frog's name and species
// are updated in the database

Watch for Object Updates¶

Receive object updates and notifications automatically when objects stored in Realm Database change:

// configure and open a local realm
val config = RealmConfiguration.Builder()
    .allowQueriesOnUiThread(true)
    .allowWritesOnUiThread(true)
    .build()
val realm = Realm.getInstance(config)
// create an reference to a frog
var frog : Frog? = null
// insert a new frog into the database and store it in our reference
realm.executeTransaction { transactionRealm: Realm ->
    frog = transactionRealm.createObject(Frog::class.java)
    frog?.name = "Doctor Cucumber"
    frog?.age = 3
    frog?.species = "Tree Frog"
    frog?.owner = "Greg"
}
// create a listener that logs new changes to the frog
val listener = RealmObjectChangeListener { changedFrog: Frog?,
                                           changeSet: ObjectChangeSet? ->
    if (changeSet!!.isDeleted) {
        Log.i("EXAMPLE", "The frog was deleted")
    } else {
        for (fieldName in changeSet.changedFields) {
            Log.i("EXAMPLE", "Field '$fieldName' changed.")
        }
    }
}
// attach the listener we just created to the frog
frog?.addChangeListener(listener)
// update the frog
realm.executeTransaction { frog?.name = "Ronald" }

Always Access the Latest Data¶

Live objects keep all instances of an object up to date at all times:

// configure and open a local realm
val config = RealmConfiguration.Builder()
    .allowQueriesOnUiThread(true)
    .allowWritesOnUiThread(true)
    .build()
val realmA = Realm.getInstance(config)
val realmB = Realm.getInstance(config)
// get a reference to a single frog object
// stored in the database from each realm instance
val frogA = realmA.where(Frog::class.java)
    .equalTo("name", "Mr. President")
    .findFirst()
val frogB = realmB.where(Frog::class.java)
    .equalTo("name", "Mr. President")
    .findFirst()
// update frog A's name
realmA.executeTransaction { frogA?.name = "Skipper" }
// frog B instance automatically updates with the new name
assert(frogA?.name === frogB?.name)
// update frog B's age
realmB.executeTransaction { frogB?.age = 10 }
// frog A instance automatically updates with the new age
assert(frogB?.age === frogA?.age)

Tip

Realm Apps¶

Realm apps are backends for client applications hosted by MongoDB in the cloud. They provide the ability to synchronize data stored in Realm Database, called Realm Sync, as well as a layer of backend functionality collectively called App Services. The MongoDB Realm Android SDK optionally contains the ability to access these Realm apps running in the cloud. In addition to local Realm Database in the SDK, Realm apps provide the following functionality:

Realm Sync¶

Automatically sync data between realms on client devices and your backend MongoDB Atlas data store with Realm Sync:

// Sync uses SyncConfiguration instead of RealmConfiguration,
// and requires both a logged-in user and a partition value
val config : SyncConfiguration =
    SyncConfiguration.Builder(app.currentUser(), "myPartition")
        .build()
val realm = Realm.getInstance(config)
// start a write transaction
realm.executeTransactionAsync { transactionRealm: Realm ->
    // get a frog from the database to update
    val frog =
        transactionRealm.where(FrogJava::class.java)
            .equalTo("name", "Benjamin Franklin").findFirst()
    // change the frog's name
    frog!!.setName("George Washington")
    // change the frog's species
    frog.setSpecies("American bullfrog")
} // when the transaction completes, the frog's name and species
// are updated in the database and synced to the connected Realm App

App Services¶

Use Realm's built-in user management to enable user account creation and user authentication across devices.
Store data persistently with permissions in your backend Realm app using a MongoDB Atlas database.
Execute logic in your backend Realm app from a client application using Functions.
React to events in your backend Realm app using Triggers.

Tip

Get Started¶

To start using the MongoDB Realm Android SDK in your Android application, see Install Realm for Android to add the Android SDK dependency and then check out the Quick Start.

To learn more about the concepts that underly Realm Database, such as the Asynchronous API, the Query Engine, and more, check out the Fundamentals.

For practical code samples of common tasks in Realm Database and Realm apps, take a look at the Examples.

Get Started	Fundamentals	Examples	Realm Apps Examples
Install Realm for Android Quick Start Quick Start with Sync Quick Start with LiveData Upgrade from Stitch to Realm	Asynchronous API Realms Live Queries Query Engine Write Transactions Relationships Object Models & Schemas Schema Versions & Migrations Application Services	Define a Realm Object Schema Open & Close a Local Realm Read & Write Data Filter Data React to Changes Modify an Object Schema	Connect to a MongoDB Realm Backend App Authenticate Users Sync Changes Between Devices Call a Function Manage Email/Password Users Create & Manage User API Keys Query MongoDB

Advanced Guides¶

Realm Database	Realm Apps
Encryption Threading Testing	Link User Identities Multi-User Applications Custom User Data Client Resets

Give Feedback

← Realm SDKs Install Realm - Android SDK →