(DOCSP-39516): Consolidate Delete page

source/includes/api-details/cpp/crud/delete-all-objects-not-supported.rst

@@ -0,0 +1,3 @@
+C++ does not currently provide a method to delete all objects in the database.
+You can manually iterate through the objects and delete them if you need to
+clear the database.

source/includes/api-details/cpp/crud/delete-all-objects-of-type-not-supported.rst

@@ -0,0 +1 @@
+C++ does not currently provide an API to delete all objects of a type.

source/includes/api-details/cpp/crud/delete-inverse-relationship-description.rst

@@ -0,0 +1,4 @@
+In this example, a ``Person`` has a to-one relationship to a ``Dog``,
+and the ``Dog`` has an inverse relationship to ``Person``.
+Setting the ``Person.dog`` relationship to ``nullptr`` removes the inverse
+relationship from the ``Dog`` object. 

source/includes/api-details/cpp/crud/delete-multiple-objects-description.rst

@@ -0,0 +1 @@
+You can delete multiple objects within a write transaction.

source/includes/api-details/cpp/crud/delete-objects-procedure.rst

@@ -0,0 +1,25 @@
+1. Open a write transaction with :cpp-sdk:`db.write()
+   <structrealm_1_1db.html>`.
+
+#. Pass the object(s) you want to delete into the write block, or query for
+   them inside the block.
+
+   .. important:: Objects Must Be Live
+
+      You can only delete live objects. If you are working with a frozen
+      object or thread-safe reference, you must ``thaw()`` the object or 
+      ``resolve()`` the thread-safe reference before deleting the object.
+      For more details, refer to :ref:`sdks-threading`.
+
+#. Call the ``remove()`` method with the object you want to delete as an
+   argument.
+
+#. The specified objects are deleted from the database and can no longer be
+   accessed or modified. If you try to use a deleted object, the SDK throws an
+   error.
+
+   If any deleted objects had a relationship with another object, the SDK
+   only deletes the reference to the other object. The referenced object
+   remains in the database, but it can no longer be queried through the deleted 
+   parent property. Refer to the :ref:`sdks-delete-related-objects` section
+   for more information.

source/includes/api-details/cpp/crud/delete-operations-description.rst

@@ -0,0 +1,3 @@
+To delete an object from the database, pass the object to the
+:cpp-sdk:`db.remove() function <structrealm_1_1db.html>`
+inside of a write transaction.

source/includes/api-details/cpp/crud/delete-remove-dictionary-keys-values-description.rst

@@ -0,0 +1,3 @@
+To delete a :cpp-sdk:`map key
+<structrealm_1_1managed_3_01std_1_1map_3_01std_1_1string_00_01T_01_4_00_01void_01_4.html>`, 
+pass the key name to ``erase()``.

source/includes/api-details/cpp/crud/delete-remove-elements-from-list-description.rst

@@ -0,0 +1,3 @@
+You can delete a :cpp-sdk:`list element 
+<structrealm_1_1managed_3_01std_1_1vector_3_01T_01_5_01_4_01_4.html>` 
+with ``erase()``, or remove all elements from the list with ``clear()``.

source/includes/api-details/cpp/crud/delete-remove-elements-from-set-description.rst

@@ -0,0 +1,3 @@
+You can delete a :cpp-sdk:`set element 
+<structrealm_1_1managed_3_01std_1_1set_3_01T_01_5_01_4_01_4.html>` 
+with ``erase()``, or remove all elements from a set with ``clear()``.

source/includes/api-details/cpp/crud/delete-single-object-description.rst

@@ -0,0 +1,3 @@
+To delete an object from the database, pass the object to the
+:cpp-sdk:`db.remove() function <structrealm_1_1db.html>`
+inside of a write transaction.

source/includes/api-details/csharp/crud/delete-all-objects-in-the-database-description.rst

@@ -0,0 +1,2 @@
+To delete all managed objects in the database, call :dotnet-sdk:`Realm.RemoveAll
+<reference/Realms.Realm.html#Realms_Realm_RemoveAll>`.

source/includes/api-details/csharp/crud/delete-all-objects-of-type-description.rst

@@ -0,0 +1,2 @@
+To delete all objects of a type, call :dotnet-sdk:`Realm.RemoveAll<T> 
+<reference/Realms.Realm.html#Realms_Realm_RemoveAll__1>`.

source/includes/api-details/csharp/crud/delete-an-object-and-its-related-objects-description.rst

