Delete Realm Objects - Kotlin SDK

Related Objects and References

When you delete an object that has a relationship property with another object, Realm does not automatically delete the instance of the related object. Instead, Realm only deletes the reference to the other object. The referenced object remains in the realm, but it can no longer be queried through the parent property.

The only exception is if the related object is embedded. When you delete an object that has a relationship with an EmbeddedRealmObject, Realm automatically deletes the embedded object in a cascading delete. For more information, refer to the Delete an Embedded Object section on this page.

Delete a Single Object

To delete a single RealmObject object, query for the object type using a filter that returns the specific object that you want to delete.

In the following example, we query for a Frog object with a specific primary key, and then pass the returned object to mutableRealm.delete() to delete it from the realm:

// Open a write transaction
realm.write {
    // Query the Frog type and filter by primary key value
    val frogToDelete: Frog = query<Frog>("_id == $0", PRIMARY_KEY_VALUE).find().first()
    // Pass the query results to delete()
    delete(frogToDelete)
}

Delete Multiple Objects

To delete multiple objects at the same time, pass the object type to query() and specify a query that returns all objects that you want to delete.

In the following example, we query for the first three Frog objects whose species is "bullfrog", and then pass the results to mutableRealm.delete() to delete them from the realm:

// Open a write transaction
realm.write {
    // Query by species and limit to 3 results
    val bullfrogsToDelete: RealmResults<Frog> = query<Frog>("species == 'bullfrog' LIMIT(3)").find()
    // Pass the query results to delete()
    delete(bullfrogsToDelete)
}

Delete All Objects of a Type

To delete all objects of a specific type from a realm at the same time, pass the object type to query() and leave the query filter empty to return all objects of that type.

In the following example, we query for all Frog objects, and then pass the results to mutableRealm.delete() to delete them all from the realm:

// Open a write transaction
realm.write {
    // Query Frog type with no filter to return all frog objects
    val frogsLeftInTheRealm = query<Frog>().find()
    // Pass the query results to delete()
    delete(frogsLeftInTheRealm)
}

Delete All Objects in a Realm

The Kotlin SDK lets you delete all managed objects of all types, which is useful for quickly clearing out your realm while prototyping. This does not affect the realm schema or any objects that are not managed by the realm.

To delete all objects from the realm at the same time, call mutableRealm.deleteAll(). This deletes all objects of all types.

In the following example, we delete all objects from the realm with deleteAll():

// Open a write transaction
realm.write {
    // Delete all objects from the realm
    deleteAll()
}

Delete an Object and Its Related Objects

To delete related objects when you delete a parent object, you must manually delete the related objects yourself. We recommend chaining deletes: first query for the parent object that you want to delete, then iterate through the parent object's relationships and delete each related object. Finally, delete the parent object itself.

In the following example, we query for a Frog object named "Kermit", then iterate through the object's favoritePonds property and delete each Pond object. Then, we delete the Frog object itself:

realm.write {
    // Query for the parent frog object with ponds
    val frog = query<Frog>("name == $0", "Kermit").find().first()
    val ponds = frog.favoritePonds
    // Iterate over the list and delete each pond object
    if (ponds.isNotEmpty()) {
        ponds.forEach { pond ->
            delete(pond)
        }
    }
    // Delete the parent frog object
    val frogToDelete = findLatest(frog)
    if (frogToDelete != null) {
        delete(frogToDelete)
    }
}

Delete an Embedded Object

You can delete an embedded object through the parent object in a cascading delete or by deleting the embedded object directly.

• To delete the embedded object through the parent object, fetch and delete the parent object. Realm automatically deletes all of its embedded objects from the realm.

• To delete an embedded object instance directly:

  • Fetch and delete a specific embedded object.

  • Clear the parent's reference to the embedded object, which also deletes the embedded object instance.

In the following example, we have a Business object with a list of embedded EmbeddedAddress objects. We query for and delete the Business object, which automatically deletes all of its embedded EmbeddedAddress objects:

// Delete the parent object
realm.write {
    val businessToDelete = query<Business>("name == $0", "Big Frog Corp.").find().first()
    // Delete the parent object (deletes all embedded objects)
    delete(businessToDelete)
}

In the following example, we have Contact objects with embedded EmbeddedAddress objects. We delete an EmbeddedAddress object directly and delete another through the parent object:

// Delete an embedded object directly
realm.write {
    val addressToDelete = query<EmbeddedAddress>("street == $0", "456 Lily Pad Ln").find().first()
    // Delete the embedded object (nullifies the parent property)
    delete(addressToDelete)
}
// Delete an embedded object through the parent
realm.write {
    val propertyToClear = query<Contact>("name == $0", "Kermit").find().first()
    // Clear the parent property (deletes the embedded object instance)
    propertyToClear.address = null
}

Remove Elements from a RealmList

You can remove one or more elements in a single transaction from a RealmList:

• To remove one element from the list, pass the element to list.remove().

• To remove one element at a specified index in the list, pass the index to list.removeAt().

• To remove multiple elements from the list, pass the elements to list.removeAll().

You can also remove all list elements at once by calling list.clear().

In the following example, we have a Forest object with a list of Pond objects. We remove the list elements in a series of operations until the list is empty:

// Open a write transaction
realm.write {
    // Query for the parent forest object
    val forest = query<Forest>("name == $0", "Hundred Acre Wood").find().first()
    val forestPonds = forest.nearbyPonds
    assertEquals(5, forestPonds.size)
    // Remove the first pond in the list
    val removeFirstPond = forestPonds.first()
    forestPonds.remove(removeFirstPond)
    assertEquals(4, forestPonds.size)
    // Remove the pond at index 2 in the list
    forestPonds.removeAt(2)
    assertEquals(3, forestPonds.size)
    // Remove the remaining three ponds in the list
    forestPonds.removeAll(forestPonds)
    assertEquals(0, forestPonds.size)
}

In the following example, we have a Forest object with a list of Pond objects. We remove all list elements with the list.clear() method:

// Open a write transaction
realm.write {
    val forest = query<Forest>("name == $0", "Hundred Acre Wood").find().first()
    val forestPonds = forest.nearbyPonds
    assertEquals(5, forestPonds.size)
    // Clear all ponds from the list
    forestPonds.clear()
    assertEquals(0, forestPonds.size)
}

Remove Elements from a RealmSet

You can remove one or more elements in a single transaction from a RealmSet:

• To remove one element from the set, pass the element you want to delete to set.remove().

• To remove multiple elements from the set, pass the elements you want to delete to set.removeAll().

You can also remove all set elements at once by calling set.clear().

In the following example, we have a Frog object with a set of Snack objects. We remove the set elements in a series of operations until the set is empty:

// Open a write transaction
realm.write {
    // Query for the parent frog object
    val myFrog = query<RealmSet_Frog>("name == $0", "Kermit").find().first()
    val snackSet = myFrog.favoriteSnacks
    assertEquals(3, snackSet.size)
    // Remove one snack from the set
    snackSet.remove(snackSet.first { it.name == "Flies" })
    assertEquals(2, snackSet.size)
    // Remove the remaining two snacks from the set
    val allSnacks = findLatest(myFrog)!!.favoriteSnacks
    snackSet.removeAll(allSnacks)
    assertEquals(0, snackSet.size)
}

In the following example, we have a Frog object with a set of Snack objects. We remove all set elements with the set.clear() method:

realm.write {
    val myFrog = realm.query<RealmSet_Frog>("name == $0", "Kermit").find().first()
    val snackSet = findLatest(myFrog)!!.favoriteSnacks
    assertEquals(3, snackSet.size)
    // Clear all snacks from the set
    snackSet.clear()
    assertEquals(0, snackSet.size)
}

Remove Dictionary Keys/Values

You can remove RealmDictionary entries in a few ways:

• To remove the value but keep the key, set the key to null (the dictionary's value must be nullable)

• To remove the key and the value, pass the key to remove()

You can also remove all keys and values by calling clear().

In the following example, we have a Frog object with a dictionary of String values. We remove the dictionary elements in a series of operations until the dictionary is empty:

// Find frogs who have forests with favorite ponds
val thisFrog = realm.query<Frog>("favoritePondsByForest.@count > 1").find().first()
// Set an optional value for a key to null if the key exists
if (thisFrog.favoritePondsByForest.containsKey("Hundred Acre Wood")) {
    realm.write {
        val mutableFrog = findLatest(thisFrog)
        if (mutableFrog != null) {
            mutableFrog.favoritePondsByForest["Hundred Acre Wood"] = null
        }
    }
}
realm.write {
    // Remove a key and its value
    findLatest(thisFrog)?.favoritePondsByForest?.remove("Lothlorien")
    // Remove all keys and values
    findLatest(thisFrog)?.favoritePondsByForest?.clear()
    assertTrue(thisFrogUpdated.favoritePondsByForest.isEmpty())
}