Merge branch 'feature-consolidated-sdk-docs' into DOCSP-39514

Author: dacharyc

source/help.txt

@@ -4,16 +4,33 @@
 Get Help
 ========
 
+.. meta::
+   :description: Get help for Atlas Device SDK through community forums, sharing feedback, or professional support.
+   :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK
+
+.. facet::
+  :name: genre
+  :values: reference
+
+.. facet::
+   :name: programming_language
+   :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift
+
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
-Overview
---------
+.. tabs-selector:: drivers
+
+MongoDB provides various resources for getting help with Atlas Device SDK and
+Atlas App Services.
+
+.. tip:: Atlas Device SDK and Realm
 
-MongoDB provides various resources for getting help with Atlas App Services.
+   While the SDK has been renamed to Atlas Device SDK, some resources still
+   reflect ``Realm`` naming.
 
 Professional Support
 --------------------
@@ -35,9 +52,9 @@ Community Forums
 The official `MongoDB Community Forums
 <https://www.mongodb.com/community/forums/c/realm/9>`__ are a great
 place to meet other developers, ask and answer questions, and stay
-up-to-date with the latest Realm and App Services features and releases. You can also
-interact with MongoDB employees, like our community team, engineers, and
-product managers, who are active forum contributors.
+up-to-date with the latest Atlas Device SDK and App Services features and
+releases. You can also interact with MongoDB employees, like our community
+team, engineers, and product managers, who are active forum contributors.
 
 Stack Overflow
 --------------
@@ -68,62 +85,56 @@ at the bottom right or right side of the page.
 Bug Reporting, and Changelogs
 -----------------------------
 
-.. tabs-realm-sdks::
+You can report bugs or view the changelog in the relevant ``realm-SDK``
+repository in GitHub. While the SDK has been renamed to Atlas Device SDK, the
+GitHub repositories still reflect ``realm`` naming.
 
-   .. tab::
-      :tabid: android
-
-      For the Java SDK:
-
-      - :github:`Report a bug <realm/realm-java/issues/new?template=bug_report.md>`
-      - :github:`View the changelog <realm/realm-java/blob/master/CHANGELOG.md>`
+.. tabs-drivers::
 
    .. tab::
-      :tabid: ios
+      :tabid: cpp-sdk
 
-      For the Swift SDK:
-
-      - :github:`Report a bug <realm/realm-swift/issues/new>`
-      - :github:`View the changelog <realm/realm-swift/blob/master/CHANGELOG.md>`
+      - :github:`Report a bug <realm/realm-cpp/issues/new>`
+      - :github:`View the changelog <realm/realm-cpp/blob/master/CHANGELOG.md>`
 
    .. tab::
-      :tabid: dotnet
-
-      For the .NET SDK:
+      :tabid: csharp
 
       - :github:`Report a bug <realm/realm-dotnet/issues/new>`
       - :github:`View the changelog <realm/realm-dotnet/blob/master/CHANGELOG.md>`
+      
+   .. tab::
+      :tabid: dart
+
+      - :github:`Report a bug <realm/realm-dart/issues/new>`
+      - :github:`View the changelog <realm/realm-dart/blob/master/CHANGELOG.md>`
 
    .. tab::
       :tabid: javascript
 
-      For the Node.js, React Native, or Web SDKs:
-
       - :github:`Report a bug <realm/realm-js/issues/new>`
       - :github:`View the changelog <realm/realm-js/blob/master/CHANGELOG.md>`
 
-   .. tab::
-      :tabid: flutter
-
-      For the Flutter SDK:
-
-      - :github:`Report a bug <realm/realm-dart/issues/new>`
-      - :github:`View the changelog <realm/realm-dart/blob/master/CHANGELOG.md>`
-
    .. tab::
       :tabid: kotlin
 
-      For the Kotlin SDK:
-
       - :github:`Report a bug <realm/realm-kotlin/issues/new>`
       - :github:`View the changelog <realm/realm-kotlin/blob/master/CHANGELOG.md>`
 
    .. tab::
-      :tabid: cpp
+      :tabid: objectivec
 
-      For the C++ SDK:
+      - :github:`Report a bug <realm/realm-swift/issues/new>`
+      - :github:`View the changelog <realm/realm-swift/blob/master/CHANGELOG.md>`
 
-      - :github:`Report a bug <realm/realm-cpp/issues/new>`
-      - :github:`View the changelog <realm/realm-cpp/blob/master/CHANGELOG.md>`
+   .. tab::
+      :tabid: swift
+
+      - :github:`Report a bug <realm/realm-swift/issues/new>`
+      - :github:`View the changelog <realm/realm-swift/blob/master/CHANGELOG.md>`
 
-   
+   .. tab::
+      :tabid: typescript
+
+      - :github:`Report a bug <realm/realm-js/issues/new>`
+      - :github:`View the changelog <realm/realm-js/blob/master/CHANGELOG.md>`

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/cpp/users/custom-user-data-create-custom-user-data-description.rst

@@ -0,0 +1,12 @@
+In this example, we use an Atlas Function to create the custom user data. The
+Function takes an object passed by the client add adds it to the custom user
+data collection in Atlas. The Function creates the custom user data if it
+doesn't already exist and replaces all data in it if it does exist.
+
+.. literalinclude:: /examples/generated/cpp/updateCustomUserData.snippet.update-custom-user-data.js
+   :language: js
+   :caption: updateCustomUserData.js - Atlas Function running on server (JavaScript)
+
+The following example :ref:`calls a function <sdks-call-function>` to 
+insert a document containing the user ID of the currently logged in user 
+and a ``favoriteColor`` value into the custom user data collection.