@@ -0,0 +1,6 @@
+In the following example, we call :dotnet-sdk:`Realm.RemoveRange<T> 
+<reference/Realms.Realm.html#Realms_Realm_RemoveRange__1_System_Linq_IQueryable___0__>`
+to remove Ali's ``dogs`` collection, which is a to-many list property 
+containing one or more ``Dog`` objects. Then, we call :dotnet-sdk:`Realm.Remove()
+<reference/Realms.Realm.html#Realms_Realm_Remove_Realms_IRealmObjectBase_>` to
+delete Ali's ``Person`` object itself.

source/includes/api-details/csharp/crud/delete-mixed-property-values-description.rst

@@ -0,0 +1 @@
+To delete the value of a mixed property, set its value to ``Null``.

source/includes/api-details/csharp/crud/delete-multiple-objects-description.rst

@@ -0,0 +1,3 @@
+To delete multiple objects at the same time, pass an ``IQueryable<T>`` query
+for the objects you want to delete to :dotnet-sdk:`Realm.RemoveRange<T> 
+<reference/Realms.Realm.html#Realms_Realm_RemoveRange__1_System_Linq_IQueryable___0__>`.

source/includes/api-details/csharp/crud/delete-objects-procedure.rst

@@ -0,0 +1,35 @@
+1. Open a write transaction with :dotnet-sdk:`Realm.Write
+   <reference/Realms.Realm.html#Realms_Realm_Write_System_Action_>` or
+   :dotnet-sdk:`Realm.WriteAsync
+   <reference/Realms.Realm.html#Realms_Realm_WriteAsync_System_Action_System_Threading_CancellationToken_>`.
+
+#. Pass the object(s) you want to delete into the write block, or query for
+   them inside the block.
+
+   .. important:: Objects Must Be Live
+
+      You can only delete live objects. If you are working with a frozen
+      object or thread-safe reference, you must query for the live object or
+      resolve the thread-safe reference before deleting the object. For more
+      details, refer to :ref:`sdks-threading`.
+
+#. Call the :dotnet-sdk:`Remove
+   <reference/Realms.Realm.html#Realms_Realm_Remove_Realms_IRealmObjectBase_>`
+   method with the object you want to delete as an argument.
+
+#. The specified objects are deleted from the database and can no longer be
+   accessed or modified. If you try to use a deleted object, the SDK throws an
+   error.
+
+   If any deleted objects had a relationship with another object, the SDK
+   only deletes the reference to the other object. The referenced object
+   remains in the database, but it can no longer be queried through the deleted 
+   parent property. Refer to the :ref:`sdks-delete-related-objects` section
+   for more information.
+
+.. tip:: 
+
+   You can check whether an object is still valid to use by calling 
+   :dotnet-sdk:`isValid
+   <reference/Realms.RealmObjectBase.html#Realms_RealmObjectBase_IsValid>`.
+   Deleted objects return ``false``.

source/includes/api-details/csharp/crud/delete-operations-description.rst

@@ -0,0 +1,10 @@
+You can only delete live objects. If you are working with a frozen object,
+such as when passing an object across threads, you must query for the frozen
+object on the new thread in order to delete it.
+
+Similarly, if you're passing a :dotnet-sdk:`ThreadSafeReference
+<reference/Realms.ThreadSafeReference.html>` for an object you want to delete,
+you must resolve the reference and then delete the resovled object.
+
+For more information about working with objects across threads, refer to
+:ref:`sdks-threading`.

source/includes/api-details/csharp/crud/delete-remove-dictionary-keys-values-description.rst

@@ -0,0 +1 @@
+You can remove dictionary keys and values within a write transaction.

source/includes/api-details/csharp/crud/delete-remove-elements-from-list-description.rst

@@ -0,0 +1,16 @@
+You can remove one or more elements from a list within a write transaction.
+
+Deleting an object from the database will remove it from any lists 
+where it existed. Therefore, a list of objects will never contain deleted objects.
+However, lists of primitive types can contain null values. If you do not 
+want to allow null values in a list, then either use non-nullable types in 
+the list declaration (for example, use ``IList<double>`` instead of 
+``IList<double?>``). If you are using the older schema 
+type definition (your classes derive from the ``RealmObject`` base class),
+or you do not have nullability enabled, use the ``[Required]`` attribute if
+the list contains nullable reference types, such as ``string`` or ``byte[]``.
+
+.. important:: Not Supported with Sync
+
+   Non-synced databases support collections of nullable (optional) values, 
+   but synced databases do not.

source/includes/api-details/csharp/crud/delete-remove-elements-from-set-description.rst

@@ -0,0 +1,17 @@
+You can remove one or more elements from a set within a write transaction.
+
+Deleting an object from the database will remove it from any sets 
+in which it existed. Therefore, a set of objects will never contain null objects.
+However, sets of primitive types can contain null values. If you do not 
+want to allow null values in a set, then either use non-nullable types in 
+the set declaration (for example, use ``ISet<double>`` instead of 
+``ISet<double?>``). If you are using the older schema 
+type definition (your classes derive from the ``RealmObject`` base class),
+or you do not have nullability enabled, you will need to use the
+``[Required]`` attribute if the set contains nullable reference types, such as
+``string`` or ``byte[]``. 
+
+.. important:: Not Supported with Sync
+
+   Non-synced databases support collections of nullable (optional) values, 
+   but synced databases do not.

source/includes/api-details/csharp/crud/delete-single-object-description.rst

@@ -0,0 +1,4 @@
+To delete an object from the database, pass the object to
+:dotnet-sdk:`Realm.Remove()
+<reference/Realms.Realm.html#Realms_Realm_Remove_Realms_IRealmObjectBase_>`
+inside of a write transaction.

