Read Realm Objects - Kotlin SDK

Frozen and Live Results

Unlike other Atlas Device SDKs, which always return live results, results with the Kotlin SDK can be frozen or live. For more information on the Kotlin SDK's frozen architecture, refer to Frozen Architecture - Kotlin SDK.

To access frozen results, run a query on a Realm. Frozen results cannot be modified and do not reflect the latest changes to the database. A Realm.query() does not require a write transaction.

To access live results, run a query on a MutableRealm instance in a write transaction. A MutableRealm represents a writeable state of a database and is only accessible through a write transaction. Results from a MutableRealm.query are live, but are only valid on the calling thread and are frozen once the write transaction completes. For more information on write transactions and accessing a MutableRealm, refer to Write Transactions.

You can also access live objects from frozen results by calling MutableRealm.findLatest() . For more information, refer to the Find Latest Version of an Object section on this page.

// 'Realm.query()' results are always frozen
val frozenResults = realm.query<Frog>("age > $0", 50).find()
// 'MutableRealm.query()' results are live within the current write transaction
realm.write { // this: MutableRealm
    val liveResults = this.query<Frog>("age > $0", 50).find()

Find Latest Version of an Object

Because of the SDK's frozen architecture, you aren't always working with the latest version of an object or collection.

To get a version of an object or collection that reflects the latest changes to the database, you can call findLatest() from a MutableRealm instance. Like a MutableRealm.query(), the results are live but are only valid on the calling thread and are frozen once the write transaction completes.

In the following example, we pass an existing frozenFrogs query's RealmResults to findLatest() to get the latest live copy of the collection. We then modify the now-live objects within the write transaction:

// Open a write transaction to access the MutableRealm
realm.write {  // this: MutableRealm
    for (frog in frozenFrogs) {
        // Call 'findLatest()' on an earlier query's frozen results
        // to return the latest live objects that you can modify
        // within the current write transaction
        findLatest(frog)?.also { liveFrog ->  
            copyToRealm(liveFrog.apply { age += 1 })
            println(liveFrog.name + " is now " + liveFrog.age + " years old")
        }
    }
}

val isFrozen = frog.isFrozen()

Query All Objects of a Type

To query all objects of a specific type, pass the RealmObject or EmbeddedRealmObject object type as a type parameter to query() without any query arguments. The SDK returns all objects of the specified type.

In the following example, we query all RealmObject objects of type Frog:

// Query all Frog objects in the database
val queryAllFrogs = realm.query<Frog>()
val allFrogs = queryAllFrogs.find()

In the following example, we query all EmbeddedRealmObject objects of type EmbeddedAddress:

val queryAllEmbeddedAddresses = realm.query<EmbeddedAddress>()
val allEmbeddedAddresses = queryAllEmbeddedAddresses.find()

You can also query an embedded object through its parent object. For more information, refer to the Filter By Embedded Object Property section on this page.

val getParent = embeddedObject.parent<Contact>()

Query a Single Object

To find a single object of a specific object type, call first() on the query. When you run the query, the SDK returns the first object that matches the conditions or null.

In the following example, we query a Frog object type and return the first object:

val querySingleFrog = realm.query<Frog>().first()
val singleFrog = querySingleFrog.find()
if (singleFrog != null) {
    println("${singleFrog.name} is a frog.")
} else {
    println("No frogs found.")
}

Filter By Property

You can filter a query by any property in the object type that persists in the database. This includes child properties, which you can refer to using dot notation.

To filter by property, you can pass Realm Query Language (RQL) filters and operators, use Kotlin's built-in extension methods or the SDK's convenience methods, or use a combination. For information on all currently supported RQL operators and syntax, refer to the Realm Query Language reference documentation.

In the following example, we query a Frog object type and filter by the name property:

val filterByProperty = realm.query<Frog>("name == $0", "Kermit")
val frogsNamedKermit = filterByProperty.find()

val filterByPrimaryKey = realm.query<Frog>("_id == $0", PRIMARY_KEY_VALUE)
val findPrimaryKey = filterByPrimaryKey.find().first()

// Use dot notation to access the embedded object properties as if it
// were in a regular nested object
val filterEmbeddedObjectProperty =
    realm.query<Contact>("address.street == '123 Pond St'")
// You can also access properties nested within the embedded object
val queryNestedProperty = realm.query<Contact>()
    .query("address.propertyOwner.name == $0", "Mr. Frog")

val filterByRealmAnyInt = realm.query<Frog>("favoriteThing.@type == 'int'")
val findFrog = filterByRealmAnyInt.find().first()

val frogsFavoriteThing = findFrog.favoriteThing // Int
// Using the correct getter method returns the value
val frogsFavoriteNumber = frogsFavoriteThing?.asInt()
println("${findFrog.name} likes the number $frogsFavoriteNumber")

// Handle possible types with a 'when' statement
frogsFavoriteThings.forEach { realmAny ->
    if (realmAny != null) {
        when (realmAny.type) {
            RealmAny.Type.INT -> {
                val intValue = realmAny.asInt()
                // Do something with intValue ...
            }
            RealmAny.Type.STRING -> {
                val stringValue = realmAny.asString()
                // Do something with stringValue ...
            }
            RealmAny.Type.OBJECT -> {
                val objectValue = realmAny.asRealmObject(Frog::class)
                // Do something with objectValue ...
            }
            // Handle other possible types...
            else -> {
                // Debug or perform a default action for unhandled types
                Log.d("Unhandled type: ${realmAny.type}")
            }
        }
    }
}

@PersistedName("latin_name")
var species: String? = null // Remapped property

val filterByKotlinName = realm.query<Frog>("species == $0", "Muppetarium Amphibius")
val findSpecies = filterByKotlinName.find().first()
val filterByRemappedName = realm.query<Frog>("latin_name == $0", "Muppetarium Amphibius")
val find_latin_name = filterByRemappedName.find().first()
// Both queries return the same object
assertEquals(findSpecies, find_latin_name)

// Filter by FTS property value using 'TEXT'
// Find all frogs with "green" in the physical description
val onlyGreenFrogs =
    realm.query<Frog>("physicalDescription TEXT $0", "green").find()
// Find all frogs with "green" but not "small" in the physical description
val onlyBigGreenFrogs =
    realm.query<Frog>("physicalDescription TEXT $0", "green -small").find()
// Find all frogs with "muppet-" and "rain-" in the physical description
val muppetsInTheRain =
    realm.query<Frog>("physicalDescription TEXT $0", "muppet* rain*").find()

// Find frogs with a favorite pond
val allFrogs = query<Frog>().find()
val frogsWithFavoritePond = allFrogs.query("favoritePonds.@size > $0", 0).find()
// Check if the list contains a value
for (frog in frogsWithFavoritePond) {
    val likesBigPond = frog.favoritePonds.any { pond -> pond.name == "Big Pond" }
    if (likesBigPond) {
        Log.v("${frog.name} likes Big Pond")
    } else {
        Log.v("${frog.name} does not like Big Pond")
    }
}

// Find frogs with flies and crickets as a favorite snack
val filterBySnackSet = query<RealmSet_Frog>("favoriteSnacks.name CONTAINS $0 AND favoriteSnacks.name CONTAINS $1", "Flies", "Crickets")
val potentialFrogs = filterBySnackSet.find()
// Check if the set contains a value
val frogsThatLikeWorms = potentialFrogs.filter { frog ->
    val requiredSnacks = query<RealmSet_Snack>("name == $0", "Worms")
    frog.favoriteSnacks.contains(requiredSnacks.find().first())
}
for (frog in frogsThatLikeWorms) {
    Log.v("${frog.name} likes both Flies, Worms, and Crickets")
}

// Find frogs who have forests with favorite ponds
val frogs = realm.query<Frog>().find()
val frogsWithFavoritePonds = frogs.query("favoritePondsByForest.@count > $0", 1).find()
val thisFrog = frogsWithFavoritePonds.first()
// Iterate through the map and log each key-value pair
for (forestName in thisFrog.favoritePondsByForest.keys) {
    val pondName = thisFrog.favoritePondsByForest[forestName]
    Log.v("Forest: $forestName, Pond: $pondName")
}
// Check if the dictionary contains a key
if (thisFrog.favoritePondsByForest.containsKey("Hundred Acre Wood")) {
    Log.v("${thisFrog.name}'s favorite pond in Hundred Acre Wood is ${thisFrog.favoritePondsByForest["Hundred Acre Wood"]}")
}
// Check if the dictionary contains a value
if (thisFrog.favoritePondsByForest.containsValue("Picnic Pond")) {
    Log.v("${thisFrog.name} lists Picnic Pond as a favorite pond")
}

// Find frogs who have a favorite pond
val allFrogs = query<Frog>().find()
val frogsWithFavoritePond = allFrogs.query("favoritePond.@count == $0", 1).find()
// Iterate through the results
for (frog in frogsWithFavoritePond) {
    Log.v("${frog.name} likes ${frog.favoritePond?.name}")
}

// Find all forests with at least one nearby pond
val allForests = query<Forest>().find()
val forestsWithPonds = allForests.query("nearbyPonds.@count > $0", 0).find()
// Iterate through the results
for (forest in forestsWithPonds) {
    val bigPond = query<Pond>("name == $0", "Big Pond").find().first()
    if (forest.nearbyPonds.contains(bigPond)) {
        Log.v("${forest.name} has a nearby pond named ${bigPond.name}")
    } else {
        Log.v("${forest.name} does not have a big pond nearby")
    }
}

// Query the parent object
val filterByUserName = query<User>("name == $0", "Kermit")
val kermit = filterByUserName.find().first()
// Use dot notation to access child objects
val myFirstPost = kermit.posts[0]
// Iterate through the backlink collection property
kermit.posts.forEach { post ->
    Log.v("${kermit.name}'s Post: ${post.date} - ${post.title}")
}
// Filter posts through the parent's backlink property
// using `@links.<ObjectType>.<PropertyName>` syntax
val oldPostsByKermit = realm.query<Post>("date < $0", today)
    .query("@links.User.posts.name == $0", "Kermit")
    .find()
// Query the child object to access the parent
val post1 = query<Post>("title == $0", "Forest Life").find().first()
val post2 = query<Post>("title == $0", "Top Ponds of the Year!").find().first()
val parent = post1.user.first()

@PersistedName(name = "Blog_Author")
class User : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var posts: RealmList<Post> = realmListOf()
}

