Leer objetos Realm - 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.

Para acceder a resultados en vivo, ejecuta una query en una instancia MutableRealm en una transacción de escritura. Un MutableRealm representa un estado escribible de una base de datos y solo es accesible a través de una transacción de escritura. Los resultados de una MutableRealm.query son en vivo, pero solo son válidos en el hilo que los llama y quedan congelados una vez que la transacción de escritura se completa. Para obtener más información sobre las transacciones de escritura y el acceso a un MutableRealm, consulte Transacciones de escritura.

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.

Para obtener una versión de un objeto o colección que refleje los últimos cambios en la base de datos, puede llamar a findLatest() desde una MutableRealm instancia. Al igual que con una MutableRealm.query() instancia, los resultados están activos,pero solo son válidos en el hilo que los llama y se congelan una vez completada la transacción de escritura.

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 todos los objetos de un tipo

Para consultar todos los objetos de un tipo específico, pase el RealmObject EmbeddedRealmObject tipo de objeto o como parámetro de tipo a query() sin ningún argumento de consulta. El SDK devuelve todos los objetos del tipo especificado.

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 un objeto individual

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.

Para filtrar por propiedad, puede usar filtros y operadores de Realm Query Language (RQL), utilizar los métodos de extensión incorporados de Kotlin o los métodos de conveniencia del SDK, o una combinación. Para información sobre todos los operadores y sintaxis RQL actualmente admitidos, consulta la documentación de referencia del Realm Query Language.

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 datos geoespaciales

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.

El SDK es compatible con las siguientes formas geoespaciales:

• 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.

Para query datos geoespaciales:

1. Create an object containing the embedded geospatial data.

2. Define la forma geoespacial para establecer el límite de la 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.

En el siguiente ejemplo, se desea hacer una query para datos geoespaciales almacenados en un objeto Company a través de su propiedad incrustada location. Creamos dos objetos GeoCircle para establecer nuestro límite de query:

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

haga clic para ampliar