source/includes/api-details/dart/crud/delete-all-objects-in-the-database-not-supported.rst

@@ -0,0 +1,6 @@
+Dart does not provide an API to delete all objects in the database. Instead,
+you can iterate through the object types that the database manages and
+delete all objects of each type.
+
+For more information, refer to the Delete All Objects of a Type section on
+this page.

source/includes/api-details/dart/crud/delete-all-objects-of-type-description.rst

@@ -0,0 +1,2 @@
+Delete all objects of a type in the database with :flutter-sdk:`Realm.deleteAll() <realm/Realm/deleteAll.html>`
+in a write transaction block.

source/includes/api-details/dart/crud/delete-mixed-property-values-description.rst

@@ -0,0 +1 @@
+To delete the value of a mixed property, call ``RealmValue.nullValue()``.

source/includes/api-details/dart/crud/delete-multiple-objects-description.rst

@@ -0,0 +1,2 @@
+Delete multiple objects from the database by calling :flutter-sdk:`Realm.deleteMany()
+<realm/Realm/deleteMany.html>` in a write transaction block.

source/includes/api-details/dart/crud/delete-objects-procedure.rst

@@ -0,0 +1,30 @@
+1. Open a write transaction with :flutter-sdk:`realm.write
+   <realm/Realm/write.html>` or :flutter-sdk:`realm.writeAsync
+   <realm/Realm/writeAsync.html>`.
+
+#. Pass the object(s) you want to delete into the write block, or query for
+   them inside the block.
+
+   .. important:: Objects Must Be Live
+
+      You can only delete live objects. If you are working with a frozen
+      object, you must query for the live object before deleting the object.
+
+#. Call the :flutter-sdk:`delete <realm/Realm/delete.html>`
+   method with the object you want to delete as an argument.
+
+#. The specified object is deleted from the database and can no longer be
+   accessed or modified. If you try to use a deleted object, the SDK throws an
+   error.
+
+   If any deleted objects had a relationship with another object, the SDK
+   only deletes the reference to the other object. The referenced object
+   remains in the database, but it can no longer be queried through the deleted 
+   parent property. Refer to the :ref:`sdks-delete-related-objects` section
+   for more information.
+
+.. tip:: 
+
+   You can check whether an object is still valid to use by checking the
+   object's :flutter-sdk:`isValid <realm/RealmObjectBase/isValid.html>`
+   property. Deleted objects return ``false``.

source/includes/api-details/dart/crud/delete-operations-description.rst

@@ -0,0 +1,3 @@
+You can only delete live objects. If you are working with a frozen object,
+such as when passing an object across isolates, you must query for the frozen
+object in order to delete it.

source/includes/api-details/dart/crud/delete-remove-dictionary-keys-values-description.rst

@@ -0,0 +1,4 @@
+You can remove keys and values from a :flutter-sdk:`RealmMap
+<realm/RealmMap-class.html>` within a write transaction. To remove a key and
+its associated value, call ``map.remove()``. To remove an element matching
+a query, call ``map.removeWhere()``.

source/includes/api-details/dart/crud/delete-remove-elements-from-list-description.rst

@@ -0,0 +1,10 @@
+You can remove one or more elements from a :flutter-sdk:`RealmList
+<realm/RealmList-class.html>` within a write transaction:
+
+- 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 contiguous elements from the list, pass the range to
+  ``list.removeRange()``.
+- To remove the last element from the list, call ``list.removeLast()``.
+- To remove specific elements from a list that match a query, call ``list.removeWhere()``.

