From fc3d1121002bac3ced69f3894c4d447e6ad85220 Mon Sep 17 00:00:00 2001 From: cbullinger Date: Wed, 29 Nov 2023 11:25:25 -0500 Subject: [PATCH] Apply Dachary feedback --- .../mongodb/realm/realmkmmapp/SchemaSync.kt | 6 +- ...ync.snippet.sync-define-embedded-object.kt | 10 +-- ...nippet.sync-define-inverse-relationship.kt | 8 +- ...nippet.sync-define-to-many-relationship.kt | 2 +- .../schemas/model-data-device-sync.txt | 84 +++++++++++-------- .../schemas/property-annotations.txt | 10 ++- source/sdk/kotlin/sync/subscribe.txt | 2 + 7 files changed, 72 insertions(+), 50 deletions(-) diff --git a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaSync.kt b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaSync.kt index 3787f08917..9e2862ae17 100644 --- a/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaSync.kt +++ b/examples/kotlin/shared/src/commonTest/kotlin/com/mongodb/realm/realmkmmapp/SchemaSync.kt @@ -14,9 +14,9 @@ import org.mongodb.kbson.ObjectId // "terms": { // "ExampleSyncObject_": "", // "ExampleSyncRelationship_": "", -// "_Inverse": "", -// "_Many": "", -// "_Embedded": "", +// "Inverse_": "", +// "Many_": "", +// "Embedded_": "", // "SyncTask": "Task" // } // } diff --git a/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-embedded-object.kt b/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-embedded-object.kt index 62e0502913..18750328ee 100644 --- a/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-embedded-object.kt +++ b/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-embedded-object.kt @@ -1,20 +1,20 @@ -class _Frog : RealmObject { +class Frog : RealmObject { @PrimaryKey var _id: ObjectId = ObjectId() var name: String = "" var age: Int? = null // Embed a single object (MUST be optional) - var favoritePond: Pond? = null + var favoritePond: EmbeddedPond? = null } -class _Forest : RealmObject { +class Forest : RealmObject { @PrimaryKey var _id: ObjectId = ObjectId() var name: String = "" // Embed multiple objects (can have many ponds) - var forestPonds: RealmList = realmListOf() + var forestPonds: RealmList = realmListOf() } -class Pond : EmbeddedRealmObject { +class EmbeddedPond : EmbeddedRealmObject { var name: String? = null } diff --git a/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-inverse-relationship.kt b/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-inverse-relationship.kt index de7ed5e714..7efaf4d609 100644 --- a/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-inverse-relationship.kt +++ b/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-inverse-relationship.kt @@ -1,15 +1,15 @@ -class _Pond : RealmObject { +class Pond : RealmObject { @PrimaryKey var _id: ObjectId = ObjectId() var name: String = "" // Backlink to the `Frog` that has this `Pond` as its favorite - val frog: RealmResults<_Frog> by backlinks(_Frog::favoritePonds) + val frog: RealmResults by backlinks(Frog::favoritePonds) } -class _Frog : RealmObject { +class Frog : RealmObject { @PrimaryKey var _id: ObjectId = ObjectId() var name: String = "" var age: Int? = null // To-many relationship (can have many ponds) - var favoritePonds: RealmList<_Pond> = realmListOf() + var favoritePonds: RealmList = realmListOf() } diff --git a/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-to-many-relationship.kt b/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-to-many-relationship.kt index 768c31e03f..32e87874c8 100644 --- a/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-to-many-relationship.kt +++ b/source/examples/generated/kotlin/SchemaSync.snippet.sync-define-to-many-relationship.kt @@ -1,4 +1,4 @@ -class _Frog : RealmObject { +class Frog : RealmObject { @PrimaryKey var _id: ObjectId = ObjectId() var name: String = "" diff --git a/source/sdk/kotlin/realm-database/schemas/model-data-device-sync.txt b/source/sdk/kotlin/realm-database/schemas/model-data-device-sync.txt index 44ee4f4d74..aef9fdae9d 100644 --- a/source/sdk/kotlin/realm-database/schemas/model-data-device-sync.txt +++ b/source/sdk/kotlin/realm-database/schemas/model-data-device-sync.txt @@ -67,17 +67,10 @@ an App Services schema, and both schemas must be consistent with each other. You can define your schema in the client app or in Atlas first, depending on your preference and use case. You can then generate a corresponding schema with matching -object models. +object models. -.. important:: Device Sync Requires an _id Primary Key Field - - To work with Atlas Device Sync, your object models *must* - have a :ref:`primary key ` field called ``_id``. - It can be of type ``String``, ``Int``, or ``ObjectId``. Device Sync - uses this to identify objects in the Atlas collections. - -Generate a Schema with Development Mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Generate a Schema from the Client App +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are developing a new client application, you likely want to iterate on the data model in the client app. After you @@ -98,8 +91,32 @@ exists in Atlas, you can generate a schema from that data, and then generate SDK object models to use in your Kotlin client app. To learn more, refer to :ref:`` in the App Services documentation. -Map Realm Objects ------------------ +Device Sync Requirements +------------------------ + +There are a few requirements to successfully sync objects. As outlined +earlier, you must have matching Realm and App Services +schemas that contain the objects that you want to sync. + +Additionally, Device Sync requires that: + +- Your object models *must* have a :ref:`primary key ` + field called ``_id``. It can be of type ``String``, ``Int``, or ``ObjectId``. + Device Sync uses this to identify objects in the Atlas collections. + + If an object does not have an ``_id`` field defined, Realm throws the + the following schema validation error: + ``There must be a primary key property named '_id' on a synchronized Realm``. + +- Each class *must* have at least one queryable field. + + When Development Mode is enabled, fields that you include in client + subscription queries are automatically added as queryable fields in Atlas. + For more information on configuring subscriptions with the Kotlin SDK, + refer to :ref:``. + +Realm Object Mapping +-------------------- Realm objects are the uniquely named instances of Kotlin classes defined in your Realm schema that determine the properties and @@ -108,22 +125,18 @@ relationships for objects of that type. App Services maps Realm objects to Atlas in the following ways: - Realm object names map to Atlas collections in your linked Device Sync - data source. - - .. tip:: Map with Development Mode + data source. Note the following: - When Development Mode is enabled, App Services automatically - creates a collection and schema for each new Realm object - type that you sync. + - When Development Mode is enabled, App Services automatically creates + a collection and schema for each new Realm object type that you sync. + - Embedded objects are *not* stored in their own collection in + Atlas. This is because they cannot exist outside of their parent object + type. Refer to the :ref:`` section on + this page for more information. - The Realm object schema maps to an App Services schema within its appropriate collection. -Note that embedded objects are *not* stored in their own collection in -Atlas. This is because they cannot exist outside of their parent object -type. Refer to the :ref:`` section on -this page for more information. - In the following example, we have ``Frog`` and ``Pond`` objects with basic properties defined in our Realm schema: @@ -132,9 +145,8 @@ objects with basic properties defined in our Realm schema: :caption: Frog and Pond Realm Objects In Atlas, we can see how these object types map to corresponding -App Services schemas in respective Frog and Pond collections as well as what -frog and pond objects that conform to the data model might look like in -those collections: +App Services schemas -- each object maps to its respective collection. +We also see example frog and pond objects that conform to this data model: .. tabs:: @@ -204,8 +216,8 @@ those collections: "name": "Kermit's Pond" } -Map Realm Relationships ------------------------ +Realm Relationship Mapping +-------------------------- Your Realm object model might include :ref:`relationships ` between objects. There are two primary types of relationships: @@ -559,8 +571,8 @@ Types `. - .. code-block:: json "stringReq": { - "bsonType": "string" - } + "bsonType": "string" + } * - ``Byte`` - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.byte-required.kt @@ -577,8 +589,8 @@ Types `. - .. code-block:: json "shortReq": { - "bsonType": "long" - } + "bsonType": "long" + } * - ``Int`` - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.int-required.kt @@ -586,8 +598,8 @@ Types `. - .. code-block:: json "intReq": { - "bsonType": "long" - } + "bsonType": "long" + } * - ``Long`` - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.long-required.kt @@ -595,8 +607,8 @@ Types `. - .. code-block:: json "longReq": { - "bsonType": "long" - } + "bsonType": "long" + } * - ``Float`` - .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.float-required.kt diff --git a/source/sdk/kotlin/realm-database/schemas/property-annotations.txt b/source/sdk/kotlin/realm-database/schemas/property-annotations.txt index 8c87017df2..8e349e4ed6 100644 --- a/source/sdk/kotlin/realm-database/schemas/property-annotations.txt +++ b/source/sdk/kotlin/realm-database/schemas/property-annotations.txt @@ -73,7 +73,15 @@ You can create a primary key with any of the following types: - ``Long`` - ``ObjectId`` - ``RealmUUID`` - + +.. important:: Device Sync Requires an _id Primary Key Field + + If you use Device Sync, your object models *must* include a primary key + field named ``_id``, which must be be of type ``String``, ``Int``, or + ``ObjectId``. + + For more information, refer to :ref:``. + .. _kotlin-remap-a-property: Map a Property or Class to a Different Name diff --git a/source/sdk/kotlin/sync/subscribe.txt b/source/sdk/kotlin/sync/subscribe.txt index 7a54c242a5..03145ef155 100644 --- a/source/sdk/kotlin/sync/subscribe.txt +++ b/source/sdk/kotlin/sync/subscribe.txt @@ -24,6 +24,8 @@ to use Device Sync and configure Flexible Sync on the backend. To do this, complete the steps outlined in the :ref:`Add Device Sync to Your App ` procedure. +.. _kotlin-subscriptions-overview: + Subscriptions Overview ----------------------