From 852ed05bcd81c292d95a2c616ee5f65cd233f65d Mon Sep 17 00:00:00 2001 From: cbullinger Date: Tue, 10 Oct 2023 11:22:33 -0400 Subject: [PATCH] Move note --- .../sdk/kotlin/realm-database/crud/delete.txt | 143 +++++++++--------- 1 file changed, 73 insertions(+), 70 deletions(-) diff --git a/source/sdk/kotlin/realm-database/crud/delete.txt b/source/sdk/kotlin/realm-database/crud/delete.txt index d6df5b70f6..212df1df90 100644 --- a/source/sdk/kotlin/realm-database/crud/delete.txt +++ b/source/sdk/kotlin/realm-database/crud/delete.txt @@ -22,6 +22,13 @@ or affect the realm schema. It only deletes the object instance from the realm. If you want to delete the realm file itself, refer to :ref:``. +.. note:: Write to a Synced Realm + + The syntax to delete an object from a realm is the same for a local or + a synced realm. However, there are additional considerations that determine + whether the delete operation in a synced realm is successful. For more + information, refer to :ref:``. + Write Transactions ------------------ @@ -37,13 +44,6 @@ instance, and then delete objects within the realm. For more information on write transactions and how Realm handles them, refer to :ref:``. -.. note:: Write to a Synced Realm - - The syntax to delete an object from a realm is the same for a local or - a synced realm. However, there are additional considerations that determine - whether the delete operation in a synced realm is successful. For more - information, refer to :ref:``. - You can only delete live objects, which are only accessible inside of a write transaction. You can convert a frozen object to a live object in a transaction with `mutableRealm.findLatest() @@ -207,6 +207,72 @@ In the following example, we delete all objects from the realm with ``deleteAll( 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. +Delete Related Objects +---------------------- + +Deleting a parent object *does not* automatically delete any objects that are +related to it unless the related object is embedded. +Instead, Realm only deletes the reference to the related object. + +In the following example, we have a ``Frog`` object with a list of +``Pond`` objects. After we delete the ``Frog`` object, we confirm that all +``Pond`` objects still remain in the realm: + +.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.delete-realm-object-with-related-objects.kt + :language: kotlin + +.. _kotlin-delete-related-objects: + +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 performing a **chaining delete**. +To perform a chaining delete, you 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: + +.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.chain-delete-realm-list.kt + :language: kotlin + +.. _kotlin-delete-embedded-objects: + +Delete an Embedded Object +------------------------- + +.. warning:: Realm Uses Cascading Deletes for Embedded Objects + + When you delete a Realm object, Realm automatically deletes any + embedded objects referenced by that object. + If you want the referenced objects to persist after the deletion of the + parent object, use a regular Realm object with a :ref:`to-one relationship + ` instead. + +You can delete an embedded object directly: + +- Fetch and delete a specific embedded object +- Clear the parent's reference to the embedded object, which also deletes the embedded object instance. + +Alternatively, you can delete the parent object, which automatically deletes all +of its embedded objects. + +In the following example, we have a ``Contact`` object with an embedded +``Address`` object and a ``Business`` object with a list of embedded +``Contact`` objects: + +.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.delete-embedded-object.kt + :language: kotlin + +.. tip:: Get Embedded Object's Parent + + You can get the unique parent of an embedded object using + `parent() <{+kotlin-local-prefix+}io.realm.kotlin.ext/parent.html>`__. + Remove Elements from Collections -------------------------------- @@ -293,66 +359,3 @@ until the dictionary is empty: .. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.delete-realm-dictionary.kt :language: kotlin - -.. _kotlin-delete-related-objects: - -Delete Related Objects ----------------------- - -Deleting a parent object *does not* automatically delete any objects that are -related to it unless the related object is embedded. -Instead, Realm only deletes the reference to the related object. - -In the following example, we have a ``Frog`` object with a list of -``Pond`` objects. After we delete the ``Frog`` object, we confirm that all -``Pond`` objects still remain in the realm: - -.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.delete-realm-object-with-related-objects.kt - :language: kotlin - -To delete related objects when you delete a parent object, you must manually -delete the related objects yourself. We recommend performing a **chaining delete**. -To perform a chaining delete, you 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: - -.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.chain-delete-realm-list.kt - :language: kotlin - -.. _kotlin-delete-embedded-objects: - -Delete an Embedded Object -------------------------- - -.. warning:: Realm Uses Cascading Deletes for Embedded Objects - - When you delete a Realm object, Realm automatically deletes any - embedded objects referenced by that object. - If you want the referenced objects to persist after the deletion of the - parent object, use a regular Realm object with a :ref:`to-one relationship - ` instead. - -You can delete an embedded object directly: - -- Fetch and delete a specific embedded object -- Clear the parent's reference to the embedded object, which also deletes the embedded object instance. - -Alternatively, you can delete the parent object, which automatically deletes all -of its embedded objects. - -In the following example, we have a ``Contact`` object with an embedded -``Address`` object and a ``Business`` object with a list of embedded -``Contact`` objects: - -.. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.delete-embedded-object.kt - :language: kotlin - -.. tip:: Get Embedded Object's Parent - - You can get the unique parent of an embedded object using - `parent() <{+kotlin-local-prefix+}io.realm.kotlin.ext/parent.html>`__.