source/includes/api-details/dart/crud/delete-remove-elements-from-set-description.rst

@@ -0,0 +1,6 @@
+You can remove one or more elements from a :flutter-sdk:`RealmSet
+<realm/RealmSet-class.html>` within a write transaction:
+
+- To remove one element from the set, pass the element to ``set.remove()``.
+- To remove specific elements from a set that match a query, call ``set.removeWhere()``.
+- To remove all elements from the set, call ``set.removeAll()``.

source/includes/api-details/dart/crud/delete-single-object-description.rst

@@ -0,0 +1,2 @@
+Delete an object from the database by calling :flutter-sdk:`Realm.delete()
+<realm/Realm/delete.html>` in a write transaction block.

source/includes/api-details/java/crud/delete-all-objects-in-the-database-description.rst

@@ -0,0 +1,3 @@
+The following example demonstrates how to delete everything
+from the database with :java-sdk:`deleteAll()
+<io/realm/Realm.html#deleteAll-->`.

source/includes/api-details/java/crud/delete-all-objects-of-type-description.rst

@@ -0,0 +1,3 @@
+The following example demonstrates how to delete all
+Turtle instances from the database with :java-sdk:`delete()
+<io/realm/Realm.html#delete-java.lang.Class->`.

source/includes/api-details/java/crud/delete-an-object-and-its-related-objects-description.rst

@@ -0,0 +1,3 @@
+The following example demonstrates how to perform a
+chaining delete by first deleting all of Ali's turtles,
+then deleting Ali.

source/includes/api-details/java/crud/delete-multiple-objects-description.rst

@@ -0,0 +1,9 @@
+To delete an object from the database, use the ``deleteAllFromRealm()``
+method of the :java-sdk:`RealmResults <io/realm/RealmResults.html>`
+instance that contains the objects you would like to delete. You can
+filter the ``RealmResults`` down to a subset of objects using the
+:java-sdk:`where() <io/realm/Realm.html#where-java.lang.Class->` method.
+
+The following example demonstrates how to delete a
+collection from the database with :java-sdk:`deleteAllFromRealm()
+<io/realm/RealmResults.html#deleteAllFromRealm-->`.

source/includes/api-details/java/crud/delete-objects-procedure.rst

@@ -0,0 +1,30 @@
+1. Open a write transaction with one of the relevant APIs.
+
+#. Pass the object(s) you want to delete into the write block, or query for
+   them inside the block.
+
+   .. important:: Objects Must Be Live
+
+      You can only delete live objects. If you are working with a frozen
+      object, you query for the live version of the object on the local thread
+      before deleting the object. For more details, refer to
+      :ref:`sdks-threading`.
+
+#. Call the ``delete()`` method with the object you want to delete as an
+   argument.
+
+#. The specified objects are deleted from the database and can no longer be
+   accessed or modified. If you try to use a deleted object, the SDK throws an
+   error.
+
+   If any deleted objects had a relationship with another object, the SDK
+   only deletes the reference to the other object. The referenced object
+   remains in the database, but it can no longer be queried through the deleted 
+   parent property. Refer to the :ref:`sdks-delete-related-objects` section
+   for more information.
+
+.. tip:: 
+
+   You can check whether an object is still valid to use by calling 
+   :java-sdk:`isValid() <io/realm/RealmObject.html#isValid()>`.
+   Deleted objects return ``false``.

source/includes/api-details/java/crud/delete-operations-description.rst

@@ -0,0 +1,3 @@
+You can only delete live objects. If you are working with a frozen object,
+such as when passing an object across threads, you must query for the frozen
+object on the new thread in order to delete it.

source/includes/api-details/java/crud/delete-remove-dictionary-keys-values-description.rst

@@ -0,0 +1,2 @@
+For the available methods to remove dictionary keys and values, refer to the 
+:java-sdk:`RealmMap <io/realm/RealmMap.html>` API reference.

source/includes/api-details/java/crud/delete-remove-elements-from-list-description.rst

@@ -0,0 +1,2 @@
+For the available methods to remove elements from a list, refer to the 
+:java-sdk:`RealmList <io/realm/RealmList.html>` API reference.

source/includes/api-details/java/crud/delete-remove-elements-from-set-description.rst

@@ -0,0 +1,2 @@
+For the available methods to remove elements from a set, refer to the 
+:java-sdk:`RealmSet <io/realm/RealmSet.html>` API reference.

source/includes/api-details/java/crud/delete-single-object-description.rst

