(DOCSP-39539): Consolidate Stream Data to Atlas page (#3268)

dacharyc · lindseymoore · MongoCaleb · web-flow · commit a0659fc2accd · 2024-05-24T17:37:43.000-04:00
## Pull Request Info - SDK Docs Consolidation Jira ticket: https://jira.mongodb.org/browse/DOCSP-39539 *Staged Page* - [Stream Data to Atlas](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39539/sdk/sync/stream-data-to-atlas/): Draft consolidated page *Page Source* - [C++: Stream Data to Atlas](https://www.mongodb.com/docs/atlas/device-sdks/sdk/cpp/sync/stream-data-to-atlas/) - [Flutter: Stream Data to Atlas](https://www.mongodb.com/docs/atlas/device-sdks/sdk/flutter/sync/stream-data-to-atlas/) - [Kotlin: Stream Data to Atlas](https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/sync/stream-data-to-atlas/) - [.NET: Stream Data to Atlas](https://www.mongodb.com/docs/atlas/device-sdks/sdk/dotnet/sync/asymmetric-sync/) - [Node.js: Stream Data to Atlas](https://www.mongodb.com/docs/atlas/device-sdks/sdk/node/sync/stream-data-to-atlas/) - [Swift: Stream Data to Atlas](https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/sync/stream-data-to-atlas/) ### PR Author Checklist Before requesting a review for your PR, please check these items: - [x] Open the PR against the `feature-consolidated-sdk-docs` branch instead of `master` - [x] Tag the consolidated page for: - genre - meta.keywords - meta.description #### Naming - [x] Update Realm naming and the language around persistence layer/local/device per [this document](https://docs.google.com/document/d/126OczVxBWAwZ4P5ZsSM29WI3REvONEr1ald-mAwPtyQ/edit?usp=sharing) - [x] Include `.rst` files comply with [the naming guidelines](https://docs.google.com/document/d/1h8cr66zoEVeXytVfvDxlCSsUS5IZwvUQvfSCEXNMpek/edit#heading=h.ulh8b5f2hu9) #### Links and Refs - [x] Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections - [x] Remove or update any SDK-specific refs to use the new consolidated SDK ref targets - [x] [Update any Kotlin API links](https://jira.mongodb.org/browse/DOCSP-32519) to use the new Kotlin SDK roles #### Content - [x] Shared code boxes have snippets or placeholders for all 9 languages - [x] API description sections have API details or a generic placeholder for all 9 languages - [x] Check related pages for relevant content to include - [x] Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic ### Reviewer Checklist As a reviewer, please check these items: - [ ] Shared code example boxes contain language-specific snippets or placeholders for every language - [ ] API reference details contain working API reference links or generic content - [ ] Realm naming/language has been updated - [ ] All relevant content from individual SDK pages is present on the consolidated page --------- Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Co-authored-by: MongoCaleb <caleb.thompson@mongodb.com> Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com>
diff --git a/examples/dotnet/Examples/Asymmetrics.cs b/examples/dotnet/Examples/Asymmetrics.cs
@@ -11,25 +11,26 @@ namespace Examples
 {
     public partial class Asymmetrics
     {
-        App app;
-        Realms.Sync.User user;
         Realm realm;
-        const string myRealmAppId = Config.FSAppId;
+        const string myAppId = Config.FSAppId;
 
         [OneTimeSetUp]
         public void Setup()
         {
-            app = App.Create(myRealmAppId);
-            user = app.LogInAsync(
+            // :snippet-start: connect-and-authenticate
+            App app = App.Create(myAppId);
+            Realms.Sync.User user = app.LogInAsync(
                 Credentials.Anonymous()).Result;
-
+            // :snippet-end:
+            
+            // :snippet-start: configure-and-open-db
             var config = new FlexibleSyncConfiguration(user)
             {
                 Schema = new[] { typeof(Measurement) }
             };
 
-
             realm = Realm.GetInstance(config);
+            // :snippet-end:
 
             // You cannot add a subscription for an AsymmetricObject
             // This causes a compile-time error:
@@ -40,22 +41,18 @@ public void Setup()
             //});
             // :uncomment-end:
         }
-
-        // :snippet-start: asymmetry
-        // :remove-start:
         [Realms.Explicit]
-        // :remove-end:
+        // :snippet-start: define-asymmetric-object
         private partial class Measurement : IAsymmetricObject
         {
             [PrimaryKey, MapTo("_id")]
             public Guid Id { get; private set; } = Guid.NewGuid();
             public double Value { get; set; }
             public DateTimeOffset Timestamp { get; private set; } = DateTimeOffset.UtcNow;
         }
-
-        // :remove-start:
+        // :snippet-end:
         [Test]
-        // :remove-end:
+        // :snippet-start: asymmetry
         public void SendMeasurementToRealm()
         {
             var measurement = new Measurement
diff --git a/source/examples/generated/dotnet/Asymmetrics.snippet.asymmetry.cs b/source/examples/generated/dotnet/Asymmetrics.snippet.asymmetry.cs
@@ -1,11 +1,3 @@
-private partial class Measurement : IAsymmetricObject
-{
-    [PrimaryKey, MapTo("_id")]
-    public Guid Id { get; private set; } = Guid.NewGuid();
-    public double Value { get; set; }
-    public DateTimeOffset Timestamp { get; private set; } = DateTimeOffset.UtcNow;
-}
-
 public void SendMeasurementToRealm()
 {
     var measurement = new Measurement
diff --git a/source/examples/generated/dotnet/Asymmetrics.snippet.configure-and-open-db.cs b/source/examples/generated/dotnet/Asymmetrics.snippet.configure-and-open-db.cs
@@ -0,0 +1,6 @@
+var config = new FlexibleSyncConfiguration(user)
+{
+    Schema = new[] { typeof(Measurement) }
+};
+
+realm = Realm.GetInstance(config);
diff --git a/source/examples/generated/dotnet/Asymmetrics.snippet.connect-and-authenticate.cs b/source/examples/generated/dotnet/Asymmetrics.snippet.connect-and-authenticate.cs
@@ -0,0 +1,3 @@
+App app = App.Create(myAppId);
+Realms.Sync.User user = app.LogInAsync(
+    Credentials.Anonymous()).Result;
diff --git a/source/examples/generated/dotnet/Asymmetrics.snippet.define-asymmetric-object.cs b/source/examples/generated/dotnet/Asymmetrics.snippet.define-asymmetric-object.cs
@@ -0,0 +1,7 @@
+private partial class Measurement : IAsymmetricObject
+{
+    [PrimaryKey, MapTo("_id")]
+    public Guid Id { get; private set; } = Guid.NewGuid();
+    public double Value { get; set; }
+    public DateTimeOffset Timestamp { get; private set; } = DateTimeOffset.UtcNow;
+}
diff --git a/source/includes/api-details/cpp/sync/stream-data-create-asymmetric-objects-description.rst b/source/includes/api-details/cpp/sync/stream-data-create-asymmetric-objects-description.rst
@@ -0,0 +1,2 @@
+Once you have an open database, you can create an ``asymmetric_object`` 
+and set its values as you would a regular object.
diff --git a/source/includes/api-details/cpp/sync/stream-data-define-asymmetric-object-description.rst b/source/includes/api-details/cpp/sync/stream-data-define-asymmetric-object-description.rst
@@ -0,0 +1,6 @@
+You can sync data unidirectionally when you declare an object's 
+schema as a ``REALM_ASYMMETRIC_SCHEMA``.
+
+For more information on how to define a ``REALM_ASYMMETRIC_SCHEMA``, 
+including limitations when linking to other object types, refer to
+:ref:`Define an Asymmetric Object <sdks-asymmetric-objects>`.
diff --git a/source/includes/api-details/cpp/sync/stream-data-open-database-description.rst b/source/includes/api-details/cpp/sync/stream-data-open-database-description.rst
@@ -0,0 +1,9 @@
+Unlike opening a database for non-asymmetric object types, when you open a
+database for Data Ingest, you *must* specify the ``asymmetric_object`` types
+you want to sync.
+
+.. tip:: Mixed Object and Asymmetric Object Types
+
+   You cannot open a single synced database to manage both regular objects
+   and asymmetric objects. You must use different databases to manage these
+   different object types.
diff --git a/source/includes/api-details/csharp/sync/stream-data-create-asymmetric-objects-description.rst b/source/includes/api-details/csharp/sync/stream-data-create-asymmetric-objects-description.rst
@@ -0,0 +1,4 @@
+The process for writing asymmetric objects is the same as standard
+bi-directional Sync. The following code shows creating an asymmetric object 
+and syncing it with the backend. It also shows to queries that generate
+errors.
diff --git a/source/includes/api-details/csharp/sync/stream-data-define-asymmetric-object-description.rst b/source/includes/api-details/csharp/sync/stream-data-define-asymmetric-object-description.rst
@@ -0,0 +1,7 @@
+To define an asymmetric object, your objects must implement the 
+:dotnet-sdk:`IAsymmetricObject <reference/Realms.IAsymmetricObject.html>`
+interface or derive from the 
+:dotnet-sdk:`AsymmetricObject <reference/Realms.AsymmetricObject.html>` class.
+
+For more information on how to define an asymmetric object, refer to 
+:ref:`sdks-asymmetric-objects`.
diff --git a/source/includes/api-details/dart/sync/stream-data-create-asymmetric-objects-description.rst b/source/includes/api-details/dart/sync/stream-data-create-asymmetric-objects-description.rst
@@ -0,0 +1,2 @@
+Once you have an open database, you can create an asymmetric object inside
+a write transaction. Pass your object data to ``realm.ingest``.
diff --git a/source/includes/api-details/dart/sync/stream-data-define-asymmetric-object-description.rst b/source/includes/api-details/dart/sync/stream-data-define-asymmetric-object-description.rst
@@ -0,0 +1,5 @@
+To define an asymmetric object, pass ``ObjectType.asymmetricObject`` to
+``@RealmModel()``.
+
+For more information on how to define an asymmetric object, refer to 
+:ref:`sdks-asymmetric-objects`.
diff --git a/source/includes/api-details/generic/sync/stream-data-create-asymmetric-objects-js-ts-description.rst b/source/includes/api-details/generic/sync/stream-data-create-asymmetric-objects-js-ts-description.rst
@@ -0,0 +1,4 @@
+Once you have an open database, you can create an asymmetric object inside
+a write transaction using :js-sdk:`Realm.create() <classes/Realm-1.html#create>`.
+When creating an asymmetric object, ``Realm.create()`` returns
+``undefined`` rather than the object itself.
diff --git a/source/includes/api-details/generic/sync/stream-data-define-asymmetric-object-js-ts-description.rst b/source/includes/api-details/generic/sync/stream-data-define-asymmetric-object-js-ts-description.rst
@@ -0,0 +1,7 @@
+Asymmetric objects sync data unidirectionally. Define an asymmetric object
+by setting ``asymmetric`` to ``true`` in your object schema. For more
+information, refer to the :js-sdk:`BaseObjectSchema API reference
+<types/BaseObjectSchema.html>`.
+
+For more information on how to define an asymmetric object, refer to 
+:ref:`Define an Asymmetric Object <sdks-asymmetric-objects>`.
diff --git a/source/includes/api-details/kotlin/sync/stream-data-create-asymmetric-objects-description.rst b/source/includes/api-details/kotlin/sync/stream-data-create-asymmetric-objects-description.rst
@@ -0,0 +1,3 @@
+Once you have an open database, you can create an ``AsymmetricRealmObject``
+inside a write transaction using the :kotlin-sync-sdk:`insert() <io.realm.kotlin.mongodb.ext/insert.html>` 
+extension method:
diff --git a/source/includes/api-details/kotlin/sync/stream-data-define-asymmetric-object-description.rst b/source/includes/api-details/kotlin/sync/stream-data-define-asymmetric-object-description.rst
@@ -0,0 +1,8 @@
+You can sync data unidirectionally when that object is an
+``AsymmetricRealmObject``.
+
+Define an asymmetric object by implementing the 
+:kotlin-sync-sdk:`AsymmetricRealmObject <io.realm.kotlin.types/-asymmetric-realm-object/index.html>`
+interface.
+
+.. include:: /includes/kotlin-asymmetric-object.rst
diff --git a/source/includes/api-details/kotlin/sync/stream-data-open-synced-database-description.rst b/source/includes/api-details/kotlin/sync/stream-data-open-synced-database-description.rst
@@ -0,0 +1,4 @@
+Specify the ``AsymmetricRealmObject`` types you want to sync.
+
+If you have non-asymmetric objects in the same database, you can add a
+Sync subscription query for only those objects.
diff --git a/source/includes/api-details/swift/sync/stream-data-create-asymmetric-objects-description.rst b/source/includes/api-details/swift/sync/stream-data-create-asymmetric-objects-description.rst
@@ -0,0 +1,3 @@
+Once you have an open database, you can create an ``AsymmetricObject`` inside
+a write transaction using :swift-sdk:`create(_ type:, value:)
+<Structs/Realm.html#/s:10RealmSwift0A0V6create_5valueyxm_yptSo0aB16AsymmetricObjectCRbzlF>`.
diff --git a/source/includes/api-details/swift/sync/stream-data-define-asymmetric-object-description.rst b/source/includes/api-details/swift/sync/stream-data-define-asymmetric-object-description.rst
@@ -0,0 +1,6 @@
+You can sync data unidirectionally when that object is an ``AsymmetricObject``.
+Define an AsymmetricObject by deriving from :swift-sdk:`AsymmetricObject 
+<Extensions/AsymmetricObject.html>`.
+
+For more information on how to define an ``AsymmetricObject``, refer to
+:ref:`Define an AsymmetricObject <sdks-asymmetric-objects>`.
diff --git a/source/includes/api-details/swift/sync/stream-data-open-synced-database-description.rst b/source/includes/api-details/swift/sync/stream-data-open-synced-database-description.rst
@@ -0,0 +1,14 @@
+Specify the ``AsymmetricObject`` types you want to sync.
+
+.. note:: Mixed Synced and Non-Synced Databases in Projects
+
+    The ``AsymmetricObject`` type is incompatible with non-synced databases.
+    If your project uses both a synced and non-synced database, you must 
+    explicitly :ref:`pass a subset of classes in your database configuration 
+    <sdks-provide-a-subset-of-classes-to-a-database>` to exclude the 
+    ``AsymmetricObject`` from your non-synced database.
+    
+    Automatic schema discovery means that opening a non-synced database
+    without specifically excluding the ``AsymmetricObject`` from the 
+    configuration can throw an error related to trying to use an 
+    incompatible object type.
diff --git a/source/includes/data-ingest-overview.rst b/source/includes/data-ingest-overview.rst
diff --git a/source/includes/dotnet-asymmetric-object.rst b/source/includes/dotnet-asymmetric-object.rst
@@ -0,0 +1,18 @@
+When defining an asymmetric object in C#:
+
+- The C# objects that you sync with Atlas must implement the 
+  :dotnet-sdk:`IAsymmetricObject <reference/Realms.IAsymmetricObject.html>`
+  interface or derive from the 
+  :dotnet-sdk:`AsymmetricObject <reference/Realms.AsymmetricObject.html>` class.
+
+- Starting in .NET SDK version 11.6.0 and later, an object that implements 
+  ``IAsymmetricObject`` can contain
+  :dotnet-sdk:`IEmbeddedObject <reference/Realms.IEmbeddedObject.html>` types, 
+  and links to ``IRealmObject`` types. In .NET SDK versions 11.5.0 and earlier, 
+  an object that implements ``IAsymmetricObject`` can only contain
+  :dotnet-sdk:`IEmbeddedObject <reference/Realms.IEmbeddedObject.html>` types - 
+  it does not support links to ``IRealmObject`` types or other 
+  ``IAsymmetricObject`` types. 
+
+- ``IRealmObject`` and ``IEmbeddedObject`` types cannot contain ``IAsymmetricObject``
+  types as properties. 
diff --git a/source/includes/kotlin-asymmetric-object.rst b/source/includes/kotlin-asymmetric-object.rst
@@ -1,17 +1,16 @@
 Asymmetric objects broadly support the same property types as ``RealmObject``, 
 with a few exceptions:
 
-- Asymmetric objects can only be used in synced realms configured with 
-  Flexible Sync. However, you cannot create subscriptions to 
-  asymmetric objects.
+- Asymmetric objects can only be used in synced databases. However, you cannot
+  create subscriptions to asymmetric objects.
 - An ``AsymmetricRealmObject`` can contain ``EmbeddedRealmObject`` 
   types, but *cannot* contain ``RealmObject`` types or other 
   ``AsymmetricRealmObject`` types.
 - ``AsymmetricRealmObject`` types *cannot* be used as properties in other 
-  Realm objects.
+  database objects.
 
-Additionally, asymmetric objects do not function in the same way as other Realm objects. 
-You cannot add, read, update, or delete an asymmetric object from the realm.
-You can only create an asymmetric object, which then syncs unidirectionally 
-to the Atlas database linked to your App with Device Sync.
-Realm then deletes this object after syncing. 
+Additionally, asymmetric objects do not function in the same way as other
+database objects. You cannot add, read, update, or delete an asymmetric object
+from the database. You can only create an asymmetric object, which then syncs
+unidirectionally to the Atlas database linked to your App with Device Sync.
+The SDK then deletes this object after syncing.
diff --git a/source/includes/sdk-examples/sync/stream-data-connect-and-authenticate.rst b/source/includes/sdk-examples/sync/stream-data-connect-and-authenticate.rst
@@ -0,0 +1,47 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: cpp-sdk
+       content: |
+
+         .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.connect-and-authenticate.cpp
+            :language: cpp
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/Asymmetrics.snippet.connect-and-authenticate.cs
+            :language: csharp
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/app_services_test.snippet.access-app-client.dart
+            :language: dart
+
+         .. literalinclude:: /examples/generated/flutter/authenticate_users_test.snippet.anonymous-credentials.dart
+            :language: dart
+
+     - id: javascript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/authenticate.snippet.anonymous-login.js
+            :language: javascript
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.connect-and-authenticate.kt
+            :language: kotlin
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.connect-and-authenticate.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude:: /examples/generated/node/authenticate.snippet.anonymous-login.ts
+            :language: typescript
diff --git a/source/includes/sdk-examples/sync/stream-data-create-asymmetric-objects.rst b/source/includes/sdk-examples/sync/stream-data-create-asymmetric-objects.rst
@@ -0,0 +1,44 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: cpp-sdk
+       content: |
+
+         .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.create-asymmetric-object.cpp
+            :language: cpp
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/Asymmetrics.snippet.asymmetry.cs
+            :language: csharp
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart
+            :language: dart
+
+     - id: javascript
+       content: |
+
+         .. literalinclude::  /examples/MissingPlaceholders/example.js
+            :language: javascript
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt
+            :language: kotlin
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude::  /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts
+            :language: typescript
diff --git a/source/includes/sdk-examples/sync/stream-data-define-asymmetric-object.rst b/source/includes/sdk-examples/sync/stream-data-define-asymmetric-object.rst
@@ -0,0 +1,47 @@
+.. tabs-drivers::
+
+   tabs:
+     - id: cpp-sdk
+       content: |
+
+         .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.asymmetric-object.cpp
+            :language: cpp
+
+     - id: csharp
+       content: |
+
+         .. literalinclude:: /examples/generated/dotnet/Asymmetrics.snippet.define-asymmetric-object.cs
+            :language: csharp
+
+     - id: dart
+       content: |
+
+         .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.asymmetric-sync-object.dart
+            :language: dart
+            :emphasize-lines: 1
+
+     - id: javascript
+       content: |
+
+         .. literalinclude::  /examples/generated/node/asymmetric-sync.snippet.asymmetric-sync-object.js
+            :language: javascript
+            :emphasize-lines: 6
+
+     - id: kotlin
+       content: |
+
+         .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-asymmetric-model.kt 
+            :language: kotlin
+
+     - id: swift
+       content: |
+
+         .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.asymmetric-model.swift
+            :language: swift
+
+     - id: typescript
+       content: |
+
+         .. literalinclude::  /examples/generated/node/asymmetric-sync.snippet.asymmetric-sync-object.ts
+            :language: typescript
+            :emphasize-lines: 12
diff --git a/source/includes/sdk-examples/sync/stream-data-open-synced-database.rst b/source/includes/sdk-examples/sync/stream-data-open-synced-database.rst
diff --git a/source/sdk/files/configure-and-open.txt b/source/sdk/files/configure-and-open.txt
diff --git a/source/sdk/sync/stream-data-to-atlas.txt b/source/sdk/sync/stream-data-to-atlas.txt
diff --git a/temp/cpp/sync/stream-data-to-atlas.txt b/temp/cpp/sync/stream-data-to-atlas.txt
diff --git a/temp/flutter/sync/stream-data-to-atlas.txt b/temp/flutter/sync/stream-data-to-atlas.txt
diff --git a/temp/node/sync/stream-data-to-atlas.txt b/temp/node/sync/stream-data-to-atlas.txt
diff --git a/temp/swift/sync/stream-data-to-atlas.txt b/temp/swift/sync/stream-data-to-atlas.txt

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+App app = App.Create(myAppId);`
	`2`	`+Realms.Sync.User user = app.LogInAsync(`
	`3`	`+ Credentials.Anonymous()).Result;`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Once you have an open database, you can create an ``asymmetric_object``
	`2`	`+and set its values as you would a regular object.`