// Filter by the remapped object type name
// using `@links.<RemappedObjectType>.<PropertyName>` syntax
val postsByKermit = realm.query<Post>()
    .query("@links.Blog_Author.posts.name == $0", "Kermit")
    .find()

Query Geospatial Data

Kotlin SDK version 1.11.0 and later adds experimental geospatial APIs that support querying with geospatial data.

Geospatial data is persisted as latitude/longitude pair in a custom embedded object's coordinates property. A geospatial query checks whether the point defined by the coordinates property is contained within the boundary of a defined geospatial shape.

The SDK supports the following geospatial shapes:

• GeoCircle: defined by a center GeoPoint and a radius Distance

• GeoBox: defined by two GeoPoint coordinates that represent the southwest and northeast corners of the box

• GeoPolygon: defined by a set of at least 4 GeoPoint coordinates that represent a closed shape. This shape can contain holes that represent exclusive boundaries within the confines of the defined polygon.

For more information on geospatial shapes and how to define them, refer to Geospatial Data - Kotlin SDK.

To query geospatial data:

1. Create an object containing the embedded geospatial data.

2. Define the geospatial shape to set the boundary for the query.

3. Query using the GEOWITHIN RQL operator. This method takes the coordinates property of your GeoJSON-compatible embedded object and checks if that point is contained within the boundary of a defined shape. The syntax is the same, regardless of the geospatial shape.

In the following example, we want to query for geospatial data persisted in a Company object through its embedded location property. We create two GeoCircle objects to set our query boundary:

val circle1 = GeoCircle.create(
    center = GeoPoint.create(47.8, -122.6),
    radius = Distance.fromKilometers(44.4)
)
val circle2 = GeoCircle.create(
    center = GeoPoint.create(47.3, -121.9),
    radius = Distance.fromDegrees(0.25)
)

We then query for any Company objects with a location contained within the defined GeoCircle boundaries:

val companiesInLargeCircle =
    realm.query<Company>("location GEOWITHIN $circle1").find()
println("Companies in large circle: ${companiesInLargeCircle.size}")
val companiesInSmallCircle =
    realm.query<Company>("location GEOWITHIN $circle2").find()
println("Companies in small circle: ${companiesInSmallCircle.size}")

Companies in large circle: 1
Companies in small circle: 0

click to enlarge