@@ -0,0 +1,7 @@
+To delete an object from the database, use either the dynamic or static
+versions of the ``deleteFromRealm()`` method of a :java-sdk:`RealmObject
+<io/realm/RealmObject.html>` subclass.
+
+The following example shows how to delete one object from
+its realm with :java-sdk:`deleteFromRealm()
+<io/realm/RealmObject.html#deleteFromRealm-->`.

source/includes/api-details/javascript/crud/delete-all-objects-in-the-database-js-ts-description.rst

@@ -0,0 +1,3 @@
+To delete **all** objects from the database, call :js-sdk:`Realm.deleteAll()
+<classes/Realm-1.html#deleteAll>` inside of a write transaction. This clears
+the database of all object instances but does not affect the database schema.

source/includes/api-details/javascript/crud/delete-all-objects-of-type-js-ts-description.rst

@@ -0,0 +1,3 @@
+To delete all objects of a given object type from the database, pass
+``Realm.objects(<ObjectType>)`` to the :js-sdk:`Realm.delete()
+<classes/Realm-1.html#delete>` method inside of a write transaction.

source/includes/api-details/javascript/crud/delete-mixed-property-values-js-ts-description.rst

@@ -0,0 +1 @@
+To delete the value of a ``Mixed`` property, set it to ``null``.

source/includes/api-details/javascript/crud/delete-multiple-objects-js-ts-description.rst

@@ -0,0 +1,3 @@
+To delete a collection of objects from the database, pass the collection to
+:js-sdk:`Realm.delete() <classes/Realm-1.html#delete>` inside of a write 
+transaction.

source/includes/api-details/javascript/crud/delete-objects-js-ts-procedure.rst

@@ -0,0 +1,24 @@
+1. Open a write transaction with :js-sdk:`realm.write 
+   <classes/Realm-1.html#write>`.
+
+#. Pass the object(s) you want to delete into the write block, or query for
+   them inside the block.
+
+#. Call the :js-sdk:`delete <classes/Realm-1.html#delete>`
+   method with the object you want to delete as an argument.
+
+#. The specified object is deleted from the database and can no longer be
+   accessed or modified. If you try to use a deleted object, the SDK throws an
+   error.
+
+   If any deleted objects had a relationship with another object, the SDK
+   only deletes the reference to the other object. The referenced object
+   remains in the database, but it can no longer be queried through the deleted 
+   parent property. Refer to the :ref:`sdks-delete-related-objects` section
+   for more information.
+
+.. tip:: 
+
+   You can check whether an object is still valid to use by calling
+   :js-sdk:`isValid <classes/Realm.Object.html#isValid>`
+   on the object. Deleted objects return ``false``.

source/includes/api-details/javascript/crud/delete-remove-dictionary-keys-values-js-ts-description.rst

@@ -0,0 +1,2 @@
+To delete members of a dictionary, use the ``dictionary.remove()`` method with
+an array of properties to remove from the dictionary.

source/includes/api-details/javascript/crud/delete-remove-elements-from-list-js-ts-description.rst

@@ -0,0 +1,3 @@
+You can remove one or more elements from a :js-sdk:`List <classes/List.html>`
+within a write transaction. Call :js-sdk:`list.remove()
+<classes/List.html#remove>` with the index of the element you want to remove.

source/includes/api-details/javascript/crud/delete-remove-elements-from-set-description.rst

@@ -0,0 +1,8 @@
+To remove a specific value from a set, pass the value to the
+``<Realm.Set>.delete()`` method within a write transaction.
+
+.. literalinclude:: /examples/generated/node/data-types.snippet.remove-specific-item-from-set.js
+   :language: javascript
+
+To remove all items from the set, run the ``<Realm.Set>.clear()`` method within
+a write transaction.

source/includes/api-details/javascript/crud/delete-single-object-js-ts-description.rst

@@ -0,0 +1,2 @@
+To delete an object from the database, pass the object to :js-sdk:`Realm.delete()
+<classes/Realm-1.html#delete>` inside of a write transaction.

source/includes/api-details/kotlin/crud/delete-all-objects-in-the-database-description.rst

@@ -0,0 +1,4 @@
+To delete *all* objects from the database at the same time, call 
+:kotlin-sdk:`mutableRealm.deleteAll()
+<io.realm.kotlin/-mutable-realm/delete-all.html>`. This deletes all objects of
+all types.

source/includes/api-details/kotlin/crud/delete-all-objects-of-type-description.rst

@@ -0,0 +1,6 @@
+To delete all objects of a specific type from the database 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 database:

source/includes/api-details/kotlin/crud/delete-an-object-and-its-related-objects-description.rst

@@ -0,0 +1,3 @@
+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: