Ler objetos de domínio - Kotlin SDK

Resultados congelados e ao vivo

Ao contrário de outros Atlas Device SDKs, que sempre retornam resultados ao vivo, os resultados com o Kotlin SDK podem ser congelados ou ao vivo. Para obter mais informações sobre a arquitetura congelada do Kotlin SDK, consulte Arquitetura congelada - Kotlin SDK.

Para acessar os resultados congelados, execute uma consulta em um Realm. Os resultados congelados não podem ser modificados e não refletem as alterações mais recentes no banco de dados. Um Realm.query() não exige uma transação de escrita.

Para acessar os resultados em tempo real, execute uma query em uma instância do MutableRealm em uma transação de escrita. Um MutableRealm representa um estado gravável de um banco de dados e só é acessível por meio de uma transação de escrita. Os resultados de um MutableRealm.query estão ativos, mas só são válidos no thread de chamada e são congelados quando a transação de escrita é concluída. Para obter mais informações sobre transações de gravação e acesso a um MutableRealm, consulte Transações de gravação.

Você também pode acessar objetos ativos a partir de resultados congelados chamando MutableRealm.findLatest() . Para obter mais informações, consulte a seção Localizar a versão mais recente de um objeto nesta página.

// '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()

Localizar a versão mais recente de um objeto

Devido à arquitetura congelada do SDK, você nem sempre trabalhará com a versão mais recente de um objeto ou collection.

Para obter uma versão de um objeto ou coleção que reflita as alterações mais recentes no banco de dados, você pode chamar findLatest() de uma instância do MutableRealm . Como um MutableRealm.query(), os resultados estão ativos, mas são válidos apenas no tópico de chamada e são congelados quando a transação de escrita é concluída.

No exemplo abaixo, passamos uma query frozenFrogs existente de RealmResults para findLatest() para obter a cópia ao vivo mais recente da collection. Em seguida, modificamos os objetos ao vivo ativos na transação de escrita:

// 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()

Fazer query de todos os objetos de um tipo

Para fazer query de todos os objetos de um tipo específico, passe o tipo de objeto RealmObject ou EmbeddedRealmObject como um parâmetro de tipo para query() sem quaisquer argumentos de query. O SDK retorna todos os objetos do tipo especificado.

No exemplo abaixo, fazemos query de todos os objetos RealmObject do tipo Frog:

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

No exemplo abaixo, fazemos query de todos os objetos EmbeddedRealmObject do tipo EmbeddedAddress:

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

Você também pode fazer query de um objeto incorporado por meio de seu objeto principal. Para obter mais informações, consulte a seção Filtrar por propriedade de objeto incorporado nesta página.

val getParent = embeddedObject.parent<Contact>()

Fazer query de um único objeto

Para encontrar um único objeto de um tipo de objeto específico, chame first() na query. Quando você executa a consulta, o SDK retorna o primeiro objeto que corresponde às condições ou null.

No exemplo abaixo, fazemos query em um tipo de objeto Frog e retornamos o primeiro objeto:

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

Filtrar por propriedade

Você pode filtrar uma query por qualquer propriedade no tipo de objeto que persiste no banco de dados. Isso inclui propriedades secundárias, às quais você pode se referir usando a notação de ponto.

Para filtrar por propriedade, você pode passar por filtros e operadores da Realm Query Language (RQL), usar os métodos de extensão integrados do Kotlin ou os métodos de conveniência do SDK, ou usar uma combinação. Para obter informações sobre todos os operadores e sintaxe de RQL atualmente suportados, consulte a documentação de referência.

No exemplo abaixo, fazemos query em um tipo de objeto Frog e filtramos pela propriedade name:

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()

Executar query de dados geoespaciais

O Kotlin SDK versão 1.11.0 e posterior adiciona APIs geoespaciais experimentais que aceitam queries com dados geoespaciais.

Os dados geoespaciais são persistentes como par latitude/longitude em uma propriedade coordinates de objeto embarcado personalizado. Uma query geoespacial verifica se o ponto definido pela propriedade coordinates está contido dentro do limite de uma forma geoespacial definida.

O SDK aceita as seguintes formas geoespaciais:

• GeoCircle: definida por um centro GeoPoint e um raio Distance

• GeoBox: definida por duas coordenadas GeoPoint que representam os cantos sudoeste e nordeste da caixa

• GeoPolygon: definida por um conjunto de pelo menos quatro coordenadas do GeoPoint que representam uma forma fechada. Esta forma pode conter buracos que representam limites exclusivos dentro dos limites do polígono definido.

Para obter mais informações sobre formas geoespaciais e como defini-las, consulte Dados geoespaciais Kotlin SDK.

Para fazer query de dados geoespaciais:

1. Criar um objeto contendo os dados geoespaciais incorporados.

2. Definir a forma geoespacial para configurar o limite da query.

3. Fazer query usando o operador GEOWITHIN RQL. Este método utiliza a propriedade coordinates do seu objeto embarcado compatível com GeoJSONV e verifica se este ponto está contido dentro do limite de uma forma definida. A sintaxe é a mesma, independente da forma geoespacial.

No exemplo abaixo, queremos fazer query de dados geoespaciais persistentes em um objeto Company por meio de sua propriedade location incorporada. Criamos dois objetos GeoCircle para definir nosso limite 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)
)

Em seguida, fazemos query de quaisquer objetos Company com um location contido nos limites definidos de GeoCircle:

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

clique para ampliar