source/includes/api-details/cpp/users/custom-user-data-delete-custom-user-data-description.rst

@@ -0,0 +1,11 @@
+In this example, we use an Atlas Function to delete the custom user data
+document. The Atlas Function does not require any arguments. The 
+Function uses the Function context to determine the caller's user ID, and 
+deletes the custom user data document matching the user's ID.
+
+.. literalinclude:: /examples/generated/cpp/deleteCustomUserData.snippet.delete-custom-user-data.js
+   :language: js
+   :caption: deleteCustomUserData.js - Atlas Function running on server (JavaScript)
+
+The code that calls this Function requires only a logged-in user to call
+the Function.

source/includes/api-details/cpp/users/custom-user-data-read-custom-user-data-2-description.rst

@@ -0,0 +1,6 @@
+.. note::
+
+   If you require the most recent version of custom user data, use the
+   :cpp-sdk:`refresh_custom_user_data()
+   <structrealm_1_1user.html#a6e08623890de4003a00a351e939a0a9f>`
+   function to request the latest version of a user's custom data.

source/includes/api-details/cpp/users/custom-user-data-read-custom-user-data-description.rst

@@ -0,0 +1,2 @@
+To read the data, access the ``custom_data`` property on the ``User`` object
+of a logged-in user.

source/includes/api-details/cpp/users/custom-user-data-update-custom-user-data-description.rst

@@ -0,0 +1,5 @@
+To update a user's custom user data with an Atlas Function, edit the
+MongoDB document whose user ID field contains the user ID of the user.
+The following example calls the same function used to create the custom user 
+data document above. Here, we update the ``favoriteColor`` field of the 
+the document containing the user ID of the currently logged in user.

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/csharp/users/custom-user-data-create-custom-user-data-description.rst

@@ -0,0 +1,12 @@
+The following example uses
+:ref:`MongoDB Data Access <sdks-access-mongodb>` to insert a
+document containing the user ID of the currently logged in user and several 
+custom properties into the custom user data collection:
+
+.. literalinclude:: /examples/generated/dotnet/CustomUserDataExamples.snippet.create.cs
+   :language: csharp
+
+You may find it helpful to create a C# class (POCO) that represents the custom 
+user data object. The SDK will serialize/deserialize this class to and from BSON 
+when writing, reading, and updating properties. The example above uses the 
+following class to map the properties.

source/includes/api-details/csharp/users/custom-user-data-delete-custom-user-data-description.rst

@@ -0,0 +1,4 @@
+The following example uses :ref:`MongoDB Data Access <sdks-access-mongodb>` to
+find and deletes the data through the 
+:dotnet-sdk:`DeleteOneAsync() <reference/Realms.Sync.MongoClient.Collection-1.html#Realms_Sync_MongoClient_Collection_1_DeleteOneAsync_System_Object_>` 
+method.

source/includes/api-details/csharp/users/custom-user-data-read-custom-user-data-2-description.rst

@@ -0,0 +1,6 @@
+.. note::
+
+   If you require the most recent version of custom user data, call the
+   :dotnet-sdk:`RefreshCustomDataAsync()
+   <reference/Realms.Sync.User.html#Realms_Sync_User_RefreshCustomDataAsync>` 
+   method to request the latest version of a user's custom data.

source/includes/api-details/csharp/users/custom-user-data-read-custom-user-data-description.rst

@@ -0,0 +1,3 @@
+To read custom user data, call the 
+:dotnet-sdk:`GetCustomData() <reference/Realms.Sync.User.html#Realms_Sync_User_GetCustomData>`
+method on the ``User`` object of a logged in user.

source/includes/api-details/csharp/users/custom-user-data-update-custom-user-data-description.rst

@@ -0,0 +1,4 @@
+The following example 
+finds and updates the data by using the 
+:dotnet-sdk:`UpdateOneAsync() <reference/Realms.Sync.MongoClient.Collection-1.html#Realms_Sync_MongoClient_Collection_1_UpdateOneAsync_System_Object_System_Object_System_Boolean_>` 
+method, and then refreshes the data to ensure the latest changes are available.

source/includes/api-details/csharp/users/link-user-identities-example-description.rst

@@ -0,0 +1,13 @@
+You can link identities using the 
+:dotnet-sdk:`LinkCredentialsAsync() <reference/Realms.Sync.User.html#Realms_Sync_User_LinkCredentialsAsync_Realms_Sync_Credentials_>`. 
+This links the identity belonging to the credentials to the logged-in 
+:dotnet-sdk:`User <reference/Realms.Sync.User.html>` object. 
+
+.. literalinclude:: /examples/generated/dotnet/UserLinkExamples.snippet.link.cs
+   :language: csharp
+
+In the example above, we must first register the new :ref:`email/password
+<email-password-authentication>` user before linking. If you are using any of
+the other :ref:`Auth Providers <authentication-providers>`, this step is
+unnecessary. The following example uses :ref:`Google authentication
+<google-authentication>` instead of EmailPassword.