Delete Objects and Property Values
On this page
- Delete Operations
- Related Objects and References
- Delete Objects
- Delete a Single Object
- Delete Multiple Objects
- Delete All Objects of a Type
- Delete All Objects in the Database
- Delete Related Objects
- Delete an Object and Its Related Objects
- Delete an Embedded Object
- Delete Property Values
- Delete an Inverse Relationship
- Delete Mixed Property Values
- Remove Elements from Collections
- Remove Elements from a List
- Remove Elements from a Set
- Remove Dictionary Keys/Values
This page describes how to delete objects from a non-synced or synced database using Atlas Device SDK.
You can choose to delete a single object, multiple objects, or all objects from the database. After you delete an object, you can no longer access or modify it. If you try to use a deleted object, the SDK throws an error.
Deleting objects from a database does not delete the database file or affect the database schema. It only deletes the object instance from the database. If you want to delete the database file itself, refer to Delete a Database File. If you want to remove objects or properties from the database schema, refer to Change an Object Model.
Note
Write to a Synced Database
The syntax to delete an object from the database is the same for a non-synced or a synced database. However, there are additional considerations that determine whether the delete operation in a synced database is successful. For more information, refer to Write Data to a Synced Database.
Delete Operations
Delete operations must be performed inside of a write transaction. For more information on write transactions and how the SDK handles them, refer to Write Transactions.
Related Objects and References
When you delete an object that has a relationship property with another object, the SDK does not automatically delete the instance of the related object. Instead, the SDK only deletes the reference to the other object. The referenced object instance remains in the database, but it can no longer be queried through the relationship property.
Embedded objects are handled differently. When you delete an object that contains an embedded object, the SDK automatically deletes the embedded object in a cascading delete. This is because embedded objects do not have a lifecycle outside of their parent object. For more information, refer to the Delete an Embedded Object section on this page.
Chaining Deletes with Related SDK Objects
If you want to delete any related objects when you delete a parent object, we recommend performing a chaining delete. A chaining delete consists of manually deleting dependent objects by iterating through the dependencies and deleting them before deleting the parent object. For more information on chaining deletes, refer to the Delete Related Objects section on this page.
If you do not delete the related objects yourself, they remain in your database. Whether or not this is a problem depends on your application's needs.
Delete Objects
Delete a Single Object
Tip
Use Unique Identifying Information
We recommend using unique identifying information to find the object you want to delete, such as a primary key value, to ensure your query returns the correct object.
Delete Multiple Objects
Delete All Objects of a Type
Delete All Objects in the Database
The SDK lets you delete all managed objects of all types, which is useful for quickly clearing out your database while prototyping. For example, instead of writing a migration to update objects to a new schema, it may be faster to delete all, and then re-generate the objects with the app itself.
This does not affect the database schema or any objects that are not managed by the database instance.
Delete Related Objects
Deleting an object does not automatically delete any objects that are related to it unless the related object is embedded. Instead, the SDK only deletes the reference to the related object.
You can optionally define logic in your app to delete related objects. Or if an object lifecycle should not outlive a parent object, model it as an embedded object instead of an independent object with a relationship.
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.
Delete an Embedded Object
Warning
The SDK Uses Cascading Deletes for Embedded Objects
When you delete a Realm object, the SDK automatically deletes any
embedded objects referenced by that object. This is because embedded objects
are objects tha do not exist independent of the Realm object, and do
not have their own lifecycle. If you want the referenced objects to persist
after the deletion of the main object, use a regular Realm object with a
to-one relationship instead.
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. The SDK automatically deletes all of its embedded objects from the database.
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.
Delete Property Values
Delete an Inverse Relationship
You can't delete an inverse relationship directly. Instead, an inverse relationship automatically updates by removing the relationship through the related object.
Delete Mixed Property Values
Although mixed property instances cannot store null values, you can
delete a mixed property value by assigning your language's implementation of
null or nil directly to the property. For more information on the
mixed data type, refer to Generic (Mixed) Data Type.
Remove Elements from Collections
SDK collection instances that contain objects only store references to those objects. You can remove one or more referenced objects from a collection without deleting the objects themselves. The objects that you remove from a collection remain in the database until you manually delete them. Alternatively, deleting an SDK object from a database also deletes that object from any collection instances that contain the object.