From b6de91a08714299b8010ee9b61cd8d6b86e928c6 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 10:45:13 -0400 Subject: [PATCH 01/37] Update tab IDs in PoC stub content --- .../crud/create-asymmetric-object-model.rst | 8 +++++- .../crud/create-asymmetric-object.rst | 8 +++++- .../crud/create-embedded-object-model.rst | 9 +++++- .../crud/create-embedded-object.rst | 9 +++++- .../crud/create-realm-object-model.rst | 8 +++++- .../sdk-examples/crud/create-realm-object.rst | 10 ++++++- source/sdk/crud/create.txt | 28 ++++++++++++++++--- 7 files changed, 70 insertions(+), 10 deletions(-) diff --git a/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst b/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst index f41d389e0e..b2985ee0df 100644 --- a/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst +++ b/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.asymmetric-object.cpp @@ -26,6 +26,12 @@ .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: java + - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-asymmetric-object.rst b/source/includes/sdk-examples/crud/create-asymmetric-object.rst index 332e2e4ef3..b2c49a8fb2 100644 --- a/source/includes/sdk-examples/crud/create-asymmetric-object.rst +++ b/source/includes/sdk-examples/crud/create-asymmetric-object.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.create-asymmetric-object.cpp @@ -25,6 +25,12 @@ .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: java + - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-embedded-object-model.rst b/source/includes/sdk-examples/crud/create-embedded-object-model.rst index c008b52013..487ad17016 100644 --- a/source/includes/sdk-examples/crud/create-embedded-object-model.rst +++ b/source/includes/sdk-examples/crud/create-embedded-object-model.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/crud.snippet.model-with-embedded-object.cpp @@ -26,6 +26,13 @@ :language: java :copyable: false + - id: java-kotlin + content: | + + .. literalinclude:: /examples/EmbeddedObjects/DefineEmbeddedObjects.kt + :language: kotlin + :copyable: false + - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-embedded-object.rst b/source/includes/sdk-examples/crud/create-embedded-object.rst index 50a666809a..c989b7b407 100644 --- a/source/includes/sdk-examples/crud/create-embedded-object.rst +++ b/source/includes/sdk-examples/crud/create-embedded-object.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/crud.snippet.create-embedded-object.cpp @@ -26,6 +26,13 @@ :language: java :copyable: false + - id: java-kotlin + content: | + + .. literalinclude:: /examples/EmbeddedObjects/CreateEmbeddedObject.kt + :language: kotlin + :copyable: false + - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-realm-object-model.rst b/source/includes/sdk-examples/crud/create-realm-object-model.rst index 5723d8d99f..1518ee892e 100644 --- a/source/includes/sdk-examples/crud/create-realm-object-model.rst +++ b/source/includes/sdk-examples/crud/create-realm-object-model.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/crud.snippet.dog-model-shows-namespace.cpp @@ -25,6 +25,12 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-realm-object.rst b/source/includes/sdk-examples/crud/create-realm-object.rst index b179aad056..991d20cc6a 100644 --- a/source/includes/sdk-examples/crud/create-realm-object.rst +++ b/source/includes/sdk-examples/crud/create-realm-object.rst @@ -1,7 +1,7 @@ .. tabs-drivers:: tabs: - - id: cpp + - id: cpp-sdk content: | .. literalinclude:: /examples/generated/cpp/crud.snippet.create-an-object.cpp @@ -27,6 +27,14 @@ :emphasize-lines: 3 :copyable: false + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.create-an-object.kt + :language: kotlin + :emphasize-lines: 3 + :copyable: false + - id: javascript content: | diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 05f1debc6f..c065bff834 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -113,7 +113,7 @@ To create a new object and persist it to the database: .. tabs-drivers:: .. tab:: - :tabid: cpp + :tabid: cpp-sdk .. include:: /includes/api-details/cpp/crud/create-procedure.rst @@ -132,6 +132,11 @@ To create a new object and persist it to the database: .. include:: /includes/api-details/java/crud/create-procedure.rst + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-procedure.rst + .. tab:: :tabid: javascript @@ -166,7 +171,7 @@ Create a Realm Object .. tabs-drivers:: .. tab:: - :tabid: cpp + :tabid: cpp-sdk .. include:: /includes/api-details/cpp/crud/create-realm-object-description.rst @@ -185,6 +190,11 @@ Create a Realm Object .. include:: /includes/api-details/java/crud/create-realm-object-description.rst + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-realm-object-description.rst + .. tab:: :tabid: javascript @@ -244,7 +254,7 @@ different parent object or share it between multiple parent objects. .. tabs-drivers:: .. tab:: - :tabid: cpp + :tabid: cpp-sdk .. include:: /includes/api-details/cpp/crud/create-embedded-object-description.rst @@ -263,6 +273,11 @@ different parent object or share it between multiple parent objects. .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + .. tab:: :tabid: javascript @@ -313,7 +328,7 @@ refer to :ref:`sdks-stream-data-to-atlas`. .. tabs-drivers:: .. tab:: - :tabid: cpp + :tabid: cpp-sdk .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst @@ -332,6 +347,11 @@ refer to :ref:`sdks-stream-data-to-atlas`. .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + .. tab:: :tabid: javascript From 1e5a5b2c7f1e52ab3f312163f90793e1b98c56d3 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 11:24:58 -0400 Subject: [PATCH 02/37] Test adding IO code block for Kotlin --- .../create-unmanaged-copy-description.rst | 4 ++ .../create-unmanaged-copy-not-supported.rst | 2 + .../create-unmanaged-copy-description.rst | 2 + .../create-unmanaged-copy-description.rst | 9 +++ .../crud/create-unmanaged-object.rst | 69 +++++++++++++++++++ source/sdk/crud/create.txt | 56 +++++++++++++++ 6 files changed, 142 insertions(+) create mode 100644 source/includes/api-details/cpp/crud/create-unmanaged-copy-description.rst create mode 100644 source/includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst create mode 100644 source/includes/api-details/java/crud/create-unmanaged-copy-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst create mode 100644 source/includes/sdk-examples/crud/create-unmanaged-object.rst diff --git a/source/includes/api-details/cpp/crud/create-unmanaged-copy-description.rst b/source/includes/api-details/cpp/crud/create-unmanaged-copy-description.rst new file mode 100644 index 0000000000..e8b7e0e8f5 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-unmanaged-copy-description.rst @@ -0,0 +1,4 @@ +Create an unmanaged version of a managed object by calling the ``detach()`` +function. This returns a value of the managed type. For example, calling +the ``detach()`` function on a managed string property of a managed object +returns a ``std::string`` copy of that property. diff --git a/source/includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst b/source/includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst new file mode 100644 index 0000000000..4a1ce01df6 --- /dev/null +++ b/source/includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst @@ -0,0 +1,2 @@ +The API to create an unmanaged copy of an object is either not needed or +not currently supported in this SDK. diff --git a/source/includes/api-details/java/crud/create-unmanaged-copy-description.rst b/source/includes/api-details/java/crud/create-unmanaged-copy-description.rst new file mode 100644 index 0000000000..eb53ec7007 --- /dev/null +++ b/source/includes/api-details/java/crud/create-unmanaged-copy-description.rst @@ -0,0 +1,2 @@ +Use :java-sdk:`realm.copyFromRealm() ` +to create an in-memory instance of a Realm object. diff --git a/source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst b/source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst new file mode 100644 index 0000000000..84e5dae493 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst @@ -0,0 +1,9 @@ +Create an unmanaged copy of a managed object by passing it to +`copyFromRealm() <{+kotlin-local-prefix+}io.realm.kotlin.ext/copy-from-realm.html>`__. +For collections, this is a deep copy that includes all referenced objects up +to the specified ``depth``. + +In the following example, we create an unmanaged copy of an existing +managed ``Pond`` object that contains a list of two ``Frog`` objects. +After copying the object from the realm, we confirm that the copy is +unmanaged and contains both referenced ``Frog`` objects: diff --git a/source/includes/sdk-examples/crud/create-unmanaged-object.rst b/source/includes/sdk-examples/crud/create-unmanaged-object.rst new file mode 100644 index 0000000000..4b60290825 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-unmanaged-object.rst @@ -0,0 +1,69 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.js + :language: javascript + + - id: kotlin + content: | + + .. io-code-block:: + + .. input:: /examples/generated/kotlin/CreateTest.snippet.create-unmanaged-copy.kt + :language: kotlin + + .. output:: + + Unmanaged pond name: Big Pond + Unmanaged frogs: Kermit, Froggy Jay + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index c065bff834..0e6e258968 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -392,6 +392,62 @@ For more information about modeling an asymmetric object, refer to: Create an Unmanaged Copy of an Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can create an unmanaged, in-memory copy of a managed object or collection. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + +.. include:: /includes/sdk-examples/crud/create-unmanaged-object.rst + .. _sdks-upsert-an-object: Create or Update an Object (Upsert) From 54398683608d416b9e4b8a50183bdcf51ae8f837 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 13:30:11 -0400 Subject: [PATCH 03/37] Update naming and Kotlin links --- .../crud/create-embedded-object-description.rst | 6 +++--- .../api-details/cpp/crud/create-procedure.rst | 2 +- .../cpp/crud/create-realm-object-description.rst | 6 +++--- .../crud/create-asymmetric-object-description.rst | 2 +- .../dart/crud/create-realm-object-description.rst | 7 ++++--- .../java/crud/create-realm-object-description.rst | 6 +++--- .../crud/create-unmanaged-copy-description.rst | 2 +- .../crud/create-realm-object-description.rst | 10 +++++----- .../crud/create-asymmetric-object-description.rst | 2 +- .../api-details/kotlin/crud/create-procedure.rst | 12 ++++++------ .../crud/create-unmanaged-copy-description.rst | 4 ++-- .../crud/create-realm-object-description.rst | 2 +- .../crud/create-asymmetric-object-description.rst | 2 +- .../crud/create-realm-object-description.rst | 2 +- .../crud/create-realm-object-description.rst | 8 ++++---- source/sdk/crud/create.txt | 15 +++++++++------ 16 files changed, 46 insertions(+), 42 deletions(-) diff --git a/source/includes/api-details/cpp/crud/create-embedded-object-description.rst b/source/includes/api-details/cpp/crud/create-embedded-object-description.rst index c2deb59ae6..51bdea508d 100644 --- a/source/includes/api-details/cpp/crud/create-embedded-object-description.rst +++ b/source/includes/api-details/cpp/crud/create-embedded-object-description.rst @@ -1,14 +1,14 @@ To create an embedded object, assign the raw pointer of the embedded object to a parent object's property. Move the parent object into -the realm using the :cpp-sdk:`Realm.add() function ` +the database using the :cpp-sdk:`Realm.add() function ` inside of a write transaction. In this example, we assign the raw pointer of the embedded object - ``ContactDetails *`` - to the embedded object property of the parent object - ``Business.contactDetails``. -Then, we add the ``business`` object to the realm. This copies the -``business`` and ``contactDetails`` objects to the realm. +Then, we add the ``business`` object to the database. This copies the +``business`` and ``contactDetails`` objects to the database. Because ``ContactDetails`` is an embedded object, it does not have its own lifecycle independent of the main ``Business`` object. diff --git a/source/includes/api-details/cpp/crud/create-procedure.rst b/source/includes/api-details/cpp/crud/create-procedure.rst index 98e85ab096..fc6935ebeb 100644 --- a/source/includes/api-details/cpp/crud/create-procedure.rst +++ b/source/includes/api-details/cpp/crud/create-procedure.rst @@ -6,7 +6,7 @@ #. Move the unmanaged object instance into the database using the :cpp-sdk:`Realm.add() function `. - When you move an object into a realm, this consumes the object as an rvalue. + When you move an object into a database, this consumes the object as an rvalue. You must use the managed object for any data access or observation. If you would like to immediately work with the object, return a managed version of the object. diff --git a/source/includes/api-details/cpp/crud/create-realm-object-description.rst b/source/includes/api-details/cpp/crud/create-realm-object-description.rst index e9d7eff12a..5e9971ef9b 100644 --- a/source/includes/api-details/cpp/crud/create-realm-object-description.rst +++ b/source/includes/api-details/cpp/crud/create-realm-object-description.rst @@ -1,10 +1,10 @@ To create an object, you must instantiate it using the ``realm`` namespace. -Move the object into the realm using the +Move the object into the database using the :cpp-sdk:`Realm.add() function ` inside of a write transaction. -When you move an object into a realm, this consumes the object as an +When you move an object into a database, this consumes the object as an rvalue. You must use the managed object for any data access or observation. -In this example, copying the ``dog`` object into the realm consumes +In this example, copying the ``dog`` object into the database consumes it as an rvalue. You can return the managed object to continue to work with it. diff --git a/source/includes/api-details/dart/crud/create-asymmetric-object-description.rst b/source/includes/api-details/dart/crud/create-asymmetric-object-description.rst index 1dbaf49905..9210ead407 100644 --- a/source/includes/api-details/dart/crud/create-asymmetric-object-description.rst +++ b/source/includes/api-details/dart/crud/create-asymmetric-object-description.rst @@ -1,2 +1,2 @@ -Once you have an open Realm, you can create an asymmetric object inside +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/crud/create-realm-object-description.rst b/source/includes/api-details/dart/crud/create-realm-object-description.rst index 37958863aa..fbcfcee003 100644 --- a/source/includes/api-details/dart/crud/create-realm-object-description.rst +++ b/source/includes/api-details/dart/crud/create-realm-object-description.rst @@ -11,6 +11,7 @@ You can also return values from the write transaction callback function. .. warning:: Write RealmObjects to One Realm File - You can only write ``RealmObjects`` to a single realm file. - If you already wrote a ``RealmObject`` to one realm file, - the SDK throws a ``RealmException`` if you try to write it to another database. + You can only write ``RealmObjects`` to a single database file. + If you already wrote a ``RealmObject`` to one database file, + the SDK throws a ``RealmException`` if you try to write it to another + database. diff --git a/source/includes/api-details/java/crud/create-realm-object-description.rst b/source/includes/api-details/java/crud/create-realm-object-description.rst index cb6fba2130..29160528a8 100644 --- a/source/includes/api-details/java/crud/create-realm-object-description.rst +++ b/source/includes/api-details/java/crud/create-realm-object-description.rst @@ -1,7 +1,7 @@ Use :java-sdk:`realm.createObject() ` -in a transaction to create a persistent instance of a Realm object in a -realm. You can then modify the returned object with other field values -using accessors and mutators. +in a transaction to create a persistent instance of a database object. You can +then modify the returned object with other field values using accessors and +mutators. The following example demonstrates how to create an object with :java-sdk:`createObject() `: diff --git a/source/includes/api-details/java/crud/create-unmanaged-copy-description.rst b/source/includes/api-details/java/crud/create-unmanaged-copy-description.rst index eb53ec7007..23512b07b9 100644 --- a/source/includes/api-details/java/crud/create-unmanaged-copy-description.rst +++ b/source/includes/api-details/java/crud/create-unmanaged-copy-description.rst @@ -1,2 +1,2 @@ Use :java-sdk:`realm.copyFromRealm() ` -to create an in-memory instance of a Realm object. +to create an in-memory instance of a database object. diff --git a/source/includes/api-details/javascript/crud/create-realm-object-description.rst b/source/includes/api-details/javascript/crud/create-realm-object-description.rst index f18ba92475..474e64f9f3 100644 --- a/source/includes/api-details/javascript/crud/create-realm-object-description.rst +++ b/source/includes/api-details/javascript/crud/create-realm-object-description.rst @@ -1,5 +1,5 @@ -To add an object to a realm, instantiate it as you would any other object -and then pass it to :js-sdk:`Realm.create() ` inside of a -write transaction. If the realm's :ref:`schema ` includes -the object type and the object conforms to the schema, then Realm -stores the object, which is now *managed* by the realm. +To add an object to a database, instantiate it as you would any other object +and then pass it to :js-sdk:`Realm.create() ` +inside of a write transaction. If the database :ref:`schema ` +includes the object type and the object conforms to the schema, then the SDK +stores the object, which is now *managed* by the database instance. diff --git a/source/includes/api-details/kotlin/crud/create-asymmetric-object-description.rst b/source/includes/api-details/kotlin/crud/create-asymmetric-object-description.rst index 5f145cc22d..d26f06703e 100644 --- a/source/includes/api-details/kotlin/crud/create-asymmetric-object-description.rst +++ b/source/includes/api-details/kotlin/crud/create-asymmetric-object-description.rst @@ -5,7 +5,7 @@ it into the database. To create a new ``AsymmetricRealmObject`` instance, instantiate a new object of an :ref:`asymmetric object type ` using -`insert() <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.ext/insert.html>`__. +:kotlin-sync-sdk:`insert() `. In the following example, we instantiate a new ``WeatherSensor`` object and pass it to ``insert()`` within a write transaction: diff --git a/source/includes/api-details/kotlin/crud/create-procedure.rst b/source/includes/api-details/kotlin/crud/create-procedure.rst index 4d81f4535e..ff9c1cf777 100644 --- a/source/includes/api-details/kotlin/crud/create-procedure.rst +++ b/source/includes/api-details/kotlin/crud/create-procedure.rst @@ -1,15 +1,15 @@ -#. Open a write transaction with `realm.write() - <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write.html>`__ or - `realm.writeBlocking() - <{+kotlin-local-prefix+}io.realm.kotlin/-realm/write-blocking.html>`__. +#. Open a write transaction with :kotlin-sdk:`realm.write() + ` or + :kotlin-sdk:`realm.writeBlocking() + `. #. Instantiate an unmanaged object instance with the class constructor. You can use an `apply block `__ to configure multiple properties at once. -#. Pass the unmanaged object instance to `copyToRealm() - <{+kotlin-local-prefix+}io.realm.kotlin/-mutable-realm/copy-to-realm.html>`__ +#. Pass the unmanaged object instance to :kotlin-sdk:`copyToRealm() + ` to persist the object data to the database. This method returns a live managed instance of the object. diff --git a/source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst b/source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst index 84e5dae493..08099a1e27 100644 --- a/source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst +++ b/source/includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst @@ -1,9 +1,9 @@ Create an unmanaged copy of a managed object by passing it to -`copyFromRealm() <{+kotlin-local-prefix+}io.realm.kotlin.ext/copy-from-realm.html>`__. +:kotlin-sdk:`copyFromRealm() `. For collections, this is a deep copy that includes all referenced objects up to the specified ``depth``. In the following example, we create an unmanaged copy of an existing managed ``Pond`` object that contains a list of two ``Frog`` objects. -After copying the object from the realm, we confirm that the copy is +After copying the object from the database, we confirm that the copy is unmanaged and contains both referenced ``Frog`` objects: diff --git a/source/includes/api-details/objectivec/crud/create-realm-object-description.rst b/source/includes/api-details/objectivec/crud/create-realm-object-description.rst index be7d8b3c32..729a168dc0 100644 --- a/source/includes/api-details/objectivec/crud/create-realm-object-description.rst +++ b/source/includes/api-details/objectivec/crud/create-realm-object-description.rst @@ -1,4 +1,4 @@ -To add an object to a realm, instantiate it as you would any other +To add an object to a database, instantiate it as you would any other object and then pass it to :objc-sdk:`-[RLMRealm addObject:] ` inside of a write transaction. diff --git a/source/includes/api-details/swift/crud/create-asymmetric-object-description.rst b/source/includes/api-details/swift/crud/create-asymmetric-object-description.rst index cd9dc7b89a..20dafee43f 100644 --- a/source/includes/api-details/swift/crud/create-asymmetric-object-description.rst +++ b/source/includes/api-details/swift/crud/create-asymmetric-object-description.rst @@ -2,6 +2,6 @@ You can only create an ``AsymmetricObject`` using :swift-sdk:`create(_ type:, value:) `. You cannot use the ``.add()`` API to create asymmetric object types. -You can create AsymmetricObjects for a realm initialized with a +You can create AsymmetricObjects for a database initialized with a :swift-sdk:`Flexible Sync configuration `. diff --git a/source/includes/api-details/swift/crud/create-realm-object-description.rst b/source/includes/api-details/swift/crud/create-realm-object-description.rst index 25fe15a5ea..952b085b02 100644 --- a/source/includes/api-details/swift/crud/create-realm-object-description.rst +++ b/source/includes/api-details/swift/crud/create-realm-object-description.rst @@ -1,4 +1,4 @@ -To add an object to a realm, instantiate it as you would any other +To add an object to a database, instantiate it as you would any other object and then pass it to :swift-sdk:`Realm.add(_:update:) ` inside of a write transaction. diff --git a/source/includes/api-details/typescript/crud/create-realm-object-description.rst b/source/includes/api-details/typescript/crud/create-realm-object-description.rst index f18ba92475..cee4e584b7 100644 --- a/source/includes/api-details/typescript/crud/create-realm-object-description.rst +++ b/source/includes/api-details/typescript/crud/create-realm-object-description.rst @@ -1,5 +1,5 @@ -To add an object to a realm, instantiate it as you would any other object +To add an object to a database, instantiate it as you would any other object and then pass it to :js-sdk:`Realm.create() ` inside of a -write transaction. If the realm's :ref:`schema ` includes -the object type and the object conforms to the schema, then Realm -stores the object, which is now *managed* by the realm. +write transaction. If the database :ref:`schema ` includes +the object type and the object conforms to the schema, then the SDK +stores the object, which is now *managed* by the database instance. diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 0e6e258968..4cb1704f2e 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -75,8 +75,8 @@ which creates a managed instance. updated with changes within write transactions as long as that database remains open. Managed objects are tied to the database instance from which they originated and cannot be directly written to another database. However, - the SDK supplies a method to copy managed objects from one database file to - another. + some of the SDKs supply a method to copy managed objects from one database + file to another. You can use the SDK's APIs with managed objects. For example, managed objects can have relationships with other objects and you can observe them @@ -84,7 +84,7 @@ which creates a managed instance. Refer to the :ref:`Create an Unmanaged Copy of an Object or Collection ` section on this page. -- **Unmanaged objects** are SDK objects that behave like normal Kotlin objects, +- **Unmanaged objects** are SDK objects that behave like normal objects, but they are not persisted in the database. All SDK objects are unmanaged until you add them to a database within a write transaction. You cannot use the SDK's APIs with unmanaged objects or observe them for @@ -95,10 +95,10 @@ which creates a managed instance. You can check if an object is managed with the ``isManaged`` API. -Create a Realm Object ---------------------- +Create a Database Object +------------------------ -Before you can create a new object and persist it to the realm, you must +Before you can create a new object and persist it to the database, you must :ref:`sdks-object-models`. Then, you include that object type in your database schema when you open the database. @@ -168,6 +168,9 @@ information, refer to :ref:`sdks-upsert-an-object`. Create a Realm Object ~~~~~~~~~~~~~~~~~~~~~ +The SDKs refer to the base object type as a Realm object. This is a legacy +of the former product name, Realm Database. + .. tabs-drivers:: .. tab:: From 9a10b93d4b2afd2450ecf232ebf717bb5d47dca4 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 14:05:47 -0400 Subject: [PATCH 04/37] Add Create or Update content --- .../cpp/api-not-supported-description.rst | 1 + .../create-or-update-object-description.rst | 5 ++ .../create-or-update-object-description.rst | 2 + ...eate-or-update-object-java-description.rst | 20 ++++++ ...te-or-update-object-kotlin-description.rst | 20 ++++++ .../create-or-update-object-description.rst | 4 ++ .../create-or-update-object-description.rst | 27 ++++++++ .../create-or-update-object-description.rst | 9 +++ .../create-or-update-object-description.rst | 9 +++ .../create-or-update-object-description.rst | 4 ++ .../crud/create-or-update-object.rst | 67 +++++++++++++++++++ source/sdk/crud/create.txt | 65 +++++++++++++++++- 12 files changed, 232 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/api-not-supported-description.rst create mode 100644 source/includes/api-details/csharp/crud/create-or-update-object-description.rst create mode 100644 source/includes/api-details/dart/crud/create-or-update-object-description.rst create mode 100644 source/includes/api-details/java/crud/create-or-update-object-java-description.rst create mode 100644 source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst create mode 100644 source/includes/api-details/javascript/crud/create-or-update-object-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-or-update-object-description.rst create mode 100644 source/includes/api-details/objectivec/crud/create-or-update-object-description.rst create mode 100644 source/includes/api-details/swift/crud/create-or-update-object-description.rst create mode 100644 source/includes/api-details/typescript/crud/create-or-update-object-description.rst create mode 100644 source/includes/sdk-examples/crud/create-or-update-object.rst diff --git a/source/includes/api-details/cpp/api-not-supported-description.rst b/source/includes/api-details/cpp/api-not-supported-description.rst new file mode 100644 index 0000000000..bfd43b8820 --- /dev/null +++ b/source/includes/api-details/cpp/api-not-supported-description.rst @@ -0,0 +1 @@ +This API is not currently supported in C++. diff --git a/source/includes/api-details/csharp/crud/create-or-update-object-description.rst b/source/includes/api-details/csharp/crud/create-or-update-object-description.rst new file mode 100644 index 0000000000..47dffba609 --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-or-update-object-description.rst @@ -0,0 +1,5 @@ +Upserting a document is the same as creating a new one, except you set the +optional ``update`` parameter to ``true``. In this example, we create a new +``Item`` object with a unique ``Id``. We then insert an item with the +same id but a different ``Name`` value. Because we have set the ``update`` +parameter to ``true``, the existing record is updated with the new name. diff --git a/source/includes/api-details/dart/crud/create-or-update-object-description.rst b/source/includes/api-details/dart/crud/create-or-update-object-description.rst new file mode 100644 index 0000000000..2a9cc1dc57 --- /dev/null +++ b/source/includes/api-details/dart/crud/create-or-update-object-description.rst @@ -0,0 +1,2 @@ +To upsert an object, call :flutter-sdk:`Realm.add() ` +with the optional ``update`` flag set to ``true`` inside a transaction block. diff --git a/source/includes/api-details/java/crud/create-or-update-object-java-description.rst b/source/includes/api-details/java/crud/create-or-update-object-java-description.rst new file mode 100644 index 0000000000..be8db936a6 --- /dev/null +++ b/source/includes/api-details/java/crud/create-or-update-object-java-description.rst @@ -0,0 +1,20 @@ +The following example demonstrates how to upsert an object with the +SDK. We create a new turtle enthusiast named "Drew" and then +update their name to "Andy" using :java-sdk:`insertOrUpdate() +`: + +.. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.upsert-an-object.java + :language: java + :emphasize-lines: 14-16 + :copyable: false + +You can also use :java-sdk:`copyToRealmOrUpdate() +` to +either create a new object based on a supplied object or update an +existing object with the same primary key value. Use the +``CHECK_SAME_VALUES_BEFORE_SET`` +:java-sdk:`ImportFlag ` to only update fields +that are different in the supplied object: + +The following example demonstrates how to insert an object or, if an object already +exists with the same primary key, update only those fields that differ: diff --git a/source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst b/source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst new file mode 100644 index 0000000000..e491605d38 --- /dev/null +++ b/source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst @@ -0,0 +1,20 @@ +The following example demonstrates how to upsert an object with the SDK. We +create a new turtle enthusiast named "Drew" and then +update their name to "Andy" using :java-sdk:`insertOrUpdate() +`: + +.. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.upsert-an-object.kt + :language: kotlin + :emphasize-lines: 14-16 + :copyable: false + +You can also use :java-sdk:`copyToRealmOrUpdate() +` to +either create a new object based on a supplied object or update an +existing object with the same primary key value. Use the +``CHECK_SAME_VALUES_BEFORE_SET`` +:java-sdk:`ImportFlag ` to only update fields +that are different in the supplied object: + +The following example demonstrates how to insert an object or, if an object already +exists with the same primary key, update only those fields that differ: diff --git a/source/includes/api-details/javascript/crud/create-or-update-object-description.rst b/source/includes/api-details/javascript/crud/create-or-update-object-description.rst new file mode 100644 index 0000000000..09e7f6f338 --- /dev/null +++ b/source/includes/api-details/javascript/crud/create-or-update-object-description.rst @@ -0,0 +1,4 @@ +To upsert an object, call :js-sdk:`Realm.create() ` +with the update mode set to ``modified``. The operation either inserts a +new object with the given primary key or updates an existing object that +already has that primary key. diff --git a/source/includes/api-details/kotlin/crud/create-or-update-object-description.rst b/source/includes/api-details/kotlin/crud/create-or-update-object-description.rst new file mode 100644 index 0000000000..d7f0f9c4b5 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-or-update-object-description.rst @@ -0,0 +1,27 @@ +To upsert an object into a database, insert an object with a primary key +using +:kotlin-sdk:`copyToRealm() `, +as you would when creating a new object. Pass an +:kotlin-sdk:`UpdatePolicy ` +parameter to specify how the SDK should handle existing objects with the same +primary key: + +- ``UpdatePolicy.ALL``: Update all properties on any existing objects + identified with the same primary key. +- ``UpdatePolicy.ERROR`` (default): Disallow updating existing objects and instead + throw an exception if an object already exists with the same primary key. If + you do not specify an update policy, the SDK uses this policy by default. + +The following can occur depending on the update policy: + +- If no object exists that matches the primary key, the SDK creates the new object. +- If an object with the same primary key already exists, the SDK either: + + - Updates all properties on any existing objects identified with the + same primary key. Note that properties are marked as updated in change + listeners, even if the property was updated to the same value. + - Throws an exception indicating that an object already exists in the database. + +In the following example, we attempt to insert a ``Frog`` object with a +primary key that already exists in the database with ``UpdatePolicy.ALL``. +Then, we confirm the object is successfully upserted: diff --git a/source/includes/api-details/objectivec/crud/create-or-update-object-description.rst b/source/includes/api-details/objectivec/crud/create-or-update-object-description.rst new file mode 100644 index 0000000000..a72ed64ef4 --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-or-update-object-description.rst @@ -0,0 +1,9 @@ +To upsert an object, call :objc-sdk:`-[RLMRealm +addOrUpdateObject:] +`. + +.. literalinclude:: /examples/generated/code/start/ReadWriteData.snippet.upsert.m + :language: objectivec + +You can also partially update an object by passing the primary key and a +subset of the values to update: diff --git a/source/includes/api-details/swift/crud/create-or-update-object-description.rst b/source/includes/api-details/swift/crud/create-or-update-object-description.rst new file mode 100644 index 0000000000..284de14920 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-or-update-object-description.rst @@ -0,0 +1,9 @@ +To upsert an object, call :swift-sdk:`Realm.add(_:update:) +` +with the second parameter, update policy, set to ``.modified``. + +.. literalinclude:: /examples/generated/code/start/UpdateRealmObjects.snippet.upsert.swift + :language: swift + +You can also partially update an object by passing the primary key and a +subset of the values to update: diff --git a/source/includes/api-details/typescript/crud/create-or-update-object-description.rst b/source/includes/api-details/typescript/crud/create-or-update-object-description.rst new file mode 100644 index 0000000000..09e7f6f338 --- /dev/null +++ b/source/includes/api-details/typescript/crud/create-or-update-object-description.rst @@ -0,0 +1,4 @@ +To upsert an object, call :js-sdk:`Realm.create() ` +with the update mode set to ``modified``. The operation either inserts a +new object with the given primary key or updates an existing object that +already has that primary key. diff --git a/source/includes/sdk-examples/crud/create-or-update-object.rst b/source/includes/sdk-examples/crud/create-or-update-object.rst new file mode 100644 index 0000000000..478dfd9e16 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-or-update-object.rst @@ -0,0 +1,67 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.upsert.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/read_write_data_test.snippet.upsert.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.copy-or-update-same-values-flag.java + :language: java + :emphasize-lines: 16 + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.copy-or-update-same-values-flag.kt + :language: kotlin + :emphasize-lines: 15-16 + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/read-and-write-data.snippet.read-and-write-upsert-an-object.js + :language: javascript + :emphasize-lines: 4, 13 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/UpdateTest.snippet.upsert-an-object.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ReadWriteData.snippet.partial-update.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/UpdateRealmObjects.snippet.partial-update.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 4cb1704f2e..adee839818 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -395,7 +395,9 @@ For more information about modeling an asymmetric object, refer to: Create an Unmanaged Copy of an Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can create an unmanaged, in-memory copy of a managed object or collection. +Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a +managed object or collection. In other SDKs, this API is not needed or not +currently implemented. .. tabs-drivers:: @@ -455,3 +457,64 @@ You can create an unmanaged, in-memory copy of a managed object or collection. Create or Update an Object (Upsert) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An **upsert** is a write operation that either inserts a new object +with a given primary key or updates an existing object that already has +that primary key. We call this an upsert because it is an "**update** or +**insert**" operation. This is useful when an object may or may not +already exist, such as when bulk importing a dataset into an existing +realm. Upserting lets you update existing entries while adding any new entries. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/api-not-supported-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-or-update-object-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-or-update-object-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst + +.. include:: /includes/sdk-examples/crud/create-or-update-object.rst From 54d233d3ee5466b510a17e8438ee45e6923021a9 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 15:26:11 -0400 Subject: [PATCH 05/37] Add mixed property type --- ...create-mixed-property-type-description.rst | 3 + ...create-mixed-property-type-description.rst | 9 +++ ...create-mixed-property-type-description.rst | 2 + ...create-mixed-property-type-description.rst | 12 +++ ...create-mixed-property-type-description.rst | 2 + ...create-mixed-property-type-description.rst | 12 +++ ...create-mixed-property-type-description.rst | 7 ++ ...create-mixed-property-type-description.rst | 7 ++ ...create-mixed-property-type-description.rst | 2 + .../crud/create-mixed-property-type.rst | 62 +++++++++++++++ source/sdk/crud/create.txt | 78 ++++++++++++++++++- source/sdk/model-data/object-models.txt | 5 ++ source/sdk/model-data/supported-types.txt | 6 ++ 13 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/csharp/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/dart/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/java/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/javascript/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/objectivec/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/swift/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/api-details/typescript/crud/create-mixed-property-type-description.rst create mode 100644 source/includes/sdk-examples/crud/create-mixed-property-type.rst diff --git a/source/includes/api-details/cpp/crud/create-mixed-property-type-description.rst b/source/includes/api-details/cpp/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..b9e2c69243 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-mixed-property-type-description.rst @@ -0,0 +1,3 @@ +When you create an object with a ``realm::mixed`` value, you must specify the +type of the value you store in the property. The SDK provides a ``type()`` +function you can call to determine what type of data the property has stored. diff --git a/source/includes/api-details/csharp/crud/create-mixed-property-type-description.rst b/source/includes/api-details/csharp/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..5fcff67c42 --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-mixed-property-type-description.rst @@ -0,0 +1,9 @@ +.. note:: + + You cannot create a nullable ``RealmValue``. However, if you want a + ``RealmValue`` property to contain a null value, you can + use the special ``RealmValue.Null`` property. + +The following code demonstrates creating a ``RealmValue`` property in a class +that inherits from ``IRealmObject`` and then setting and getting the value of +that property: diff --git a/source/includes/api-details/dart/crud/create-mixed-property-type-description.rst b/source/includes/api-details/dart/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..e37f980e09 --- /dev/null +++ b/source/includes/api-details/dart/crud/create-mixed-property-type-description.rst @@ -0,0 +1,2 @@ +To add a ``RealmValue`` to an object, call ``RealmValue.from()`` on the data +or ``RealmValue.nullValue()`` to set a null value. diff --git a/source/includes/api-details/java/crud/create-mixed-property-type-description.rst b/source/includes/api-details/java/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..1ab4164235 --- /dev/null +++ b/source/includes/api-details/java/crud/create-mixed-property-type-description.rst @@ -0,0 +1,12 @@ +To create a ``RealmAny`` instance, use the +:java-sdk:`RealmAny.valueOf() ` method +to assign an initial value or ``RealmAny.nullValue()`` to assign no +value. ``RealmAny`` instances are immutable just like ``String`` or +``Integer`` instances; if you want to assign a new value to a +``RealmAny`` field, you must create a new ``RealmAny`` instance. + +.. warning:: Two Possible Null ``RealmAny`` Values + + ``RealmAny`` instances are always :ref:`nullable + `. Additionally, instances can contain a + value of type ``RealmAny.Type.NULL``. diff --git a/source/includes/api-details/javascript/crud/create-mixed-property-type-description.rst b/source/includes/api-details/javascript/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..a939d3ffc1 --- /dev/null +++ b/source/includes/api-details/javascript/crud/create-mixed-property-type-description.rst @@ -0,0 +1,2 @@ +Create an object with a mixed value by running the :js-sdk:`realm.create() +` method within a write transaction. diff --git a/source/includes/api-details/kotlin/crud/create-mixed-property-type-description.rst b/source/includes/api-details/kotlin/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..44a98b5e50 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-mixed-property-type-description.rst @@ -0,0 +1,12 @@ +To create a new object instance with a polymorphic +:kotlin-sdk:`RealmAny ` +property, instantiate an object and pass an initial value of a +supported type to the ``RealmAny`` property using +:kotlin-sdk:`RealmAny.create() `. + +After you create the object, you *must* know the stored value type +to work with the ``RealmAny`` property. + +In the following example, we instantiate a new ``Frog`` object with a +``favoriteThings`` list of ``RealmAny`` type and pass the initial values to +``RealmAny.create()``: diff --git a/source/includes/api-details/objectivec/crud/create-mixed-property-type-description.rst b/source/includes/api-details/objectivec/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..a3ee3c39b6 --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-mixed-property-type-description.rst @@ -0,0 +1,7 @@ +When you create an object with an ``RLMValue``, you must specify the +type of the value you store in the property. The SDK provides an +:objc-sdk:`RLMValue type ` +that you can use to determine what type of value the property has stored. + +Later, when you read the mixed property type, you must check the type before +you do anything with the value. diff --git a/source/includes/api-details/swift/crud/create-mixed-property-type-description.rst b/source/includes/api-details/swift/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..26185a3074 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-mixed-property-type-description.rst @@ -0,0 +1,7 @@ +When you create an object with an ``AnyRealmValue``, you must specify the +type of the value you store in the property. The SDK provides an +:swift-sdk:`AnyRealmValue enum ` that iterates +through all of the types the ``AnyRealmValue`` can store. + +Later, when you read the mixed property type, you must check the type before +you do anything with the value. diff --git a/source/includes/api-details/typescript/crud/create-mixed-property-type-description.rst b/source/includes/api-details/typescript/crud/create-mixed-property-type-description.rst new file mode 100644 index 0000000000..a939d3ffc1 --- /dev/null +++ b/source/includes/api-details/typescript/crud/create-mixed-property-type-description.rst @@ -0,0 +1,2 @@ +Create an object with a mixed value by running the :js-sdk:`realm.create() +` method within a write transaction. diff --git a/source/includes/sdk-examples/crud/create-mixed-property-type.rst b/source/includes/sdk-examples/crud/create-mixed-property-type.rst new file mode 100644 index 0000000000..509d6ad17e --- /dev/null +++ b/source/includes/sdk-examples/crud/create-mixed-property-type.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/DataTypesSectionExamples.snippet.realmvalue.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-from.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/data-types.snippet.create-objects-with-mixed-values.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-realmany-property.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/CreateRealmObjects.snippet.mixed-data-type.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index adee839818..e6dd52a7e1 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -165,6 +165,8 @@ To create a new object and persist it to the database: You can also upsert into a database using specific criteria. For more information, refer to :ref:`sdks-upsert-an-object`. +.. _sdks-create-realm-object: + Create a Realm Object ~~~~~~~~~~~~~~~~~~~~~ @@ -510,7 +512,7 @@ realm. Upserting lets you update existing entries while adding any new entries. .. tab:: :tabid: swift - .. include:: /includes/api-details/generic/crud/create-or-update-object-description.rst + .. include:: /includes/api-details/swift/crud/create-or-update-object-description.rst .. tab:: :tabid: typescript @@ -518,3 +520,77 @@ realm. Upserting lets you update existing entries while adding any new entries. .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst .. include:: /includes/sdk-examples/crud/create-or-update-object.rst + +.. _sdks-create-special-property-types: + +Create Special Property Types +----------------------------- + +Depending on how you define your object type, you might have properties +that are special SDK-specific types. These may be custom data types, or +familiar language types that have specific requirements or limitations when +used with Atlas Device SDK. + +Create a Generic (Mixed) Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SDK provides a generic mixed property type that could contain a +number of property types. It's the closest analog to a polymorphic data type +that the SDK provides. + +For a list of the value types that a mixed property can hold, refer to +:ref:`sdks-mixed-data-type`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/create-mixed-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-mixed-property-type-description.rst + +.. include:: /includes/sdk-examples/crud/create-mixed-property-type.rst diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index a25708ff63..8590061623 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -45,3 +45,8 @@ Define Special Property Types Define a Full-Text Search Property ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-optional-property-types: + +Define Optional Property Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/supported-types.txt index 6a13f4c7e2..d4a94eec66 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/supported-types.txt @@ -19,3 +19,9 @@ Supported Types :class: singlecol Placeholder page for supported data types. + + +.. _sdks-mixed-data-type: + +Generic (Mixed) Data Type +~~~~~~~~~~~~~~~~~~~~~~~~~ From 439d26beeac21f5d90a4a35bcfa5b91fb2a5b926 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 16:51:10 -0400 Subject: [PATCH 06/37] Add details about creating a List property, flesh out page ToC --- .../crud/create-list-property-description.rst | 28 ++++ .../crud/create-list-property-description.rst | 3 + .../crud/create-list-property-description.rst | 3 + .../crud/create-list-property-description.rst | 3 + .../crud/create-list-property-description.rst | 2 + .../crud/create-list-property-description.rst | 14 ++ .../crud/create-list-property-description.rst | 2 + .../crud/create-list-property.rst | 62 +++++++ source/sdk/crud/create.txt | 155 +++++++++++++++++- source/sdk/model-data/supported-types.txt | 5 + source/sdk/react-to-changes.txt | 10 ++ 11 files changed, 286 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/crud/create-list-property-description.rst create mode 100644 source/includes/api-details/csharp/crud/create-list-property-description.rst create mode 100644 source/includes/api-details/dart/crud/create-list-property-description.rst create mode 100644 source/includes/api-details/java/crud/create-list-property-description.rst create mode 100644 source/includes/api-details/javascript/crud/create-list-property-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-list-property-description.rst create mode 100644 source/includes/api-details/typescript/crud/create-list-property-description.rst create mode 100644 source/includes/sdk-examples/crud/create-list-property.rst diff --git a/source/includes/api-details/cpp/crud/create-list-property-description.rst b/source/includes/api-details/cpp/crud/create-list-property-description.rst new file mode 100644 index 0000000000..a8251e9bfe --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-list-property-description.rst @@ -0,0 +1,28 @@ +To create an object with a list property (to-many relationship) to one or +more objects: + +- Initialize the main object and the related objects +- Use the :cpp-sdk:`push_back + ` + member function available to the SDK object lists + to append the raw pointers of the related objects to the main object's + list property +- Move the object into the realm using the + :cpp-sdk:`Realm.add() function ` + inside of a write transaction. + +In this example, we append the raw pointers of the related objects - +``Employee *`` - to the relationship property of the main object +- ``Company.employees``. This creates a one-way connection from the +``Company`` object to the ``Employee`` objects. + +Then, we add the ``Company`` to the database. This copies the +``Company`` and ``Employee`` objects to the database. + +The related ``Employee`` objects have their own lifecycle independent +of the main ``Company`` object. If you delete the main object, the +related objects remain. + +You can optionally create an inverse relationship to refer to the main object +from the related object. For more information, refer to: +:ref:`sdks-create-object-with-inverse-relationship`. diff --git a/source/includes/api-details/csharp/crud/create-list-property-description.rst b/source/includes/api-details/csharp/crud/create-list-property-description.rst new file mode 100644 index 0000000000..97377df95d --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-list-property-description.rst @@ -0,0 +1,3 @@ +You create a list collection property by defining a getter-only property of type +`IList `_, +where ``T`` can be any data type (except other collections). diff --git a/source/includes/api-details/dart/crud/create-list-property-description.rst b/source/includes/api-details/dart/crud/create-list-property-description.rst new file mode 100644 index 0000000000..8510ff09c5 --- /dev/null +++ b/source/includes/api-details/dart/crud/create-list-property-description.rst @@ -0,0 +1,3 @@ +You can create a relationship between one object and any number of objects +using a property of type ``List`` in your application, where T is an SDK +model class. diff --git a/source/includes/api-details/java/crud/create-list-property-description.rst b/source/includes/api-details/java/crud/create-list-property-description.rst new file mode 100644 index 0000000000..b2e9889d3f --- /dev/null +++ b/source/includes/api-details/java/crud/create-list-property-description.rst @@ -0,0 +1,3 @@ +You can create a relationship between one object +and any number of objects using a field of type ``RealmList`` +where ``T`` is an SDK object in your application. diff --git a/source/includes/api-details/javascript/crud/create-list-property-description.rst b/source/includes/api-details/javascript/crud/create-list-property-description.rst new file mode 100644 index 0000000000..2d4a846db5 --- /dev/null +++ b/source/includes/api-details/javascript/crud/create-list-property-description.rst @@ -0,0 +1,2 @@ +To define a to-many relationship, specify a property where the type is a list +or array of the related SDK object type in its object schema. diff --git a/source/includes/api-details/kotlin/crud/create-list-property-description.rst b/source/includes/api-details/kotlin/crud/create-list-property-description.rst new file mode 100644 index 0000000000..2099b30d91 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-list-property-description.rst @@ -0,0 +1,14 @@ +To create a new object instance with a +:kotlin-sdk:`RealmList ` +property, instantiate an object and pass any values of a +supported type to the ``RealmList`` property. + +You can instantiate an unmanaged list with :kotlin-sdk:`realmListOf() ` +or pass elements to the list using +:kotlin-sdk:`list.add() `, +:kotlin-sdk:`list.addAll() `, +or :kotlin-sdk:`list.set() `. +The list is unmanaged until you copy it to the database. + +In the following example, we instantiate a new ``Frog`` object with +initial values for several ``RealmList`` properties: diff --git a/source/includes/api-details/typescript/crud/create-list-property-description.rst b/source/includes/api-details/typescript/crud/create-list-property-description.rst new file mode 100644 index 0000000000..2d4a846db5 --- /dev/null +++ b/source/includes/api-details/typescript/crud/create-list-property-description.rst @@ -0,0 +1,2 @@ +To define a to-many relationship, specify a property where the type is a list +or array of the related SDK object type in its object schema. diff --git a/source/includes/sdk-examples/crud/create-list-property.rst b/source/includes/sdk-examples/crud/create-list-property.rst new file mode 100644 index 0000000000..23cbbc56e0 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-list-property.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/relationships.snippet.create-to-many-relationship.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.many-to-many-models.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-realm-list.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index e6dd52a7e1..a080a2f0ba 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -392,6 +392,16 @@ For more information about modeling an asymmetric object, refer to: .. include:: /includes/sdk-examples/crud/create-asymmetric-object-model.rst +.. _sdks-create-geospatial-data: + +Create a Geospatial Data Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + +Model +````` + .. _sdks-create-unmanaged-copy: Create an Unmanaged Copy of an Object @@ -521,6 +531,23 @@ realm. Upserting lets you update existing entries while adding any new entries. .. include:: /includes/sdk-examples/crud/create-or-update-object.rst +.. _sdks-create-objects-from-json: + +Create Objects from JSON +~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. _sdks-create-objects-with-value: + +Initialize Objects with a Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. _sdks-create-copy-object-to-another-database: + +Copy an Object to Another Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. _sdks-create-special-property-types: Create Special Property Types @@ -531,6 +558,8 @@ that are special SDK-specific types. These may be custom data types, or familiar language types that have specific requirements or limitations when used with Atlas Device SDK. +.. _sdks-create-mixed-property-type: + Create a Generic (Mixed) Property ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -546,7 +575,7 @@ For a list of the value types that a mixed property can hold, refer to .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/create-mixed-property-type-description.rst + .. include:: /includes/api-details/cpp/crud/create-mixed-property-type-description.rst .. tab:: :tabid: csharp @@ -594,3 +623,127 @@ For a list of the value types that a mixed property can hold, refer to .. include:: /includes/api-details/typescript/crud/create-mixed-property-type-description.rst .. include:: /includes/sdk-examples/crud/create-mixed-property-type.rst + +.. _sdks-create-counter-property-type: + +Create a Counter Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-create-timestamp-property-type: + +Create a Timestamp Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-create-collection-property-types: + +Create Collection Property Types +-------------------------------- + +The SDK provides a few collection type properties: + +- List +- Set +- Map + +Collections are mutable: you can add and remove elements in a collection +within a write transaction. + +Collections can contain both managed and unmanaged objects. When +you copy a collection to the database, you create a managed instance of the +collection *and* all elements in the collection, including any +unmanaged elements. Unmanaged collections behave like their corresponding +language classes and are not persisted to the database. + +.. tip:: Listen for Changes to a Created Collection + + After you create a collection, you can register a notification handler to + listen for changes. For more information, refer to + :ref:``. + +.. _sdks-create-list-properties: + +Create List Properties +~~~~~~~~~~~~~~~~~~~~~~ + +The SDK uses the List container type to define to-many relationships. A +**to-many** relationship means that an object is related in a specific +way to multiple objects. + +For a list of the value types that a list property can hold, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-list-property-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-list-property-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-list-property-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-list-property-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-list-property-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-list-property-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-mixed-property-type-description.rst + +.. include:: /includes/sdk-examples/crud/create-list-property.rst + +.. _sdks-create-set-properties: + +Create Set Properties +~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-create-dictionary-properties: + +Create Dictionary Properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-create-relationship-property-types: + +Create Relationship Property Types +---------------------------------- + +Create a To-One Relationship +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create a To-Many Relationship +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-create-object-with-inverse-relationship: + +Create an Inverse Relationship +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/supported-types.txt index d4a94eec66..b686b0722f 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/supported-types.txt @@ -25,3 +25,8 @@ Placeholder page for supported data types. Generic (Mixed) Data Type ~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-list-property-types: + +Supported List Property Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/react-to-changes.txt b/source/sdk/react-to-changes.txt index e3a25cbb04..f4aa4c2320 100644 --- a/source/sdk/react-to-changes.txt +++ b/source/sdk/react-to-changes.txt @@ -11,3 +11,13 @@ React to Changes :class: singlecol Placeholder page for information about realm notifications. + +.. _sdks-collection-change-listener: + +Register a Collection Change Listener +------------------------------------- + +.. _sdks-list-change-listener: + +React to List Changes +~~~~~~~~~~~~~~~~~~~~~ From b55c6d33b2c7e8ac7f2a3fd406629d566f1d3864 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 17:22:56 -0400 Subject: [PATCH 07/37] Add creating geospatial data --- ...create-geospatial-object-not-supported.rst | 1 + ...te-geospatial-object-js-ts-description.rst | 3 + ...create-geospatial-object-not-supported.rst | 2 + .../crud/create-geospatial-data-model.rst | 65 +++++++++++++++++++ .../crud/create-geospatial-data-object.rst | 62 ++++++++++++++++++ source/sdk/crud/create.txt | 58 +++++++++++++++++ 6 files changed, 191 insertions(+) create mode 100644 source/includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst create mode 100644 source/includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst create mode 100644 source/includes/api-details/java/crud/create-geospatial-object-not-supported.rst create mode 100644 source/includes/sdk-examples/crud/create-geospatial-data-model.rst create mode 100644 source/includes/sdk-examples/crud/create-geospatial-data-object.rst diff --git a/source/includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst b/source/includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst new file mode 100644 index 0000000000..0fb2bb5e45 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst @@ -0,0 +1 @@ +The C++ SDK does not currently support geospatial data. diff --git a/source/includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst b/source/includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst new file mode 100644 index 0000000000..aa08c242e1 --- /dev/null +++ b/source/includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst @@ -0,0 +1,3 @@ +However, in this example, because the ``MyGeoPoint`` class does not +extend ``Realm.Object``, we must specify ``MyGeoPoint.schema`` when opening +the database: diff --git a/source/includes/api-details/java/crud/create-geospatial-object-not-supported.rst b/source/includes/api-details/java/crud/create-geospatial-object-not-supported.rst new file mode 100644 index 0000000000..5d99e9a83c --- /dev/null +++ b/source/includes/api-details/java/crud/create-geospatial-object-not-supported.rst @@ -0,0 +1,2 @@ +The Java SDK does not support geospatial data. To store and query geospatial +data, use the Kotlin SDK. diff --git a/source/includes/sdk-examples/crud/create-geospatial-data-model.rst b/source/includes/sdk-examples/crud/create-geospatial-data-model.rst new file mode 100644 index 0000000000..f042b1640c --- /dev/null +++ b/source/includes/sdk-examples/crud/create-geospatial-data-model.rst @@ -0,0 +1,65 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Geospatial.snippet.usingcustomgeopoint.cs + :language: csharp + :emphasize-lines: 7 + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/geospatial_data_test.snippet.use-geopoint-class.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.use-geopoint-class.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Geospatial.snippet.geopoint-model.kt + :language: kotlin + :emphasize-lines: 4 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Geospatial.snippet.custom-geopoint.swift + :language: swift + :emphasize-lines: 2-3 + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.use-geopoint-class.ts + :language: typescript diff --git a/source/includes/sdk-examples/crud/create-geospatial-data-object.rst b/source/includes/sdk-examples/crud/create-geospatial-data-object.rst new file mode 100644 index 0000000000..3633b9f35b --- /dev/null +++ b/source/includes/sdk-examples/crud/create-geospatial-data-object.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Geospatial.snippet.geopoint.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/geospatial_data_test.snippet.write-geospatial-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.write-geospatial-object.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Geospatial.snippet.create-geopoint.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.write-geospatial-object.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index a080a2f0ba..aa05e518a4 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -397,11 +397,69 @@ For more information about modeling an asymmetric object, refer to: Create a Geospatial Data Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +After you :ref:`define a geospatial object type `, +you can use that type to create objects that persist geospatial data. +Initialize objects that use the geospatial data class, and add them to the +database like you would any other object type. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-geospatial-object-not-supported.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-geospatial-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-geospatial-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst + + +.. include:: /includes/sdk-examples/crud/create-geospatial-data-object.rst + +The following image shows the results of creating these two company objects: + +.. figure:: /images/geopoints.png + :alt: 2 GeoPoints + :width: 150 + :lightbox: Model ````` +.. include:: /includes/sdk-examples/crud/create-geospatial-data-model.rst + .. _sdks-create-unmanaged-copy: Create an Unmanaged Copy of an Object From 771dd8916248a8ad9f58b0e192366839c5b1675c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 22 May 2024 17:26:46 -0400 Subject: [PATCH 08/37] Fix snooty build error --- source/sdk/crud/create.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index aa05e518a4..3821b4f5d7 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -408,7 +408,7 @@ database like you would any other object type. .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/generic/crud/create-geospatial-object-not-supported.rst + .. include:: /includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst .. tab:: :tabid: csharp From a51f41eaae2d31adccbaa3b480be80252c84c21b Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 09:12:09 -0400 Subject: [PATCH 09/37] Add create multiple objects details --- .../create-multiple-objects-description.rst | 4 + .../create-multiple-objects-description.rst | 3 + ...eate-multiple-objects-no-dedicated-api.rst | 1 + .../create-multiple-objects-description.rst | 4 + .../create-multiple-objects-description.rst | 3 + .../crud/create-multiple-objects.rst | 62 +++ source/sdk/crud/create.txt | 401 +++++++++++------- 7 files changed, 323 insertions(+), 155 deletions(-) create mode 100644 source/includes/api-details/csharp/crud/create-multiple-objects-description.rst create mode 100644 source/includes/api-details/dart/crud/create-multiple-objects-description.rst create mode 100644 source/includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst create mode 100644 source/includes/api-details/objectivec/crud/create-multiple-objects-description.rst create mode 100644 source/includes/api-details/swift/crud/create-multiple-objects-description.rst create mode 100644 source/includes/sdk-examples/crud/create-multiple-objects.rst diff --git a/source/includes/api-details/csharp/crud/create-multiple-objects-description.rst b/source/includes/api-details/csharp/crud/create-multiple-objects-description.rst new file mode 100644 index 0000000000..8778c1566f --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-multiple-objects-description.rst @@ -0,0 +1,4 @@ +You can create multiple items in the database using the +:dotnet-sdk:`Add(IEnumerable, bool) ` +method. It takes a collection of standalone ``IRealmObject`` instances to +add to the database. diff --git a/source/includes/api-details/dart/crud/create-multiple-objects-description.rst b/source/includes/api-details/dart/crud/create-multiple-objects-description.rst new file mode 100644 index 0000000000..993d130edb --- /dev/null +++ b/source/includes/api-details/dart/crud/create-multiple-objects-description.rst @@ -0,0 +1,3 @@ +To add multiple objects to a database, pass a list of multiple objects +to :flutter-sdk:`Realm.addAll() ` inside a write +transaction block. diff --git a/source/includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst b/source/includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst new file mode 100644 index 0000000000..378167cf98 --- /dev/null +++ b/source/includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst @@ -0,0 +1 @@ +The SDK does not have a dedicated API to create multiple objects. diff --git a/source/includes/api-details/objectivec/crud/create-multiple-objects-description.rst b/source/includes/api-details/objectivec/crud/create-multiple-objects-description.rst new file mode 100644 index 0000000000..b6985d86ff --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-multiple-objects-description.rst @@ -0,0 +1,4 @@ +You can create multiple items in the database using the +:objc-sdk:`-[RLMRealm +addObjects:] ` +method. It takes a collection of objects to add to the database. diff --git a/source/includes/api-details/swift/crud/create-multiple-objects-description.rst b/source/includes/api-details/swift/crud/create-multiple-objects-description.rst new file mode 100644 index 0000000000..e378a3e278 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-multiple-objects-description.rst @@ -0,0 +1,3 @@ +You can create multiple items in the database using the +:swift-sdk:`add() ` +method. It takes a sequence of objects to add to the database. diff --git a/source/includes/sdk-examples/crud/create-multiple-objects.rst b/source/includes/sdk-examples/crud/create-multiple-objects.rst new file mode 100644 index 0000000000..e753cac0d6 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-multiple-objects.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/read_write_data_test.snippet.create-multiple-objects.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 3821b4f5d7..5715870414 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -95,18 +95,17 @@ which creates a managed instance. You can check if an object is managed with the ``isManaged`` API. -Create a Database Object ------------------------- +.. _sdks-create-object-methods: -Before you can create a new object and persist it to the database, you must -:ref:`sdks-object-models`. Then, you include that object type in your database -schema when you open the database. +Create Object Methods +--------------------- -.. important:: Object Types Must Be in Your Schema +The SDK provides many methods to create objects. - You can only write objects whose object type is included in the database - schema. If you try to reference or write an object of an object type - that isn't in your schema, the SDK returns a schema validation error. +.. _sdks-create-one-object: + +Create One Object +~~~~~~~~~~~~~~~~~ To create a new object and persist it to the database: @@ -162,9 +161,232 @@ To create a new object and persist it to the database: .. include:: /includes/api-details/typescript/crud/create-procedure.rst +.. include:: /includes/sdk-examples/crud/create-realm-object.rst + You can also upsert into a database using specific criteria. For more information, refer to :ref:`sdks-upsert-an-object`. +.. _sdks-create-multiple-objects: + +Create Multiple Objects +~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide a dedicated API to create multiple objects from +a sequence or collection. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + +.. include:: /includes/sdk-examples/crud/create-multiple-objects.rst + +.. _sdks-upsert-an-object: + +Create or Update an Object (Upsert) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An **upsert** is a write operation that either inserts a new object +with a given primary key or updates an existing object that already has +that primary key. We call this an upsert because it is an "**update** or +**insert**" operation. This is useful when an object may or may not +already exist, such as when bulk importing a dataset into an existing +realm. Upserting lets you update existing entries while adding any new entries. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/api-not-supported-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-or-update-object-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-or-update-object-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst + +.. include:: /includes/sdk-examples/crud/create-or-update-object.rst + +.. _sdks-create-objects-with-value: + +Initialize Objects with a Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-create-objects-from-json: + +Create Objects from JSON +~~~~~~~~~~~~~~~~~~~~~~~~ + + +.. _sdks-create-unmanaged-copy: + +Create an Unmanaged Copy of an Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a +managed object or collection. In other SDKs, this API is not needed or not +currently implemented. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + +.. include:: /includes/sdk-examples/crud/create-unmanaged-object.rst + +.. _sdks-create-copy-object-to-another-database: + +Copy an Object to Another Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Create Specific SDK Object Types +-------------------------------- + +Before you can create a new object and persist it to the database, you must +:ref:`sdks-object-models`. Then, you include that object type in your database +schema when you open the database. + +.. important:: Object Types Must Be in Your Schema + + You can only write objects whose object type is included in the database + schema. If you try to reference or write an object of an object type + that isn't in your schema, the SDK returns a schema validation error. + .. _sdks-create-realm-object: Create a Realm Object @@ -460,152 +682,6 @@ Model .. include:: /includes/sdk-examples/crud/create-geospatial-data-model.rst -.. _sdks-create-unmanaged-copy: - -Create an Unmanaged Copy of an Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a -managed object or collection. In other SDKs, this API is not needed or not -currently implemented. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - -.. include:: /includes/sdk-examples/crud/create-unmanaged-object.rst - -.. _sdks-upsert-an-object: - -Create or Update an Object (Upsert) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -An **upsert** is a write operation that either inserts a new object -with a given primary key or updates an existing object that already has -that primary key. We call this an upsert because it is an "**update** or -**insert**" operation. This is useful when an object may or may not -already exist, such as when bulk importing a dataset into an existing -realm. Upserting lets you update existing entries while adding any new entries. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/api-not-supported-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-or-update-object-java-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-or-update-object-kotlin-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst - -.. include:: /includes/sdk-examples/crud/create-or-update-object.rst - -.. _sdks-create-objects-from-json: - -Create Objects from JSON -~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. _sdks-create-objects-with-value: - -Initialize Objects with a Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -.. _sdks-create-copy-object-to-another-database: - -Copy an Object to Another Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. _sdks-create-special-property-types: Create Special Property Types @@ -692,6 +768,21 @@ Create a Counter Property Type Create a Timestamp Property Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _sdks-create-object-id-property-type: + +Create an Object ID Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-create-uuid-property-type: + +Create a UUID Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _flutter-create-Uint8List-property-type: + +Create a Uint8List Property Type (Dart) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. _sdks-create-collection-property-types: Create Collection Property Types From 71d87308cc96df636ca6527ebfd6c65e650d206a Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 09:45:16 -0400 Subject: [PATCH 10/37] Add details about initializing objects with a value --- ...ze-objects-with-value-no-dedicated-api.rst | 3 + ...tialize-objects-with-value-description.rst | 12 +++ ...tialize-objects-with-value-description.rst | 12 +++ .../create-initialize-objects-with-value.rst | 74 +++++++++++++++++++ source/sdk/crud/create.txt | 67 +++++++++++++++++ 5 files changed, 168 insertions(+) create mode 100644 source/includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst create mode 100644 source/includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst create mode 100644 source/includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst create mode 100644 source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst diff --git a/source/includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst b/source/includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst new file mode 100644 index 0000000000..93993034c6 --- /dev/null +++ b/source/includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst @@ -0,0 +1,3 @@ +This SDK does not provide specialized methods to initialize objects with +a value. Instead, use standard language features to create objects with +initial values, or set the values after creating an object. diff --git a/source/includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst b/source/includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst new file mode 100644 index 0000000000..d780446174 --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst @@ -0,0 +1,12 @@ +You can initialize an object by passing an initializer value to +:objc-sdk:`RLMObject initWithValue +`. +The initializer value can be a :apple:`key-value coding +` +compliant object, a dictionary, or an array containing one element for +each managed property. + +.. note:: + + When using an array as an initializer value, you must include all + properties in the same order as they are defined in the model. diff --git a/source/includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst b/source/includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst new file mode 100644 index 0000000000..ae31fdce02 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst @@ -0,0 +1,12 @@ +You can initialize an object by passing an initializer value to +:swift-sdk:`Object.init(value:) +`. +The initializer value can be a :apple:`key-value coding +` +compliant object, a dictionary, or an array containing one element for +each managed property. + +.. note:: + + When using an array as an initializer value, you must include all + properties in the same order as they are defined in the model. diff --git a/source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst b/source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst new file mode 100644 index 0000000000..7b97b86286 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst @@ -0,0 +1,74 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ReadWriteData.snippet.initialize-objects-with-values.m + :language: objectivec + + You can even initialize related or embedded objects by nesting + initializer values: + + .. literalinclude:: /examples/generated/code/start/ReadWriteData.snippet.nested-objects.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/CreateRealmObjects.snippet.initialize-objects-with-values.swift + :language: swift + + You can even initialize related or embedded objects by nesting + initializer values: + + .. literalinclude:: /examples/generated/code/start/CreateRealmObjects.snippet.nested-objects.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 5715870414..f6c1caa949 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -299,6 +299,73 @@ realm. Upserting lets you update existing entries while adding any new entries. Initialize Objects with a Value ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some of the SDKs provide specific methods to initialize objects with a value. +Others use language-idiomatic methods to set the values of objects during +initialization. + +Some Property Types are Only Mutable in a Write Transaction +``````````````````````````````````````````````````````````` + +Some property types are only mutable in a write transaction. For example, +you can instantiate an object with a :ref:`Set ` +property, but you can only set that property's value in a write transaction. +You cannot initialize the object with a value for that property unless +you do so inside a write transaction. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + +.. include:: /includes/sdk-examples/crud/create-initialize-objects-with-value.rst + .. _sdks-create-objects-from-json: Create Objects from JSON From 4d3a074e269ca6445e3743f041c1d7f3617e4689 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 10:06:09 -0400 Subject: [PATCH 11/37] Add details for creating objects from JSON --- ...eate-objects-from-json-missing-example.rst | 2 + .../create-objects-from-json-description.rst | 11 +++ .../create-objects-from-json-description.rst | 29 ++++++++ .../create-objects-from-json-description.rst | 28 ++++++++ .../crud/create-objects-from-json.rst | 64 +++++++++++++++++ source/sdk/crud/create.txt | 69 ++++++++++++++++--- 6 files changed, 195 insertions(+), 8 deletions(-) create mode 100644 source/includes/api-details/generic/crud/create-objects-from-json-missing-example.rst create mode 100644 source/includes/api-details/java/crud/create-objects-from-json-description.rst create mode 100644 source/includes/api-details/objectivec/crud/create-objects-from-json-description.rst create mode 100644 source/includes/api-details/swift/crud/create-objects-from-json-description.rst create mode 100644 source/includes/sdk-examples/crud/create-objects-from-json.rst diff --git a/source/includes/api-details/generic/crud/create-objects-from-json-missing-example.rst b/source/includes/api-details/generic/crud/create-objects-from-json-missing-example.rst new file mode 100644 index 0000000000..dc245dc40c --- /dev/null +++ b/source/includes/api-details/generic/crud/create-objects-from-json-missing-example.rst @@ -0,0 +1,2 @@ +This language is currently missing an example of how to create objects from +JSON. diff --git a/source/includes/api-details/java/crud/create-objects-from-json-description.rst b/source/includes/api-details/java/crud/create-objects-from-json-description.rst new file mode 100644 index 0000000000..f1a10612cb --- /dev/null +++ b/source/includes/api-details/java/crud/create-objects-from-json-description.rst @@ -0,0 +1,11 @@ +You can insert objects into the database from JSON. The SDK +supports creating objects from ``String``, +:android:`JSONObject `, and +:android:`InputStream ` types. +The SDK ignores any properties present in the JSON that are +not defined in the SDK object schema. + +The following example demonstrates how to create a single object from JSON with +:java-sdk:`createObjectFromJson() ` +or multiple objects from JSON with +:java-sdk:`createAllFromJson() `: diff --git a/source/includes/api-details/objectivec/crud/create-objects-from-json-description.rst b/source/includes/api-details/objectivec/crud/create-objects-from-json-description.rst new file mode 100644 index 0000000000..e7aa85b1a5 --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-objects-from-json-description.rst @@ -0,0 +1,29 @@ +The SDK does not directly support JSON, but you can use +:apple:`NSJSONSerialization +` to +convert JSON into a value that you can pass to +:objc-sdk:`RLMObject createInRealm(withValue:) +`. + +Nested objects or arrays in the JSON map to to-one or to-many relationships. + +The JSON property names and types must match the destination +:ref:`object model ` exactly. For example: + +- ``float`` properties must be initialized with float-backed ``NSNumbers``. +- ``Date`` and ``Data`` properties cannot be inferred from strings. Convert + them to the appropriate type before passing to + :objc-sdk:`RLMObject createInRealm(withValue:) + `. +- Required properties cannot be ``null`` or missing in the JSON. + +The SDK ignores any properties in the JSON not defined in the +object schema. + +.. tip:: + + If your JSON schema doesn't exactly align with your SDK objects, + consider using a third-party framework to transform your JSON. There + are many model mapping frameworks that work with the SDK. + See a :github:`partial list in the realm-swift repository + `. diff --git a/source/includes/api-details/swift/crud/create-objects-from-json-description.rst b/source/includes/api-details/swift/crud/create-objects-from-json-description.rst new file mode 100644 index 0000000000..8dd19cf33c --- /dev/null +++ b/source/includes/api-details/swift/crud/create-objects-from-json-description.rst @@ -0,0 +1,28 @@ +The SDK does not directly support JSON, but you can use +:apple:`JSONSerialization.jsonObject(with:options:) +` to +convert JSON into a value that you can pass to +:swift-sdk:`Realm.create(_:value:update:) +`. + +Nested objects or arrays in the JSON map to to-one or to-many relationships. + +The JSON property names and types must match the destination +:ref:`object model ` exactly. For example: + +- ``float`` properties must be initialized with float-backed ``NSNumbers``. +- ``Date`` and ``Data`` properties cannot be inferred from strings. Convert + them to the appropriate type before passing to + :swift-sdk:`Realm.create(_:value:update:) `. +- Required properties cannot be ``null`` or missing in the JSON. + +The SDK ignores any properties in the JSON not defined in the +object schema. + +.. tip:: + + If your JSON schema doesn't exactly align with your SDK objects, + consider using a third-party framework to transform your JSON. There + are many model mapping frameworks that work with the SDK. + See a :github:`partial list in the realm-swift repository + `. diff --git a/source/includes/sdk-examples/crud/create-objects-from-json.rst b/source/includes/sdk-examples/crud/create-objects-from-json.rst new file mode 100644 index 0000000000..b6fd5d3332 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-objects-from-json.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.create-an-object-json.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.create-an-object-json.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ReadWriteData.snippet.json.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/CreateRealmObjects.snippet.json.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index f6c1caa949..2deeee38a4 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -317,37 +317,37 @@ you do so inside a write transaction. .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. tab:: :tabid: dart - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. tab:: :tabid: java - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. tab:: :tabid: java-kotlin - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. tab:: :tabid: javascript - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. tab:: :tabid: kotlin - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. tab:: :tabid: objectivec @@ -362,7 +362,7 @@ you do so inside a write transaction. .. tab:: :tabid: typescript - .. include:: /includes/api-details/generic/create-initialize-objects-with-value-no-dedicated-api.rst + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst .. include:: /includes/sdk-examples/crud/create-initialize-objects-with-value.rst @@ -371,6 +371,59 @@ you do so inside a write transaction. Create Objects from JSON ~~~~~~~~~~~~~~~~~~~~~~~~ +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + +.. include:: /includes/sdk-examples/crud/create-objects-from-json.rst .. _sdks-create-unmanaged-copy: From 4c59437e4a9827920d219a3f749ca93df3a4d19c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 11:22:49 -0400 Subject: [PATCH 12/37] Add details about copying a managed object to another instance --- ...-to-another-database-js-ts-description.rst | 6 ++ ...-object-to-another-database-no-example.rst | 2 + ...object-to-another-database-description.rst | 9 +++ ...object-to-another-database-description.rst | 6 ++ ...object-to-another-database-description.rst | 22 +++++++ ...object-to-another-database-description.rst | 10 +++ ...create-copy-object-to-another-database.rst | 63 +++++++++++++++++++ source/sdk/crud/create.txt | 56 +++++++++++++++++ 8 files changed, 174 insertions(+) create mode 100644 source/includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst create mode 100644 source/includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst create mode 100644 source/includes/api-details/java/crud/create-copy-object-to-another-database-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst create mode 100644 source/includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst create mode 100644 source/includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst create mode 100644 source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst diff --git a/source/includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst b/source/includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst new file mode 100644 index 0000000000..a2b0dbf4de --- /dev/null +++ b/source/includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst @@ -0,0 +1,6 @@ +To copy a managed object to another database instance, call the +:js-sdk:`Realm.create() ` method in a write +transaction with the object to copy. You can optionally specify the +:js-sdk:`UpdateMode ` to determine how to handle +copying objects where the target database instance already contains an object +with a matching primary key. diff --git a/source/includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst b/source/includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst new file mode 100644 index 0000000000..a151d89047 --- /dev/null +++ b/source/includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst @@ -0,0 +1,2 @@ +The selected language does not currently have an example of how to copy an +object to another database instance. diff --git a/source/includes/api-details/java/crud/create-copy-object-to-another-database-description.rst b/source/includes/api-details/java/crud/create-copy-object-to-another-database-description.rst new file mode 100644 index 0000000000..cb0c5b3bcb --- /dev/null +++ b/source/includes/api-details/java/crud/create-copy-object-to-another-database-description.rst @@ -0,0 +1,9 @@ +Use :java-sdk:`realm.copyToRealm() ` +in a write transaction to copy a managed object to another database instance. + +Alternately, to copy an object that does not exist, or update an object that +does exist, use :java-sdk:`realm.copyToRealmOrUpdate() +`. This +copies an object where the target database instance does not contain an +object with the same primary key. If the target database instance already +contains an object with a matching primary key, it updates the object. diff --git a/source/includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst b/source/includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst new file mode 100644 index 0000000000..9188d4688d --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst @@ -0,0 +1,6 @@ +You can copy an SDK object to a :kotlin-sdk:`MutableRealm +` instance with the +:kotlin-sdk:`copyToRealm() ` +method. The :kotlin-sdk:`UpdatePolicy ` +you specify determines how to handle copying objects where the target database +instance already contains an object with a matching primary key. diff --git a/source/includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst b/source/includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst new file mode 100644 index 0000000000..e68ca3ee6f --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst @@ -0,0 +1,22 @@ +To copy a managed object to another database instance, call the +:objc-sdk:`RLMObject createOrUpdateInRealm:withValue +` +or :objc-sdk:`RLMObject createOrUpdateModifiedInRealm:withValue +` +method in a write transaction. + +If the object type does not have a primary key, or no object with a matching +primary key exists, this method creates a new object in the target database +instance. + +If an object with a matching primary key already exists in the target +database instance, ``createOrUpdateInRealm`` sets each property defined in its +schema by copying from value using key-value coding. + +Alternately, ``createOrUpdateModifiedInRealm`` only sets values which have +changed. Checking which properties have changed imposes a small amount of +overhead, and so this method may be slower when all or nearly all of the +properties being set have changed. If most or all of the properties being set +have *not* changed, this method is much faster than unconditionally setting +all of them. It also reduces how much data has to be written to the database, +saving both i/o time and disk space. diff --git a/source/includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst b/source/includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst new file mode 100644 index 0000000000..e138aa0352 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst @@ -0,0 +1,10 @@ +To copy a managed object to another database instance, call the +:swift-sdk:`create(value: update:) ` +method in a write transaction. + +If the object type does not have a primary key, or no object with a matching +primary key exists, this method creates a new object in the target database +instance. If an object with a matching primary key already exists in the target +database instance, and you set the :swift-sdk:`update policy +` to ``.modified`` or ``.all``, this method +updates the existing object returns a reference to it. diff --git a/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst b/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst new file mode 100644 index 0000000000..4c0d50178a --- /dev/null +++ b/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: java + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :emphasize-lines: 10, 11 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 2deeee38a4..7b620adcd6 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -493,6 +493,62 @@ currently implemented. Copy an Object to Another Database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can copy objects that are managed by one database instance to another +database instance. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-copy-to-another-database-no-example.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-copy-to-another-database-no-example.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-copy-to-another-database-no-example.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst + +.. include:: /includes/sdk-examples/crud/create-copy-object-to-another-database.rst Create Specific SDK Object Types -------------------------------- From cdc6d0ba5339f6363a7fc4be0b08f9ac4b4daa59 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 13:26:56 -0400 Subject: [PATCH 13/37] Add details about creating a counter property type --- ...te-counter-property-type-not-supported.rst | 1 + ...eate-counter-property-type-description.rst | 23 ++++++ ...te-counter-property-type-not-supported.rst | 1 + ...counter-property-type-java-description.rst | 45 +++++++++++ ...unter-property-type-kotlin-description.rst | 45 +++++++++++ ...te-counter-property-type-not-supported.rst | 1 + ...eate-counter-property-type-description.rst | 12 +++ ...te-counter-property-type-not-supported.rst | 1 + ...te-counter-property-type-not-supported.rst | 1 + ...te-counter-property-type-not-supported.rst | 1 + .../crud/create-asymmetric-object-model.rst | 2 +- .../crud/create-asymmetric-object.rst | 2 +- ...create-copy-object-to-another-database.rst | 3 +- .../crud/create-counter-property-type.rst | 64 ++++++++++++++++ source/sdk/crud/create.txt | 76 +++++++++++++++++-- source/sdk/model-data/supported-types.txt | 5 ++ 16 files changed, 273 insertions(+), 10 deletions(-) create mode 100644 source/includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst create mode 100644 source/includes/api-details/csharp/crud/create-counter-property-type-description.rst create mode 100644 source/includes/api-details/dart/crud/create-counter-property-type-not-supported.rst create mode 100644 source/includes/api-details/java/crud/create-counter-property-type-java-description.rst create mode 100644 source/includes/api-details/java/crud/create-counter-property-type-kotlin-description.rst create mode 100644 source/includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst create mode 100644 source/includes/api-details/kotlin/crud/create-counter-property-type-description.rst create mode 100644 source/includes/api-details/objectivec/crud/create-counter-property-type-not-supported.rst create mode 100644 source/includes/api-details/swift/crud/create-counter-property-type-not-supported.rst create mode 100644 source/includes/api-details/typescript/crud/create-counter-property-type-not-supported.rst create mode 100644 source/includes/sdk-examples/crud/create-counter-property-type.rst diff --git a/source/includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst b/source/includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst new file mode 100644 index 0000000000..eb8e4befcc --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst @@ -0,0 +1 @@ +The C++ SDK does not currently provide a dedicated counter property type. diff --git a/source/includes/api-details/csharp/crud/create-counter-property-type-description.rst b/source/includes/api-details/csharp/crud/create-counter-property-type-description.rst new file mode 100644 index 0000000000..a8548584c6 --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-counter-property-type-description.rst @@ -0,0 +1,23 @@ +Traditionally, you would implement a counter by reading a value, incrementing +it, and then setting it (``myObject.Counter += 1``). This does not work well in +an asynchronous situation like when two clients are offline. Consider +the following scenario: + +- The SDK object has a ``counter`` property of type ``int``. It is currently + set to a value of ``10``. + +- Clients 1 and 2 both read the ``counter`` property (``10``) and each increments + the value by ``1``. + +- When each client regains connectivity and merges their changes, they expect a + value of 11, and there is no conflict. However, the counter value should be + ``12``! + +When using a ``RealmInteger``, however, you can call the ``Increment()`` and +``Decrement()`` methods, and to reset the counter, you set it to ``0``, just as +you would an ``int``. + +.. important:: + + When you reset a ``RealmInteger``, you may run into the offline merge issue + described above. diff --git a/source/includes/api-details/dart/crud/create-counter-property-type-not-supported.rst b/source/includes/api-details/dart/crud/create-counter-property-type-not-supported.rst new file mode 100644 index 0000000000..7e0c63c17d --- /dev/null +++ b/source/includes/api-details/dart/crud/create-counter-property-type-not-supported.rst @@ -0,0 +1 @@ +The Flutter SDK does not currently provide a dedicated counter property type. diff --git a/source/includes/api-details/java/crud/create-counter-property-type-java-description.rst b/source/includes/api-details/java/crud/create-counter-property-type-java-description.rst new file mode 100644 index 0000000000..c1fdc88044 --- /dev/null +++ b/source/includes/api-details/java/crud/create-counter-property-type-java-description.rst @@ -0,0 +1,45 @@ +Typically, incrementing or decrementing a +``byte``, ``short``, ``int``, or ``long`` field of a Realm +object looks something like this: + +1. Read the current value of the field. +#. Update that value in memory to a new value based on the increment or + decrement. +#. Write a new value back to the field. + +When multiple distributed clients attempt this at the same time, +updates reaching clients in different orders can +result in different values on different clients. ``MutableRealmInteger`` +improves on this by translating numeric updates into sync operations +that can be executed in any order to converge to the same value. + +The :java-sdk:`counter.increment() ` +and :java-sdk:`counter.decrement() ` +operators ensure that increments and decrements from multiple distributed +clients are aggregated correctly. + +To change a :java-sdk:`MutableRealmInteger +` value, call ``increment()`` or +``decrement()`` within a write transaction. + +You can assign a ``MutableRealmInteger`` a new value with a call to +:java-sdk:`counter.set() ` +within a write transaction. + +.. warning:: Counter Resets + + Use the ``set()`` operator with extreme care. ``set()`` ignores + the effects of any prior calls to ``increment()`` or ``decrement()``. + Although the value of a ``MutableRealmInteger`` always converges + across devices, the specific value on which it converges depends on + the actual order in which operations took place. + Mixing ``set()`` with ``increment()`` and ``decrement()`` is + not advised unless fuzzy counting is acceptable. + +.. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-set.java + :language: java + :copyable: false + +Since ``MutableRealmInteger`` instances retain a reference to their +parent object, neither object can be garbage collected while you still +retain a reference to the ``MutableRealmInteger``. diff --git a/source/includes/api-details/java/crud/create-counter-property-type-kotlin-description.rst b/source/includes/api-details/java/crud/create-counter-property-type-kotlin-description.rst new file mode 100644 index 0000000000..1b68339a80 --- /dev/null +++ b/source/includes/api-details/java/crud/create-counter-property-type-kotlin-description.rst @@ -0,0 +1,45 @@ +Typically, incrementing or decrementing a +``byte``, ``short``, ``int``, or ``long`` field of a Realm +object looks something like this: + +1. Read the current value of the field. +#. Update that value in memory to a new value based on the increment or + decrement. +#. Write a new value back to the field. + +When multiple distributed clients attempt this at the same time, +updates reaching clients in different orders can +result in different values on different clients. ``MutableRealmInteger`` +improves on this by translating numeric updates into sync operations +that can be executed in any order to converge to the same value. + +The :java-sdk:`counter.increment() ` +and :java-sdk:`counter.decrement() ` +operators ensure that increments and decrements from multiple distributed +clients are aggregated correctly. + +To change a :java-sdk:`MutableRealmInteger +` value, call ``increment()`` or +``decrement()`` within a write transaction. + +You can assign a ``MutableRealmInteger`` a new value with a call to +:java-sdk:`counter.set() ` +within a write transaction. + +.. warning:: Counter Resets + + Use the ``set()`` operator with extreme care. ``set()`` ignores + the effects of any prior calls to ``increment()`` or ``decrement()``. + Although the value of a ``MutableRealmInteger`` always converges + across devices, the specific value on which it converges depends on + the actual order in which operations took place. + Mixing ``set()`` with ``increment()`` and ``decrement()`` is + not advised unless fuzzy counting is acceptable. + +.. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-set.kt + :language: kotlin + :copyable: false + +Since ``MutableRealmInteger`` instances retain a reference to their +parent object, neither object can be garbage collected while you still +retain a reference to the ``MutableRealmInteger``. diff --git a/source/includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst b/source/includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst new file mode 100644 index 0000000000..08187be898 --- /dev/null +++ b/source/includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst @@ -0,0 +1 @@ +JavaScript does not currently have a dedicated counter property type. diff --git a/source/includes/api-details/kotlin/crud/create-counter-property-type-description.rst b/source/includes/api-details/kotlin/crud/create-counter-property-type-description.rst new file mode 100644 index 0000000000..6ce690ea06 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-counter-property-type-description.rst @@ -0,0 +1,12 @@ +To create a new object instance with a +:kotlin-sdk:`MutableRealmInt +` +property, instantiate an object and pass an initial value to the +``MutableRealmInt`` property using +:kotlin-sdk:`MutableRealmInt.create() `. +For more information about the ``MutableRealmInt`` type, refer to +:ref:``. + +In the following example, we instantiate a new ``Frog`` object with a +``fliesEaten`` property and pass an initial value to +``MutableRealmInt.create()``: diff --git a/source/includes/api-details/objectivec/crud/create-counter-property-type-not-supported.rst b/source/includes/api-details/objectivec/crud/create-counter-property-type-not-supported.rst new file mode 100644 index 0000000000..c6b0104478 --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-counter-property-type-not-supported.rst @@ -0,0 +1 @@ +The Swift SDK does not currently provide a dedicated counter property type. diff --git a/source/includes/api-details/swift/crud/create-counter-property-type-not-supported.rst b/source/includes/api-details/swift/crud/create-counter-property-type-not-supported.rst new file mode 100644 index 0000000000..c6b0104478 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-counter-property-type-not-supported.rst @@ -0,0 +1 @@ +The Swift SDK does not currently provide a dedicated counter property type. diff --git a/source/includes/api-details/typescript/crud/create-counter-property-type-not-supported.rst b/source/includes/api-details/typescript/crud/create-counter-property-type-not-supported.rst new file mode 100644 index 0000000000..2fddba5e74 --- /dev/null +++ b/source/includes/api-details/typescript/crud/create-counter-property-type-not-supported.rst @@ -0,0 +1 @@ +TypeScript does not currently have a dedicated counter property type. diff --git a/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst b/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst index b2985ee0df..f05116c5e1 100644 --- a/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst +++ b/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst @@ -30,7 +30,7 @@ content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt - :language: java + :language: kotlin - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-asymmetric-object.rst b/source/includes/sdk-examples/crud/create-asymmetric-object.rst index b2c49a8fb2..26bdca8d65 100644 --- a/source/includes/sdk-examples/crud/create-asymmetric-object.rst +++ b/source/includes/sdk-examples/crud/create-asymmetric-object.rst @@ -29,7 +29,7 @@ content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt - :language: java + :language: kotlin - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst b/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst index 4c0d50178a..ea9861cca1 100644 --- a/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst +++ b/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst @@ -29,7 +29,7 @@ content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt - :language: java + :language: kotlin - id: javascript content: | @@ -42,7 +42,6 @@ .. literalinclude:: /examples/MissingPlaceholders/example.kt :language: kotlin - :emphasize-lines: 10, 11 - id: objectivec content: | diff --git a/source/includes/sdk-examples/crud/create-counter-property-type.rst b/source/includes/sdk-examples/crud/create-counter-property-type.rst new file mode 100644 index 0000000000..2e6c0758d6 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-counter-property-type.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/DataTypesSectionExamples.snippet.realmint-use.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-increment-decrement.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-increment-decrement.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-mutablerealm-property.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 7b620adcd6..faf6b28e50 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -501,17 +501,17 @@ database instance. .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/generic/crud/create-copy-to-another-database-no-example.rst + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst .. tab:: :tabid: csharp - .. include:: /includes/api-details/generic/crud/create-copy-to-another-database-no-example.rst + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst .. tab:: :tabid: dart - .. include:: /includes/api-details/generic/crud/create-copy-to-another-database-no-example.rst + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst .. tab:: :tabid: java @@ -536,12 +536,12 @@ database instance. .. tab:: :tabid: objectivec - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-description.rst + .. include:: /includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst .. tab:: :tabid: swift - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-description.rst + .. include:: /includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst .. tab:: :tabid: typescript @@ -554,7 +554,7 @@ Create Specific SDK Object Types -------------------------------- Before you can create a new object and persist it to the database, you must -:ref:`sdks-object-models`. Then, you include that object type in your database +:ref:`sdks-object-models`. Then, include that object type in your database schema when you open the database. .. important:: Object Types Must Be in Your Schema @@ -939,6 +939,63 @@ For a list of the value types that a mixed property can hold, refer to Create a Counter Property Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some of the SDKs provide a special property type you can use as a logical +counter. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-counter-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-counter-property-type-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-counter-property-type-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-counter-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-counter-property-type-not-supported.rst + +.. include:: /includes/sdk-examples/crud/create-counter-property-type.rst + .. _sdks-create-timestamp-property-type: Create a Timestamp Property Type @@ -959,6 +1016,13 @@ Create a UUID Property Type Create a Uint8List Property Type (Dart) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _sdks-create-enum-property-type: + +Create an Enum Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + .. _sdks-create-collection-property-types: Create Collection Property Types diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/supported-types.txt index b686b0722f..e44d65c93c 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/supported-types.txt @@ -26,6 +26,11 @@ Placeholder page for supported data types. Generic (Mixed) Data Type ~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _sdks-counter-data-type: + +Counter Data Type +~~~~~~~~~~~~~~~~~ + .. _sdks-list-property-types: Supported List Property Types From 1d356b2d3f136cd3027fafd223b371751b0a16ec Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 13:51:26 -0400 Subject: [PATCH 14/37] Add details about creating a timestamp property --- ...te-timestamp-property-type-description.rst | 4 ++ ...te-timestamp-property-type-description.rst | 6 ++ ...te-timestamp-property-type-description.rst | 7 +++ ...estamp-property-type-js-ts-description.rst | 2 + ...te-timestamp-property-type-description.rst | 1 + ...te-timestamp-property-type-description.rst | 16 +++++ ...te-timestamp-property-type-description.rst | 1 + ...te-timestamp-property-type-description.rst | 1 + .../crud/create-timestamp-property-type.rst | 62 +++++++++++++++++++ source/sdk/crud/create.txt | 54 ++++++++++++++++ source/sdk/model-data/supported-types.txt | 5 ++ 11 files changed, 159 insertions(+) create mode 100644 source/includes/api-details/cpp/crud/create-timestamp-property-type-description.rst create mode 100644 source/includes/api-details/csharp/crud/create-timestamp-property-type-description.rst create mode 100644 source/includes/api-details/dart/crud/create-timestamp-property-type-description.rst create mode 100644 source/includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst create mode 100644 source/includes/api-details/java/crud/create-timestamp-property-type-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-timestamp-property-type-description.rst create mode 100644 source/includes/api-details/objectivec/crud/create-timestamp-property-type-description.rst create mode 100644 source/includes/api-details/swift/crud/create-timestamp-property-type-description.rst create mode 100644 source/includes/sdk-examples/crud/create-timestamp-property-type.rst diff --git a/source/includes/api-details/cpp/crud/create-timestamp-property-type-description.rst b/source/includes/api-details/cpp/crud/create-timestamp-property-type-description.rst new file mode 100644 index 0000000000..fa2e238356 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-timestamp-property-type-description.rst @@ -0,0 +1,4 @@ +Use the `chrono library +`__ +to store a ``time_point`` relative to the ``system_clock``: +``>`` diff --git a/source/includes/api-details/csharp/crud/create-timestamp-property-type-description.rst b/source/includes/api-details/csharp/crud/create-timestamp-property-type-description.rst new file mode 100644 index 0000000000..0fbac8b5c9 --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-timestamp-property-type-description.rst @@ -0,0 +1,6 @@ +Use ``DateTimeOffset`` to store timestamp data. The SDK converts +``DateTimeOffset`` values to UTC before storing in the database, and does not +store the timezone information. + +See :github:`Issue #1835 ` for more +information. diff --git a/source/includes/api-details/dart/crud/create-timestamp-property-type-description.rst b/source/includes/api-details/dart/crud/create-timestamp-property-type-description.rst new file mode 100644 index 0000000000..cbe7854140 --- /dev/null +++ b/source/includes/api-details/dart/crud/create-timestamp-property-type-description.rst @@ -0,0 +1,7 @@ +Use ``DateTime`` to store timestamp data. + +However, it is important to note that the SDK stores ``DateTime`` in UTC. +When you use ``DateTime``, you must create it in UTC or convert it +with ``.toUtc()`` before you store it. If your application requires it, +you can convert it back to local or the desired time zone when reading +from the database. diff --git a/source/includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst b/source/includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst new file mode 100644 index 0000000000..9969f1b6ea --- /dev/null +++ b/source/includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst @@ -0,0 +1,2 @@ +Use the ``date`` property type to store timestamp data. This maps to the +JavaScript :mdn:`Date ` type. diff --git a/source/includes/api-details/java/crud/create-timestamp-property-type-description.rst b/source/includes/api-details/java/crud/create-timestamp-property-type-description.rst new file mode 100644 index 0000000000..b12cc6d0e5 --- /dev/null +++ b/source/includes/api-details/java/crud/create-timestamp-property-type-description.rst @@ -0,0 +1 @@ +Use the ``Date`` type to store timestamp data. diff --git a/source/includes/api-details/kotlin/crud/create-timestamp-property-type-description.rst b/source/includes/api-details/kotlin/crud/create-timestamp-property-type-description.rst new file mode 100644 index 0000000000..3a4b0c5083 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-timestamp-property-type-description.rst @@ -0,0 +1,16 @@ +To create a new object instance with a +:kotlin-sdk:`RealmInstant +` +property, instantiate an object and pass an initial value to the +``RealmInstant`` property using either: + +- :kotlin-sdk:`RealmInstant.from() `: + the epochSeconds and nanoseconds since the Unix epoch +- :kotlin-sdk:`RealmInstant.now() `: + the epochSeconds and nanoseconds since the Unix epoch until now + +For more information about the ``RealmInstant`` type, refer to +:ref:``. + +In the following example, we instantiate a new ``Frog`` object with a +``birthdate`` property and pass an initial value to ``RealmInstant.from()``: diff --git a/source/includes/api-details/objectivec/crud/create-timestamp-property-type-description.rst b/source/includes/api-details/objectivec/crud/create-timestamp-property-type-description.rst new file mode 100644 index 0000000000..12471da3b6 --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-timestamp-property-type-description.rst @@ -0,0 +1 @@ +Use the Objective-C ``NSDate`` data type to store timestamp data. diff --git a/source/includes/api-details/swift/crud/create-timestamp-property-type-description.rst b/source/includes/api-details/swift/crud/create-timestamp-property-type-description.rst new file mode 100644 index 0000000000..605337cbc4 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-timestamp-property-type-description.rst @@ -0,0 +1 @@ +Use the Swift ``Date`` data type to store timestamp data. diff --git a/source/includes/sdk-examples/crud/create-timestamp-property-type.rst b/source/includes/sdk-examples/crud/create-timestamp-property-type.rst new file mode 100644 index 0000000000..85eff10c22 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-timestamp-property-type.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.datetime-use.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-realminstant-property.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index faf6b28e50..e470e2bc6d 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1001,6 +1001,60 @@ counter. Create a Timestamp Property Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-timestamp-property-type-js-ts-description.rst + +.. include:: /includes/sdk-examples/crud/create-timestamp-property-type.rst + .. _sdks-create-object-id-property-type: Create an Object ID Property Type diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/supported-types.txt index e44d65c93c..797caad059 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/supported-types.txt @@ -31,6 +31,11 @@ Generic (Mixed) Data Type Counter Data Type ~~~~~~~~~~~~~~~~~ +.. _sdks-timestamp-data-type: + +Timestamp Data Type +~~~~~~~~~~~~~~~~~~~ + .. _sdks-list-property-types: Supported List Property Types From 0560132dbe07fde5ff5d5f800a6030d43d9f8ae1 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 14:56:45 -0400 Subject: [PATCH 15/37] Add create Object ID details --- ...te-object-id-property-type-description.rst | 1 + ...te-object-id-property-type-description.rst | 1 + ...te-object-id-property-type-description.rst | 3 + ...ject-id-property-type-java-description.rst | 1 + ...ct-id-property-type-kotlin-description.rst | 1 + ...te-object-id-property-type-description.rst | 1 + ...te-object-id-property-type-description.rst | 1 + .../crud/create-object-id-property-type.rst | 62 +++++++++++++++++++ source/sdk/crud/create.txt | 50 ++++++++++++++- 9 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/crud/create-object-id-property-type-description.rst create mode 100644 source/includes/api-details/csharp/crud/create-object-id-property-type-description.rst create mode 100644 source/includes/api-details/dart/crud/create-object-id-property-type-description.rst create mode 100644 source/includes/api-details/java/crud/create-object-id-property-type-java-description.rst create mode 100644 source/includes/api-details/java/crud/create-object-id-property-type-kotlin-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-object-id-property-type-description.rst create mode 100644 source/includes/api-details/swift/crud/create-object-id-property-type-description.rst create mode 100644 source/includes/sdk-examples/crud/create-object-id-property-type.rst diff --git a/source/includes/api-details/cpp/crud/create-object-id-property-type-description.rst b/source/includes/api-details/cpp/crud/create-object-id-property-type-description.rst new file mode 100644 index 0000000000..5fcb26ad20 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-object-id-property-type-description.rst @@ -0,0 +1 @@ +Create a unique Object ID with ``realm::object_id::generate()``. diff --git a/source/includes/api-details/csharp/crud/create-object-id-property-type-description.rst b/source/includes/api-details/csharp/crud/create-object-id-property-type-description.rst new file mode 100644 index 0000000000..49851f6544 --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-object-id-property-type-description.rst @@ -0,0 +1 @@ +Create a unique Object ID with ``ObjectId.GenerateNewId()``. \ No newline at end of file diff --git a/source/includes/api-details/dart/crud/create-object-id-property-type-description.rst b/source/includes/api-details/dart/crud/create-object-id-property-type-description.rst new file mode 100644 index 0000000000..e3f1b19d70 --- /dev/null +++ b/source/includes/api-details/dart/crud/create-object-id-property-type-description.rst @@ -0,0 +1,3 @@ +Call ``ObjectId()`` to set any unique identifier properties of +your object. Alternatively, pass a string +to ``ObjectId()`` to set the unique identifier property to a specific value. diff --git a/source/includes/api-details/java/crud/create-object-id-property-type-java-description.rst b/source/includes/api-details/java/crud/create-object-id-property-type-java-description.rst new file mode 100644 index 0000000000..e9b2526808 --- /dev/null +++ b/source/includes/api-details/java/crud/create-object-id-property-type-java-description.rst @@ -0,0 +1 @@ +Create a unique Object ID with ``new ObjectId()``. diff --git a/source/includes/api-details/java/crud/create-object-id-property-type-kotlin-description.rst b/source/includes/api-details/java/crud/create-object-id-property-type-kotlin-description.rst new file mode 100644 index 0000000000..2b7541ff1a --- /dev/null +++ b/source/includes/api-details/java/crud/create-object-id-property-type-kotlin-description.rst @@ -0,0 +1 @@ +Create a unique Object ID with ``ObjectId()``. diff --git a/source/includes/api-details/kotlin/crud/create-object-id-property-type-description.rst b/source/includes/api-details/kotlin/crud/create-object-id-property-type-description.rst new file mode 100644 index 0000000000..0713a0ca45 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-object-id-property-type-description.rst @@ -0,0 +1 @@ +You can initialize an ``ObjectId`` using ``ObjectId()``. \ No newline at end of file diff --git a/source/includes/api-details/swift/crud/create-object-id-property-type-description.rst b/source/includes/api-details/swift/crud/create-object-id-property-type-description.rst new file mode 100644 index 0000000000..e95a915bdb --- /dev/null +++ b/source/includes/api-details/swift/crud/create-object-id-property-type-description.rst @@ -0,0 +1 @@ +Create a unique Object ID with ``ObjectId.generate()``. \ No newline at end of file diff --git a/source/includes/sdk-examples/crud/create-object-id-property-type.rst b/source/includes/sdk-examples/crud/create-object-id-property-type.rst new file mode 100644 index 0000000000..5c89b1e8b4 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-object-id-property-type.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.objectid-use.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index e470e2bc6d..08f4f12776 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1051,7 +1051,7 @@ Create a Timestamp Property Type .. tab:: :tabid: typescript - .. include:: /includes/api-details/typescript/crud/create-timestamp-property-type-js-ts-description.rst + .. include:: /includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst .. include:: /includes/sdk-examples/crud/create-timestamp-property-type.rst @@ -1060,6 +1060,54 @@ Create a Timestamp Property Type Create an Object ID Property Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-object-id-property-type-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-object-id-property-type-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-object-id-property-type.rst + .. _sdks-create-uuid-property-type: Create a UUID Property Type From e1c959c56d6becee7e1a5833f0e3254601c0f17d Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 15:52:36 -0400 Subject: [PATCH 16/37] Add details about creating a UUID property type --- .../create-uuid-property-type-description.rst | 2 + .../create-uuid-property-type-description.rst | 3 + ...e-uuid-property-type-js-ts-description.rst | 3 + .../create-uuid-property-type-description.rst | 4 ++ ...te-object-id-property-type-description.rst | 4 +- .../create-uuid-property-type-description.rst | 1 + .../crud/create-uuid-property-type.rst | 62 +++++++++++++++++++ source/sdk/crud/create.txt | 42 +++++++++++++ 8 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/crud/create-uuid-property-type-description.rst create mode 100644 source/includes/api-details/dart/crud/create-uuid-property-type-description.rst create mode 100644 source/includes/api-details/generic/crud/create-uuid-property-type-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-uuid-property-type-description.rst create mode 100644 source/includes/api-details/swift/crud/create-uuid-property-type-description.rst create mode 100644 source/includes/sdk-examples/crud/create-uuid-property-type.rst diff --git a/source/includes/api-details/cpp/crud/create-uuid-property-type-description.rst b/source/includes/api-details/cpp/crud/create-uuid-property-type-description.rst new file mode 100644 index 0000000000..c2733a7bf6 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-uuid-property-type-description.rst @@ -0,0 +1,2 @@ +You can create a UUID with ``realm::uuid()``. Or you can initialize a UUID +with a specific value, similar to ``realm::uuid("18de7916-7f84-11ec-a8a3-0242ac120002")``. diff --git a/source/includes/api-details/dart/crud/create-uuid-property-type-description.rst b/source/includes/api-details/dart/crud/create-uuid-property-type-description.rst new file mode 100644 index 0000000000..84b3799cbd --- /dev/null +++ b/source/includes/api-details/dart/crud/create-uuid-property-type-description.rst @@ -0,0 +1,3 @@ +To set any unique identifier properties of +your object to a random value, call one of the ``Uuid`` methods to create a UUID, +such as ``Uuid.v4()``. diff --git a/source/includes/api-details/generic/crud/create-uuid-property-type-js-ts-description.rst b/source/includes/api-details/generic/crud/create-uuid-property-type-js-ts-description.rst new file mode 100644 index 0000000000..c2dc948a4d --- /dev/null +++ b/source/includes/api-details/generic/crud/create-uuid-property-type-js-ts-description.rst @@ -0,0 +1,3 @@ +To set any unique identifier properties of +your object to a random value, call ``new UUID()``. Alternatively, pass a string +to ``new UUID()`` to set the unique identifier property to a specific value. diff --git a/source/includes/api-details/kotlin/crud/create-uuid-property-type-description.rst b/source/includes/api-details/kotlin/crud/create-uuid-property-type-description.rst new file mode 100644 index 0000000000..356d3b31e3 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-uuid-property-type-description.rst @@ -0,0 +1,4 @@ +You can generate a random ``RealmUUID`` using :kotlin-sdk:`RealmUUID.random() +` +or pass a UUID-formatted string to :kotlin-sdk:`RealmUUID.from() +`: diff --git a/source/includes/api-details/swift/crud/create-object-id-property-type-description.rst b/source/includes/api-details/swift/crud/create-object-id-property-type-description.rst index e95a915bdb..9e44589357 100644 --- a/source/includes/api-details/swift/crud/create-object-id-property-type-description.rst +++ b/source/includes/api-details/swift/crud/create-object-id-property-type-description.rst @@ -1 +1,3 @@ -Create a unique Object ID with ``ObjectId.generate()``. \ No newline at end of file +To create a random Object ID, call ``ObjectId.generate()``. + +To create a zero-initialized Object ID, call ``ObjectId()``. \ No newline at end of file diff --git a/source/includes/api-details/swift/crud/create-uuid-property-type-description.rst b/source/includes/api-details/swift/crud/create-uuid-property-type-description.rst new file mode 100644 index 0000000000..3e1c75ebc5 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-uuid-property-type-description.rst @@ -0,0 +1 @@ +You can create a UUID with ``UUID()``. diff --git a/source/includes/sdk-examples/crud/create-uuid-property-type.rst b/source/includes/sdk-examples/crud/create-uuid-property-type.rst new file mode 100644 index 0000000000..fa168dd756 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-uuid-property-type.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.uuid-use.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/data-types.snippet.work-with-uuid.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.create-uuid.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 08f4f12776..bbd38cb45d 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1113,6 +1113,48 @@ Create an Object ID Property Type Create a UUID Property Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-uuid-property-type.rst + .. _flutter-create-Uint8List-property-type: Create a Uint8List Property Type (Dart) From e83a7fad871d3ef2e15375f909b528b32f5d2e6c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 16:55:12 -0400 Subject: [PATCH 17/37] Add create set property details --- .../crud/create-set-property-description.rst | 5 + .../create-set-properties-description.rst | 5 + .../create-set-properties-description.rst | 4 + .../create-set-properties-description.rst | 16 +++ .../create-set-properties-description.rst | 4 + .../create-set-properties-description.rst | 4 + .../sdk-examples/crud/create-set-property.rst | 62 ++++++++++++ source/sdk/crud/create.txt | 99 +++++++++++++++---- source/sdk/model-data/supported-types.txt | 21 ++++ 9 files changed, 200 insertions(+), 20 deletions(-) create mode 100644 source/includes/api-details/cpp/crud/create-set-property-description.rst create mode 100644 source/includes/api-details/java/crud/create-set-properties-description.rst create mode 100644 source/includes/api-details/javascript/crud/create-set-properties-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-set-properties-description.rst create mode 100644 source/includes/api-details/objectivec/crud/create-set-properties-description.rst create mode 100644 source/includes/api-details/swift/crud/create-set-properties-description.rst create mode 100644 source/includes/sdk-examples/crud/create-set-property.rst diff --git a/source/includes/api-details/cpp/crud/create-set-property-description.rst b/source/includes/api-details/cpp/crud/create-set-property-description.rst new file mode 100644 index 0000000000..f061b140ce --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-set-property-description.rst @@ -0,0 +1,5 @@ +You can create objects that contain +:cpp-sdk:`set ` +properties as you would any SDK object, but you can only mutate a set +property within a write transaction. This means you can only set the value(s) +of a set property within a write transaction. diff --git a/source/includes/api-details/java/crud/create-set-properties-description.rst b/source/includes/api-details/java/crud/create-set-properties-description.rst new file mode 100644 index 0000000000..d76c203b82 --- /dev/null +++ b/source/includes/api-details/java/crud/create-set-properties-description.rst @@ -0,0 +1,5 @@ +Add an object to a ``RealmSet`` with +:java-sdk:`RealmSet.add() `. + +Add multiple objects with +:java-sdk:`RealmSet.addAll() `. diff --git a/source/includes/api-details/javascript/crud/create-set-properties-description.rst b/source/includes/api-details/javascript/crud/create-set-properties-description.rst new file mode 100644 index 0000000000..4f6574ce74 --- /dev/null +++ b/source/includes/api-details/javascript/crud/create-set-properties-description.rst @@ -0,0 +1,4 @@ +To create an object with a **Realm Set** property, you must create +the object within a write transaction. When defining your Realm +object, initialize the **Realm Set** by passing an empty array or an +array with your initial values. diff --git a/source/includes/api-details/kotlin/crud/create-set-properties-description.rst b/source/includes/api-details/kotlin/crud/create-set-properties-description.rst new file mode 100644 index 0000000000..e7b7956327 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-set-properties-description.rst @@ -0,0 +1,16 @@ +To create a new object instance with a +:kotlin-sdk:`RealmSet ` +property, instantiate an object and pass any values of a +supported type to the ``RealmSet`` property. + +You can instantiate an unmanaged set with +:kotlin-sdk:`realmSetOf() ` +or pass elements to the set using +:kotlin-sdk:`set.add() ` +or +:kotlin-sdk:`set.addAll() `. +The set is unmanaged until you copy it to the database. + +In the following example, we instantiate a new ``Frog`` object with +initial values for ``favoriteSnacks`` and ``favoriteWeather`` set +properties: diff --git a/source/includes/api-details/objectivec/crud/create-set-properties-description.rst b/source/includes/api-details/objectivec/crud/create-set-properties-description.rst new file mode 100644 index 0000000000..44589bcf6b --- /dev/null +++ b/source/includes/api-details/objectivec/crud/create-set-properties-description.rst @@ -0,0 +1,4 @@ +You can create objects that contain :objc-sdk:`RLMSet +` properties as you would any SDK object, but you +can only mutate an ``RLMSet`` within a write transaction. This means you can +only set the value(s) of a set property within a write transaction. diff --git a/source/includes/api-details/swift/crud/create-set-properties-description.rst b/source/includes/api-details/swift/crud/create-set-properties-description.rst new file mode 100644 index 0000000000..cde6c80533 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-set-properties-description.rst @@ -0,0 +1,4 @@ +You can create objects that contain :swift-sdk:`MutableSet +` properties as you would any SDK object, but you +can only mutate a ``MutableSet`` within a write transaction. This means you can +only set the value(s) of a set property within a write transaction. diff --git a/source/includes/sdk-examples/crud/create-set-property.rst b/source/includes/sdk-examples/crud/create-set-property.rst new file mode 100644 index 0000000000..8eb739aba9 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-set-property.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.write-set-object.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/data-types.snippet.create-set-objects.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-realm-set.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/CreateRealmObjects.snippet.set-collections.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index bbd38cb45d..59c61b069b 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1155,18 +1155,6 @@ Create a UUID Property Type .. include:: /includes/sdk-examples/crud/create-uuid-property-type.rst -.. _flutter-create-Uint8List-property-type: - -Create a Uint8List Property Type (Dart) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. _sdks-create-enum-property-type: - -Create an Enum Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - .. _sdks-create-collection-property-types: Create Collection Property Types @@ -1178,14 +1166,7 @@ The SDK provides a few collection type properties: - Set - Map -Collections are mutable: you can add and remove elements in a collection -within a write transaction. - -Collections can contain both managed and unmanaged objects. When -you copy a collection to the database, you create a managed instance of the -collection *and* all elements in the collection, including any -unmanaged elements. Unmanaged collections behave like their corresponding -language classes and are not persisted to the database. +Collections are mutable within a write transaction. .. tip:: Listen for Changes to a Created Collection @@ -1198,6 +1179,10 @@ language classes and are not persisted to the database. Create List Properties ~~~~~~~~~~~~~~~~~~~~~~ +The SDK's list data type is a container that holds a collection of primitive +values or objects. These values may be of any supported type except another +collection. + The SDK uses the List container type to define to-many relationships. A **to-many** relationship means that an object is related in a specific way to multiple objects. @@ -1255,11 +1240,85 @@ For a list of the value types that a list property can hold, refer to .. include:: /includes/sdk-examples/crud/create-list-property.rst +.. _flutter-create-Uint8List-property-type: + +Create a Uint8List Property Type (Dart) +``````````````````````````````````````` + +The Flutter SDK provides a ``Uint8List`` from Dart. For more details about +defining a ``Uint8List`` type, refer to +:ref:`dart-define-uint8list-property-type`. + +To add ``Uint8List`` to a Realm object, call ``Uint8List.fromList()`` on the data. + +.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.binary-from-list.dart + :language: dart + .. _sdks-create-set-properties: Create Set Properties ~~~~~~~~~~~~~~~~~~~~~ +Like their native counterparts, the SDK's set data type stores unique values. +These values may be of any supported type except another collection. + +The SDK uses the Set container type to define to-many relationships. A +**to-many** relationship means that an object is related in a specific +way to multiple objects. + +For a list of the value types that a set property can hold, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-set-property-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-set-properties-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-set-properties-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-set-properties-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-set-properties-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-set-properties-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/crud/create-set-properties-description.rst + +.. include:: /includes/sdk-examples/crud/create-set-property.rst + .. _sdks-create-dictionary-properties: Create Dictionary Properties diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/supported-types.txt index 797caad059..98238ea4b9 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/supported-types.txt @@ -40,3 +40,24 @@ Timestamp Data Type Supported List Property Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _dart-define-uint8list-property-type: + +Define a Uint8List Property Type (Dart) +``````````````````````````````````````` + +`Uint8List `__ +is a binary data type from `dart:typed_data +`__. +You can use this data type in object models and property values. + +To define a property as ``Uint8List``, you must first import ``dart:typed_data``. +Then, set the object's type as ``Uint8List`` in your object model. + +.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.binary-model.dart + :language: dart + +.. _sdks-set-property-types: + +Supported Set Property Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 00345a2a840fb47dcff9fa76ef6f2a7df1bfdc0d Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 17:16:14 -0400 Subject: [PATCH 18/37] Add create dictionary property details --- ...create-dictionary-property-description.rst | 11 ++++ ...e-dictionary-property-java-description.rst | 5 ++ ...dictionary-property-kotlin-description.rst | 5 ++ ...create-dictionary-property-description.rst | 2 + .../create-set-properties-description.rst | 2 +- ...create-dictionary-property-description.rst | 22 +++++++ ...create-dictionary-property-description.rst | 10 +++ .../crud/create-dictionary-property.rst | 62 +++++++++++++++++++ source/sdk/crud/create.txt | 53 ++++++++++++++++ source/sdk/model-data/supported-types.txt | 7 +++ 10 files changed, 178 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/crud/create-dictionary-property-description.rst create mode 100644 source/includes/api-details/java/crud/create-dictionary-property-java-description.rst create mode 100644 source/includes/api-details/java/crud/create-dictionary-property-kotlin-description.rst create mode 100644 source/includes/api-details/javascript/crud/create-dictionary-property-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-dictionary-property-description.rst create mode 100644 source/includes/api-details/swift/crud/create-dictionary-property-description.rst create mode 100644 source/includes/sdk-examples/crud/create-dictionary-property.rst diff --git a/source/includes/api-details/cpp/crud/create-dictionary-property-description.rst b/source/includes/api-details/cpp/crud/create-dictionary-property-description.rst new file mode 100644 index 0000000000..095176083d --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-dictionary-property-description.rst @@ -0,0 +1,11 @@ +When you create an object that has a +:cpp-sdk:`map property `, +you can set the values for keys in a few ways: + +- Set keys and values on the object and then add the object to the database +- Set the object's keys and values directly inside a write transaction + +.. include:: /includes/map-key-string-limitations.rst + +.. literalinclude:: /examples/generated/cpp/crud.snippet.percent-encode-disallowed-characters.cpp + :language: cpp diff --git a/source/includes/api-details/java/crud/create-dictionary-property-java-description.rst b/source/includes/api-details/java/crud/create-dictionary-property-java-description.rst new file mode 100644 index 0000000000..3140a8648c --- /dev/null +++ b/source/includes/api-details/java/crud/create-dictionary-property-java-description.rst @@ -0,0 +1,5 @@ +Add an object to a ``RealmDictionary`` with +:java-sdk:`put() `. + +Add multiple objects to a ``RealmDictionary`` with +:java-sdk:`putAll() `. diff --git a/source/includes/api-details/java/crud/create-dictionary-property-kotlin-description.rst b/source/includes/api-details/java/crud/create-dictionary-property-kotlin-description.rst new file mode 100644 index 0000000000..7cb2f5c9bb --- /dev/null +++ b/source/includes/api-details/java/crud/create-dictionary-property-kotlin-description.rst @@ -0,0 +1,5 @@ +Add an object to a ``RealmDictionary`` with +:java-sdk:`put() ` (or the ``[]`` operator). + +Add multiple objects to a ``RealmDictionary`` with +:java-sdk:`putAll() `. diff --git a/source/includes/api-details/javascript/crud/create-dictionary-property-description.rst b/source/includes/api-details/javascript/crud/create-dictionary-property-description.rst new file mode 100644 index 0000000000..290eb9079b --- /dev/null +++ b/source/includes/api-details/javascript/crud/create-dictionary-property-description.rst @@ -0,0 +1,2 @@ +Create an object with a dictionary value by running the :js-sdk:`realm.create() +` method within a write transaction. diff --git a/source/includes/api-details/javascript/crud/create-set-properties-description.rst b/source/includes/api-details/javascript/crud/create-set-properties-description.rst index 4f6574ce74..c0ef2d772d 100644 --- a/source/includes/api-details/javascript/crud/create-set-properties-description.rst +++ b/source/includes/api-details/javascript/crud/create-set-properties-description.rst @@ -1,4 +1,4 @@ To create an object with a **Realm Set** property, you must create -the object within a write transaction. When defining your Realm +the object within a write transaction. When defining your SDK object, initialize the **Realm Set** by passing an empty array or an array with your initial values. diff --git a/source/includes/api-details/kotlin/crud/create-dictionary-property-description.rst b/source/includes/api-details/kotlin/crud/create-dictionary-property-description.rst new file mode 100644 index 0000000000..918bb09cec --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-dictionary-property-description.rst @@ -0,0 +1,22 @@ +To create a new object instance with a +:kotlin-sdk:`RealmDictionary ` +property, instantiate an object and pass any key-value pairs of a +supported type to the ``RealmDictionary`` property. + +You can instantiate an unmanaged dictionary with +:kotlin-sdk:`realmDictionaryOf() ` +or +:kotlin-sdk:`realmDictionaryEntryOf() `. +Or you can pass key-values using +:kotlin-sdk:`put() ` +or +:kotlin-sdk:`putAll() `. +The dictionary is unmanaged until you copy it to the database. + +.. include:: /includes/map-key-string-limitations.rst + +.. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.percent-encode-disallowed-characters.kt + :language: kotlin + +In the following example, we instantiate a new ``Frog`` object with +initial key-values for several dictionary properties: diff --git a/source/includes/api-details/swift/crud/create-dictionary-property-description.rst b/source/includes/api-details/swift/crud/create-dictionary-property-description.rst new file mode 100644 index 0000000000..ab30067903 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-dictionary-property-description.rst @@ -0,0 +1,10 @@ +When you create an object that has a :swift-sdk:`map property +`, you can set the values for keys in a few ways: + +- Set keys and values on the object and then add the object to the realm +- Set the object's keys and values directly inside a write transaction +- Use key-value coding to set or update keys and values inside a write transaction + +.. include:: /includes/map-key-string-limitations.rst + +.. literalinclude:: /examples/generated/code/start/CreateRealmObjects.snippet.percent-encode-disallowed-map-keys.swift diff --git a/source/includes/sdk-examples/crud/create-dictionary-property.rst b/source/includes/sdk-examples/crud/create-dictionary-property.rst new file mode 100644 index 0000000000..0bf5258739 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-dictionary-property.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.create-map-object.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/data-types.snippet.create-realm-obj-with-dictionary.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-dictionary.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/CreateRealmObjects.snippet.map.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 59c61b069b..eac22469bb 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1324,6 +1324,59 @@ For a list of the value types that a set property can hold, refer to Create Dictionary Properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The SDK supports a dictionary (map) property type. Dictionary keys must be +strings, but values can be any of the supported value types. For a list of the +value types that a dictionary property can hold, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-dictionary-property-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-dictionary-property-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/crud/create-dictionary-property-description.rst + +.. include:: /includes/sdk-examples/crud/create-dictionary-property.rst + .. _sdks-create-relationship-property-types: Create Relationship Property Types diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/supported-types.txt index 98238ea4b9..0d67e2f1ae 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/supported-types.txt @@ -61,3 +61,10 @@ Then, set the object's type as ``Uint8List`` in your object model. Supported Set Property Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-dictionary-property-types: + +Supported Dictionary Property Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + From 437558d263cd51d00da5d1ab066a430417605e73 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 17:43:22 -0400 Subject: [PATCH 19/37] Add create relationship property details --- ...reate-inverse-relationship-description.rst | 11 ++ ...reate-to-many-relationship-description.rst | 23 +++ ...create-to-one-relationship-description.rst | 14 ++ ...reate-inverse-relationship-description.rst | 2 + ...reate-to-many-relationship-description.rst | 4 + ...create-to-one-relationship-description.rst | 3 + .../crud/create-inverse-relationship.rst | 62 +++++++ .../crud/create-to-many-relationship.rst | 62 +++++++ .../crud/create-to-one-relationship.rst | 62 +++++++ source/sdk/crud/create.txt | 155 ++++++++++++++++++ source/sdk/crud/update.txt | 5 + source/sdk/model-data/relationships.txt | 17 +- 12 files changed, 419 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/cpp/crud/create-inverse-relationship-description.rst create mode 100644 source/includes/api-details/cpp/crud/create-to-many-relationship-description.rst create mode 100644 source/includes/api-details/cpp/crud/create-to-one-relationship-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-inverse-relationship-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-to-many-relationship-description.rst create mode 100644 source/includes/api-details/kotlin/crud/create-to-one-relationship-description.rst create mode 100644 source/includes/sdk-examples/crud/create-inverse-relationship.rst create mode 100644 source/includes/sdk-examples/crud/create-to-many-relationship.rst create mode 100644 source/includes/sdk-examples/crud/create-to-one-relationship.rst diff --git a/source/includes/api-details/cpp/crud/create-inverse-relationship-description.rst b/source/includes/api-details/cpp/crud/create-inverse-relationship-description.rst new file mode 100644 index 0000000000..0bbfb9db40 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-inverse-relationship-description.rst @@ -0,0 +1,11 @@ +To create an object with a inverse relationship to another object, +assign the raw pointer of the related object to the relationship +property of the main object. Move the object into the realm using the +:cpp-sdk:`Realm.add() function ` +inside of a write transaction. + +In this example, we create two ``Person`` objects that each have a to-one +relationship to the same ``Dog`` object. The ``Dog`` has an inverse +relationship to each ``Person`` object. The inverse relationship backlink +is automatically updated when a linked ``Person`` object updates its +``Dog`` relationship. diff --git a/source/includes/api-details/cpp/crud/create-to-many-relationship-description.rst b/source/includes/api-details/cpp/crud/create-to-many-relationship-description.rst new file mode 100644 index 0000000000..10e8989f1f --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-to-many-relationship-description.rst @@ -0,0 +1,23 @@ +To create an object with a to-many relationship to one or more objects: + +- Initialize the main object and the related objects +- Use the :cpp-sdk:`push_back + ` + member function available to the Realm object lists + to append the raw pointers of the related objects to the main object's + list property +- Move the object into the realm using the + :cpp-sdk:`Realm.add() function ` + inside of a write transaction. + +In this example, we append the raw pointers of the related objects - +``Employee *`` - to the relationship property of the main object +- ``Company.employees``. This creates a one-way connection from the +``Company`` object to the ``Employee`` objects. + +Then, we add the ``Company`` to the realm. This copies the +``Company`` and ``Employee`` objects to the realm. + +The related ``Employee`` objects have their own lifecycle independent +of the main ``Company`` object. If you delete the main object, the +related objects remain. diff --git a/source/includes/api-details/cpp/crud/create-to-one-relationship-description.rst b/source/includes/api-details/cpp/crud/create-to-one-relationship-description.rst new file mode 100644 index 0000000000..eb228792f4 --- /dev/null +++ b/source/includes/api-details/cpp/crud/create-to-one-relationship-description.rst @@ -0,0 +1,14 @@ +To create an object with a to-one relationship to another object, +assign the raw pointer of the related object to the relationship +property of the main object. Move the object into the database using +the :cpp-sdk:`Realm.add() function ` +inside of a write transaction. + +In this example, we assign the raw pointer of the related object - +``FavoriteToy *`` - to the relationship property of the main object +- ``Dog.favoriteToy``. Then, when we add the ``dog`` object to the +database, this copies both the ``dog`` and ``favoriteToy`` to the database. + +The related ``favoriteToy`` object has its own lifecycle independent +of the main ``dog`` object. If you delete the main object, the related +object remains. diff --git a/source/includes/api-details/kotlin/crud/create-inverse-relationship-description.rst b/source/includes/api-details/kotlin/crud/create-inverse-relationship-description.rst new file mode 100644 index 0000000000..d8eb42c7df --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-inverse-relationship-description.rst @@ -0,0 +1,2 @@ +In the following example, we instantiate a new ``User`` object with a +backlinks ``posts`` property that references a list of ``Post`` objects: diff --git a/source/includes/api-details/kotlin/crud/create-to-many-relationship-description.rst b/source/includes/api-details/kotlin/crud/create-to-many-relationship-description.rst new file mode 100644 index 0000000000..471013560f --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-to-many-relationship-description.rst @@ -0,0 +1,4 @@ +In the following example, we instantiate a new ``Forest`` object with a +``frogsThatLiveHere`` property that references a set of ``Frog`` +objects and a ``nearByPonds`` property that references a list of +``Pond`` objects: diff --git a/source/includes/api-details/kotlin/crud/create-to-one-relationship-description.rst b/source/includes/api-details/kotlin/crud/create-to-one-relationship-description.rst new file mode 100644 index 0000000000..ca46321695 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/create-to-one-relationship-description.rst @@ -0,0 +1,3 @@ +In the following example, we instantiate a new ``Frog`` object with a +``favoritePond`` property that references a ``Pond`` object and a +``bestFriend`` property that references another ``Frog`` object: diff --git a/source/includes/sdk-examples/crud/create-inverse-relationship.rst b/source/includes/sdk-examples/crud/create-inverse-relationship.rst new file mode 100644 index 0000000000..afb2c9e763 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-inverse-relationship.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/relationships.snippet.create-inverse-relationship.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-inverse-realm-relationship.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/crud/create-to-many-relationship.rst b/source/includes/sdk-examples/crud/create-to-many-relationship.rst new file mode 100644 index 0000000000..bdaf66e034 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-to-many-relationship.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/relationships.snippet.create-to-many-relationship.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-to-many-realm-relationship.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/crud/create-to-one-relationship.rst b/source/includes/sdk-examples/crud/create-to-one-relationship.rst new file mode 100644 index 0000000000..4d8901ff19 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-to-one-relationship.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/relationships.snippet.create-to-one-relationship.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/CreateTest.snippet.create-to-one-realm-relationship.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index eac22469bb..516cc39f4c 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1382,13 +1382,168 @@ value types that a dictionary property can hold, refer to Create Relationship Property Types ---------------------------------- +When you have properties whose type references another SDK object, this creates +a relationship between the objects. This can be a to-one, to-many, or +inverse relationship. For more information about relationships, refer to +:ref:`sdks-relationships`. + +.. _sdks-create-to-one-relationship: + Create a To-One Relationship ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To create a new object instance with a +:ref:`to-one relationship ` +property, instantiate both objects and pass the referenced object to the +relationship property. + +You can optionally create an inverse relationship to refer to the main object +from the related object. For more information, refer to the +:ref:`sdks-create-object-with-inverse-relationship` section on this page. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-to-one-relationship-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-to-one-relationship-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-to-one-relationship.rst + +.. _sdks-create-to-many-relationship: + Create a To-Many Relationship ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To create a new object instance with a +:ref:`to-many relationship ` +property, instantiate all objects and pass any referenced objects to the +relationship collection property. + +You may use a List or a Set to represent a to-many relationship, depending +on whether you require the values to be unique, or whether you want to use any +of the special collection type methods. + +You can optionally create an inverse relationship to refer to the main object +from the related object. For more information, refer to the +:ref:`sdks-create-object-with-inverse-relationship` section on this page. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-to-many-relationship.rst + .. _sdks-create-object-with-inverse-relationship: Create an Inverse Relationship ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a new object instance with an +:ref:`inverse relationship ` +property, instantiate the parent object and pass any referenced child +objects to the inverse relationship property. + +After you create an object that has an inverse relationship, you can access +the inverse relationship property to get the child objects. However, you +*cannot* directly modify the backlink itself. For more information, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-inverse-relationship.rst diff --git a/source/sdk/crud/update.txt b/source/sdk/crud/update.txt index 992cc009e0..2f17611c34 100644 --- a/source/sdk/crud/update.txt +++ b/source/sdk/crud/update.txt @@ -11,3 +11,8 @@ Update Objects :class: singlecol Placeholder page for content related to updating realm objects. + +.. _sdks-update-inverse-relationships: + +Update Inverse Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/model-data/relationships.txt b/source/sdk/model-data/relationships.txt index 94ab2460f7..71153db99e 100644 --- a/source/sdk/model-data/relationships.txt +++ b/source/sdk/model-data/relationships.txt @@ -10,4 +10,19 @@ Model Relationships :depth: 3 :class: singlecol -Placeholder page for modeling relationships in the SDKs. \ No newline at end of file +Placeholder page for modeling relationships in the SDKs. + +.. _sdks-to-one-relationship: + +To-One Relationship +------------------- + +.. _sdks-to-many-relationship: + +To-Many Relationship +-------------------- + +.. _sdks-inverse-relationship: + +Inverse Relationship +-------------------- From 30911957550ec5f9b288c48d73bb707bcbef1108 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 17:47:51 -0400 Subject: [PATCH 20/37] Fix snooty build error --- source/sdk/crud/create.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 516cc39f4c..c25f1d6454 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1501,7 +1501,7 @@ Create an Inverse Relationship ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To create a new object instance with an -:ref:`inverse relationship ` +:ref:`inverse relationship ` property, instantiate the parent object and pass any referenced child objects to the inverse relationship property. From 3b47dff8f3d41660ea6fce7283e72429114a7c6c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 18:11:27 -0400 Subject: [PATCH 21/37] Add details about creating objects in the background --- ...eate-objects-in-background-description.rst | 3 + ...eate-objects-in-background-description.rst | 6 ++ ...eate-objects-in-background-description.rst | 102 ++++++++++++++++++ .../crud/create-objects-in-background.rst | 62 +++++++++++ source/sdk/crud/create.txt | 50 +++++++++ 5 files changed, 223 insertions(+) create mode 100644 source/includes/api-details/csharp/crud/create-objects-in-background-description.rst create mode 100644 source/includes/api-details/dart/crud/create-objects-in-background-description.rst create mode 100644 source/includes/api-details/swift/crud/create-objects-in-background-description.rst create mode 100644 source/includes/sdk-examples/crud/create-objects-in-background.rst diff --git a/source/includes/api-details/csharp/crud/create-objects-in-background-description.rst b/source/includes/api-details/csharp/crud/create-objects-in-background-description.rst new file mode 100644 index 0000000000..af2c1f306f --- /dev/null +++ b/source/includes/api-details/csharp/crud/create-objects-in-background-description.rst @@ -0,0 +1,3 @@ +Open a write transaction with the +or :dotnet-sdk:`Realm.WriteAsync() ` +method to avoid blocking the UI thread. diff --git a/source/includes/api-details/dart/crud/create-objects-in-background-description.rst b/source/includes/api-details/dart/crud/create-objects-in-background-description.rst new file mode 100644 index 0000000000..005bc54f1b --- /dev/null +++ b/source/includes/api-details/dart/crud/create-objects-in-background-description.rst @@ -0,0 +1,6 @@ +You can add, modify, or delete objects asynchronously using +:flutter-sdk:`Realm.writeAsync() `. + +When you use ``Realm.writeAsync()`` to perform write operations, waiting +to obtain the write lock and committing a transaction occur in the background. +Only the write itself occurs on the main process. diff --git a/source/includes/api-details/swift/crud/create-objects-in-background-description.rst b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst new file mode 100644 index 0000000000..c05ec0fd38 --- /dev/null +++ b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst @@ -0,0 +1,102 @@ +**Use the Background Write API** + +You can add, modify, or delete objects in the background using +:swift-sdk:`writeAsync `. + +With ``writeAsync``, you don't need to pass a :ref:`thread-safe reference +` or :ref:`frozen objects ` +across threads. Instead, call ``realm.writeAsync``. You can provide +a completion block for the method to execute on the source thread after +the write completes or fails. + +Things to consider when performing background writes: + +- Async writes block closing or invalidating the realm +- You can explicitly commit or cancel transactions + +Wait for Async Writes to Complete +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SDK provides a ``Bool`` to signal whether the database is currently +performing an async write. The +:swift-sdk:`isPerformingAsynchronousWriteOperations +` +variable becomes ``true`` after a call to one of: + +- ``writeAsync`` +- ``beginAsyncWrite`` +- ``commitAsyncWrite`` + +It remains true until all scheduled async write operations have completed. +While this is true, this blocks closing or :swift-sdk:`invalidating +` the database. + +Commit or Cancel an Async Write +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To complete an async write, you or the SDK must call either: + +- :swift-sdk:`commitAsyncWrite ` +- :swift-sdk:`cancelAsyncWrite ` + +When you use the ``writeAsync`` method, the SDK handles committing or +canceling the transaction. This provides the convenience of the async write +without the need to manually keep state tied to the scope of the object. +However, while in the ``writeAsync`` block, you *can* explicitly call +``commitAsyncWrite`` or ``cancelAsyncWrite``. If you return without +calling one of these methods, ``writeAsync`` either: + +- Commits the write after executing the instructions in the write block +- Returns an error + +In either case, this completes the ``writeAsync`` operation. + +For more control over when to commit or cancel the async write transaction, +use the ``beginAsyncWrite`` method. When you use this method, you must +explicitly commit the transactions. Returning without committing an async +write cancels the transaction. ``beginAsyncWrite`` returns an ID that you +can pass to ``cancelAsyncWrite``. + +``commitAsyncWrite`` asynchronously commits a write transaction. This is +the step that persists the data to the database. ``commitAsyncWrite`` can +take an ``onComplete`` block. This block executes on the source thread +once the commit completes or fails with an error. + +Calling ``commitAsyncWrite`` immediately returns. This allows the caller +to proceed while the SDK performs the I/O on a background thread. This method +returns an ID that you can pass to ``cancelAsyncWrite``. This cancels the +pending invocation of the completion block. It does not cancel the commit +itself. + +You can group sequential calls to ``commitAsyncWrite``. Batching these calls +improves write performance; particularly when the batched transactions are +small. To permit grouping transactions, set the ``isGroupingAllowed`` +parameter to ``true``. + +You can call ``cancelAsyncWrite`` on either ``beginAsyncWrite`` or +``commitAsyncWrite``. When you call it on ``beginAsyncWrite``, this cancels +the entire write transaction. When you call it on ``commitAsyncWrite``, this +cancels only an ``onComplete`` block you may have passed to +``commitAsyncWrite``. It does not cancel the commit itself. You need the ID +of the ``beginAsyncWrite`` or the ``commitAsyncWrite`` you want to cancel. + +**Use Swift Concurrency Features** + +You can use Swift concurrency features to write asynchronously to an +actor-isolated database. + +This function from the example ``RealmActor`` :ref:`defined on the +Use Realm with Actors page ` shows how you might +write to an actor-isolated database: + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.write-async.swift + :language: swift + +And you might perform this write using Swift's async syntax: + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-isolated-realm-async.swift + :language: swift + +This operation does not block or perform I/O on the calling thread. For +more information about writing to realm using Swift concurrency features, +refer to :ref:`swift-actor-isolated-realm`. diff --git a/source/includes/sdk-examples/crud/create-objects-in-background.rst b/source/includes/sdk-examples/crud/create-objects-in-background.rst new file mode 100644 index 0000000000..70a5bfaa48 --- /dev/null +++ b/source/includes/sdk-examples/crud/create-objects-in-background.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/QuickStartExamples.snippet.create.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/read_write_data_test.snippet.write-async.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/UpdateRealmObjects.snippet.async-transaction.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index c25f1d6454..f7bd20a619 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -550,6 +550,56 @@ database instance. .. include:: /includes/sdk-examples/crud/create-copy-object-to-another-database.rst +.. _sdks-create-objects-in-background: + +Create Objects in the Background +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When performing large write operations, you may want to create objects in the +background. This avoids blocking the UI thread while performing large write +operations. This is particularly useful when using Device Sync, where you don't +know when and for how long the Sync client will be writing. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-objects-in-background.rst + Create Specific SDK Object Types -------------------------------- From bc519afd213f38470c5e4548e8c34da74afac45c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 23 May 2024 18:23:20 -0400 Subject: [PATCH 22/37] Add Swift Concurrency and Use Realm with Actors to new Apple platform directory --- ...eate-objects-in-background-description.rst | 15 +- source/platforms/apple.txt | 6 + source/platforms/apple/swift-concurrency.txt | 224 ++++++++++++ .../platforms/apple/use-realm-with-actors.txt | 344 ++++++++++++++++++ source/sdk/crud/threading.txt | 10 + 5 files changed, 598 insertions(+), 1 deletion(-) create mode 100644 source/platforms/apple/swift-concurrency.txt create mode 100644 source/platforms/apple/use-realm-with-actors.txt diff --git a/source/includes/api-details/swift/crud/create-objects-in-background-description.rst b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst index c05ec0fd38..6a7266ceb8 100644 --- a/source/includes/api-details/swift/crud/create-objects-in-background-description.rst +++ b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst @@ -4,7 +4,7 @@ You can add, modify, or delete objects in the background using :swift-sdk:`writeAsync `. With ``writeAsync``, you don't need to pass a :ref:`thread-safe reference -` or :ref:`frozen objects ` +` or :ref:`frozen objects ` across threads. Instead, call ``realm.writeAsync``. You can provide a completion block for the method to execute on the source thread after the write completes or fails. @@ -82,6 +82,8 @@ of the ``beginAsyncWrite`` or the ``commitAsyncWrite`` you want to cancel. **Use Swift Concurrency Features** +*Write to an Actor-Isolated Realm* + You can use Swift concurrency features to write asynchronously to an actor-isolated database. @@ -100,3 +102,14 @@ And you might perform this write using Swift's async syntax: This operation does not block or perform I/O on the calling thread. For more information about writing to realm using Swift concurrency features, refer to :ref:`swift-actor-isolated-realm`. + +*Perform Writes using Async/Await Syntax* + +The :swift-sdk:`asyncWrite() ` +API allows for performing async writes using Swift async/await syntax. + +The ``asyncWrite()`` API suspends the calling task while waiting for its +turn to write rather than blocking the thread. In addition, the actual +I/O to write data to disk is done by a background worker thread. For small +writes, using this function on the main thread may block the main thread +for less time than manually dispatching the write to a background thread. diff --git a/source/platforms/apple.txt b/source/platforms/apple.txt index 67aae62a10..b4e1bcc893 100644 --- a/source/platforms/apple.txt +++ b/source/platforms/apple.txt @@ -10,6 +10,12 @@ Build for Apple :depth: 2 :class: singlecol +.. toctree:: + :titlesonly: + + Swift Concurrency + Use Realm with Actors + Placeholder page for information about building for Apple. Include info about which frameworks we support building for Apple, plus diff --git a/source/platforms/apple/swift-concurrency.txt b/source/platforms/apple/swift-concurrency.txt new file mode 100644 index 0000000000..986b38cd8c --- /dev/null +++ b/source/platforms/apple/swift-concurrency.txt @@ -0,0 +1,224 @@ +.. _swift-concurrency: + +============================= +Swift Concurrency - Swift SDK +============================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Swift's concurrency system provides built-in support for writing asynchronous +and parallel code in a structured way. For a detailed overview of the +Swift concurrency system, refer to the `Swift Programming Language Concurrency +topic `__. + +While the considerations on this page broadly apply to using realm with +Swift concurrency features, Realm Swift SDK version 10.39.0 adds support +for using Realm with Swift Actors. You can use Realm isolated to a single +actor or use Realm across actors. + +Realm's actor support simplifies using Realm in a MainActor and background actor +context, and supersedes much of the advice on this page regarding concurrency +considerations. For more information, refer to :ref:`swift-actor-isolated-realm`. + +Realm Concurrency Caveats +------------------------- + +As you implement concurrency features in your app, consider this caveat +about Realm's threading model and Swift concurrency threading behaviors. + +.. _swift-suspend-execution-with-await: + +Suspending Execution with Await +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Anywhere you use the Swift keyword ``await`` marks a possible suspension +point in the execution of your code. With Swift 5.7, once your code suspends, +subsequent code might not execute on the same thread. This means that +anywhere you use ``await`` in your code, the subsequent code could be +executed on a different thread than the code that precedes or follows it. + +This is inherently incompatible with Realm's :ref:`live object paradigm +`. Live objects, collections, and realm instances are +**thread-confined**: that is, they are only valid on the thread on which +they were created. Practically speaking, this means you cannot pass live +instances to other threads. However, Realm offers several +mechanisms for :ref:`sharing objects across threads +`. These mechanisms typically require +your code to do some explicit handling to safely pass data across threads. + +You can use some of these mechanisms, such as :ref:`frozen objects +` or the :ref:`ThreadSafeReference +`, to safely use Realm objects and instances +across threads with the ``await`` keyword. You can also avoid +threading-related issues by marking any asynchronous Realm code with +``@MainActor`` to ensure your apps always execute this code on the main +thread. + +As a general rule, keep in mind that using Realm in an ``await`` context +*without* incorporating threading protection may yield inconsistent behavior. +Sometimes, the code may succeed. In other cases, it may throw an error +related to writing on an incorrect thread. + +.. _swift-async-await-apis: + +Async/Await APIs +---------------- + +Many Realm Swift APIs that involve working with :ref:`an Atlas App +Services app ` or a :ref:`synchronized realm +` are compatible with Swift's async/await syntax. For +examples, check out: + +- :ref:`Async/Await Login ` +- :ref:`Manage Email/Password Users ` +- :ref:`Link User Identities - Async/Await ` +- :ref:`Open a Synced Realm ` or a + :ref:`local realm ` +- :ref:`Await notifications from another actor ` +- :ref:`Manage Flexible Sync Subscriptions ` +- :ref:`Async/Await Call a Serverless Function ` +- :ref:`Async/Await Query MongoDB ` +- :ref:`Async/Await CRUD operations ` + +If you have specific feature requests related to Swift async/await APIs, +check out the `MongoDB Feedback Engine for Realm +`_. The Realm Swift SDK +team plans to continue to develop concurrency-related features based on +community feedback and Swift concurrency evolution. + +.. _swift-perform-background-writes: + +Perform Background Writes +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A commonly-requested use case for asynchronous code is to perform write +operations in the background without blocking the main thread. + +Realm has two APIs that allow for performing asynchronous writes: + +- The :swift-sdk:`writeAsync() ` + API allows for performing async writes using Swift completion handlers. +- The :swift-sdk:`asyncWrite() ` + API allows for performing async writes using Swift async/await syntax. + +Both of these APIs allow you to add, update, or delete objects in the +background without using frozen objects or passing a thread-safe reference. + +With the ``writeAsync()`` API, waiting to obtain the write lock and +committing a transaction occur in the background. The write block itself +runs on the calling thread. This provides thread-safety without requiring +you to manually handle frozen objects or passing references across threads. + +However, while the write block itself is executed, this does block new +transactions on the calling thread. This means that a large write using +the ``writeAsync()`` API could block small, quick writes while it executes. + +The ``asyncWrite()`` API suspends the calling task while waiting for its +turn to write rather than blocking the thread. In addition, the actual +I/O to write data to disk is done by a background worker thread. For small +writes, using this function on the main thread may block the main thread +for less time than manually dispatching the write to a background thread. + +For more information, including code examples, refer to: :ref:`ios-async-write`. + +Tasks and TaskGroups +-------------------- + +Swift concurrency provides APIs to manage :apple:`Tasks ` +and :apple:`TaskGroups `. The `Swift concurrency +documentation `__ +defines a task as a unit of work that can be run asynchronously as part of +your program. Task allows you to specificially define a unit of asynchronous +work. TaskGroup lets you define a collection of Tasks to execute as a unit +under the parent TaskGroup. + +Tasks and TaskGroups provide the ability to yield the thread to other +important work or to cancel a long-running task that could be blocking +other operations. To get these benefits, you might be tempted to use Tasks +and TaskGroups to manage realm writes in the background. + +However, the thread-confined constraints described in :ref:`Suspending +Execution with Await ` above apply in +the Task context. If your Task contains ``await`` points, subsequent code +might run or resume on a different thread and violate Realm's thread confinement. + +You must annotate functions that you run in a Task context with ``@MainActor`` +to ensure code that accesses Realm only runs on the main thread. This negates +some of the benefits of using Tasks, and may mean this is not a good design +choice for apps that use Realm unless you are using Tasks solely for +networking activities like managing users. + +Actor Isolation +--------------- + +.. seealso:: Use Realm with Swift Actors + + The information in this section is applicable to Realm SDK versions earlier + than 10.39.0. Starting in Realm Swift SDK version 10.39.0 and newer, + the SDK supports using Realm with Swift Actors and related async functionality. + + For more information, refer to :ref:`swift-actor-isolated-realm`. + +Actor isolation provides the perception of confining Realm access to a +dedicated actor, and therefore seems like a safe way to manage Realm +access in an asynchronous context. + +However, using Realm in a non-``@MainActor`` async function is currently +not supported. + +In Swift 5.6, this would often work by coincidence. Execution after an +``await`` would continue on whatever thread the awaited thing ran on. +Using ``await Realm()`` in an async function would result in the code +following that running on the main thread until your next call to an +actor-isolated function. + +Swift 5.7 instead hops threads whenever changing actor isolation contexts. +An unisolated async function always runs on a background thread instead. + +If you have code which uses ``await Realm()`` and works in 5.6, marking +the function as ``@MainActor`` will make it work with Swift 5.7. It will +function how it did - unintentionally - in 5.6. + +Errors Related to Concurrency Code +---------------------------------- + +Most often, the error you see related to accessing Realm through concurrency +code is ``Realm accessed from incorrect thread.`` This is due to the +thread-isolation issues described on this page. + +To avoid threading-related issues in code that uses Swift concurrency features: + +- Upgrade to a version of the Realm Swift SDK that supports actor-isolated realms, + and use this as an alternative to manually managing threading. For more + information, refer to :ref:`swift-actor-isolated-realm`. +- Do not change execution contexts when accessing a realm. If you open a realm + on the main thread to provide data for your UI, annotate subsequent functions + where you access the realm asynchronously with ``@MainActor`` to ensure it + always runs on the main thread. Remember that ``await`` marks a suspension + point that could change to a different thread. +- Apps that do not use actor-isolated realms can use the ``writeAsync`` API to + :ref:`perform a background write `. This manages realm + access in a thread-safe way without requiring you to write specialized code + to do it yourself. This is a special API that outsources aspects of the + write process - where it is safe to do so - to run in an async context. + Unless you are writing to an actor-isolated realm, you do not use this + method with Swift's ``async/await`` syntax. Use this method synchronously + in your code. Alternately, you can use the ``asyncWrite`` API with Swift's + ``async/await`` syntax when awaiting writes to asynchronous realms. +- If you want to explicitly write concurrency code that is not actor-isolated + where accessing a realm is done in a thread-safe way, you can explicitly + :ref:`pass instances across threads ` where + applicable to avoid threading-related crashes. This does require a good + understanding of Realm's threading model, as well as being mindful of + Swift concurrency threading behaviors. + +.. _concurrency-page-sendable-thread-confined-reference: + +Sendable, Non-Sendable and Thread-Confined Types +------------------------------------------------ + +.. include:: /includes/swift-api-sendable-thread-confined-reference.rst diff --git a/source/platforms/apple/use-realm-with-actors.txt b/source/platforms/apple/use-realm-with-actors.txt new file mode 100644 index 0000000000..456bd027a3 --- /dev/null +++ b/source/platforms/apple/use-realm-with-actors.txt @@ -0,0 +1,344 @@ +.. _swift-actor-isolated-realm: +.. _swift-use-realm-with-actors: + +================================= +Use Realm with Actors - Swift SDK +================================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Starting with Realm Swift SDK version 10.39.0, Realm supports built-in +functionality for using Realm with Swift Actors. Realm's actor support +provides an alternative to managing threads or dispatch queues to perform +asynchronous work. You can use Realm with actors in a few different ways: + +- Work with realm *only* on a specific actor with an actor-isolated realm +- Use Realm across actors based on the needs of your application + +You might want to use an actor-isolated realm if you want to restrict all +realm access to a single actor. This negates the need to pass data across +the actor boundary, and can simplify data race debugging. + +You might want to use realms across actors in cases where you want to +perform different types of work on different actors. For example, you might +want to read objects on the MainActor but use a background actor for large +writes. + +For general information about Swift actors, refer to :apple:`Apple's Actor +documentation `. + +Prerequisites +------------- + +To use Realm in a Swift actor, your project must: + +- Use Realm Swift SDK version 10.39.0 or later +- Use Swift 5.8/Xcode 14.3 + +In addition, we strongly recommend enabling these settings in your project: + +- ``SWIFT_STRICT_CONCURRENCY=complete``: enables strict concurrency checking +- ``OTHER_SWIFT_FLAGS=-Xfrontend-enable-actor-data-race-checks``: enables + runtime actor data-race detection + +About the Examples on This Page +------------------------------- + +The examples on this page use the following model: + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.model.swift + :language: swift + +.. _swift-open-actor-confined-realm: + +Open an Actor-Isolated Realm +---------------------------- + +You can use the Swift async/await syntax to await opening a realm. + +Initializing a realm with ``try await Realm()`` opens a MainActor-isolated +realm. Alternately, you can explicitly specify an actor when opening a +realm with the ``await`` syntax. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.await-main-actor-realm.swift + :language: swift + +You can specify a default configuration or customize your configuration when +opening an actor-isolated realm: + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-confined-realm-with-config.swift + :language: swift + +For more general information about configuring a realm, refer to +:ref:`ios-configure-and-open-a-realm`. + +You can open a synced realm as an actor-isolated realm: + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-confined-synced-realm.swift + :language: swift + +For more general information about opening a synced realm, refer to +:ref:`ios-configure-and-open-a-synced-realm`. + +.. _swift-define-realm-actor: + +Define a Custom Realm Actor +--------------------------- + +You can define a specific actor to manage Realm in asynchronous contexts. +You can use this actor to manage realm access and perform write operations. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.define-realm-actor.swift + :language: swift + +An actor-isolated realm may be used with either local or global actors. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.global-actor-example.swift + :language: swift + +.. _swift-actor-synchronous-isolated-function: + +Use a Realm Actor Synchronously in an Isolated Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a function is confined to a specific actor, you can use the actor-isolated +realm synchronously. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-isolated-realm-synchronous.swift + :language: swift + +.. _swift-actor-async-nonisolated-function: + +Use a Realm Actor in Async Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a function isn't confined to a specific actor, you can use your Realm actor +with Swift's async/await syntax. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-isolated-realm-async.swift + :language: swift + +.. _swift-write-to-actor-confined-realm: + +Write to an Actor-Isolated Realm +-------------------------------- + +Actor-isolated realms can use Swift async/await syntax for asynchronous +writes. Using ``try await realm.asyncWrite { ... }`` suspends the current task, +acquires the write lock without blocking the current thread, and then invokes +the block. Realm writes the data to disk on a background thread and resumes +the task when that completes. + +This function from the example ``RealmActor`` defined above shows how you might +write to an actor-isolated realm: + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.write-async.swift + :language: swift + +And you might perform this write using Swift's async syntax: + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-isolated-realm-async.swift + :language: swift + +This does not block the calling thread while waiting to write. It does +not perform I/O on the calling thread. For small writes, this is safe to +use from ``@MainActor`` functions without blocking the UI. Writes that +negatively impact your app's performance due to complexity and/or platform +resource constraints may still benefit from being done on a background thread. + +Asynchronous writes are only supported for actor-isolated Realms or in +``@MainActor`` functions. + +.. _swift-realm-cannot-cross-actor-boundary: + +Pass Realm Data Across the Actor Boundary +----------------------------------------- + +Realm objects are not :apple:`Sendable `, +and cannot cross the actor boundary directly. To pass Realm data across +the actor boundary, you have two options: + +- Pass a ``ThreadSafeReference`` to or from the actor +- Pass other types that *are* Sendable, such as passing values directly + or by creating structs to pass across actor boundaries + +.. _swift-pass-thread-safe-reference-across-actors: + +Pass a ThreadSafeReference +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can create a +:swift-sdk:`ThreadSafeReference ` on an +actor where you have access to the object. In this case, we create a +``ThreadSafeReference`` on the ``MainActor``. Then, pass the ``ThreadSafeReference`` to the destination actor. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.pass-tsr-across-actor-boundaries.swift + :language: swift + +On the destination actor, you must ``resolve()`` the reference within a +write transaction before you can use it. This retrieves a version of the +object local to that actor. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.resolve-tsr-on-actor.swift + :language: swift + +.. important:: + + You must resolve a ``ThreadSafeReference`` exactly once. Otherwise, + the source realm remains pinned until the reference gets + deallocated. For this reason, ``ThreadSafeReference`` should be + short-lived. + + If you may need to share the same realm object across actors more than + once, you may prefer to share the :ref:`primary key ` + and :ref:`query for it ` on + the actor where you want to use it. Refer to the "Pass a Primary Key + and Query for the Object on Another Actor" section on this page for an example. + +Pass a Sendable Type +~~~~~~~~~~~~~~~~~~~~ + +While Realm objects are not Sendable, you can work around this by passing +Sendable types across actor boundaries. You can use a few strategies to +pass Sendable types and work with data across actor boundaries: + +- Pass Sendable Realm types or primitive values instead of complete Realm objects +- Pass an object's primary key and query for the object on another actor +- Create a Sendable representation of your Realm object, such as a struct + +Pass Sendable Realm Types and Primitive Values +`````````````````````````````````````````````` + +If you only need a piece of information from the Realm object, such as a +``String`` or ``Int``, you can pass the value directly across actors instead +of passing the Realm object. For a full list of which Realm types are Sendable, +refer to :ref:`concurrency-page-sendable-thread-confined-reference`. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.pass-primitive-data-across-actors.swift + :language: swift + +Pass a Primary Key and Query for the Object on Another Actor +```````````````````````````````````````````````````````````` + +If you want to use a Realm object on another actor, you can share the +:ref:`primary key ` and +:ref:`query for it ` on the actor +where you want to use it. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.query-for-data-on-another-actor.swift + :language: swift + +Create a Sendable Representation of Your Object +``````````````````````````````````````````````` + +If you need to work with more than a simple value, but don't want the +overhead of passing around ``ThreadSafeReferences`` or querying objects on +different actors, you can create a struct or other Sendable representation +of your data to pass across the actor boundary. + +For example, your actor might have a function that creates a struct +representation of the Realm object. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.pass-data-as-struct.swift + :language: swift + +Then, you can call a function to get the data as a struct on another actor. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.get-actor-confined-data-as-struct.swift + :language: swift + +.. _swift-observe-notifications-on-another-actor: + +Observe Notifications on a Different Actor +------------------------------------------ + +You can observe notifications on an actor-isolated realm using Swift's +async/await syntax. + +Calling ``await object.observe(on: Actor)`` or +``await collection.observe(on: Actor)`` registers a block to be called +each time the object or collection changes. + +The SDK asynchronously calls the block on the given actor's executor. + +For write transactions performed on different threads or in different +processes, the SDK calls the block when the realm is (auto)refreshed +to a version including the changes. For local writes, the SDK calls the block +at some point in the future after the write transaction is committed. + +Like :ref:`other Realm notifications `, you can +only observe objects or collections managed by a realm. You must retain the +returned token for as long as you want to watch for updates. + +If you need to manually advance the state of an observed realm on the main +thread or on another actor, call ``await realm.asyncRefresh()``. +This updates the realm and outstanding objects managed by the Realm to point to +the most recent data and deliver any applicable notifications. + +Observation Limitations +~~~~~~~~~~~~~~~~~~~~~~~ + +You *cannot* call the ``.observe()`` method: + +- During a write transaction +- When the containing realm is read-only +- On an actor-confined realm from outside the actor + +.. _swift-actor-collection-change-listener: + +Register a Collection Change Listener +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SDK calls a collection notification block after each write transaction which: + +- Deletes an object from the collection. +- Inserts an object into the collection. +- Modifies any of the managed properties of an object in the collection. This + includes self-assignments that set a property to its existing value. + +.. important:: Order Matters + + In collection notification handlers, always apply changes + in the following order: deletions, insertions, then + modifications. Handling insertions before deletions may + result in unexpected behavior. + +These notifications provide information about the actor on which the change +occurred. Like non-actor-isolated :ref:`collection notifications +`, they also provide +a ``change`` parameter that reports which objects are deleted, added, or +modified during the write transaction. This +:swift-sdk:`RealmCollectionChange ` +resolves to an array of index paths that you can pass to a ``UITableView``'s +batch update methods. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.observe-collection-on-actor.swift + :language: swift + +.. _swift-actor-object-change-listener: + +Register an Object Change Listener +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SDK calls an object notification block after each write transaction which: + +- Deletes the object. +- Modifies any of the managed properties of the object. This includes + self-assignments that set a property to its existing value. + +The block is passed a copy of the object isolated to the requested actor, +along with information about what changed. This object can be safely used +on that actor. + +By default, only direct changes to the object's properties produce notifications. +Changes to linked objects do not produce notifications. If a non-nil, non-empty +keypath array is passed in, only changes to the properties identified by those +keypaths produce change notifications. The keypaths may traverse link +properties to receive information about changes to linked objects. + +.. literalinclude:: /examples/generated/code/start/RealmActor.snippet.observe-object-on-actor.swift + :language: swift diff --git a/source/sdk/crud/threading.txt b/source/sdk/crud/threading.txt index e88063645a..4123a619ed 100644 --- a/source/sdk/crud/threading.txt +++ b/source/sdk/crud/threading.txt @@ -16,3 +16,13 @@ Threading :backlinks: none :depth: 2 :class: singlecol + +.. _sdks-thread-safe-reference: + +Thread-Safe Reference +~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-frozen-objects: + +Frozen Objects +~~~~~~~~~~~~~~ From c8bd56bebdfb2dfcc3bad5601c1382d18a95ad27 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 15:36:28 -0400 Subject: [PATCH 23/37] Update Swift concurrency pages for product naming and updated refs --- ...api-sendable-thread-confined-reference.rst | 2 +- source/platforms/apple.txt | 2 +- source/platforms/apple/swift-concurrency.txt | 153 ++++++++-------- ...ith-actors.txt => use-sdk-with-actors.txt} | 164 ++++++++++-------- source/sdk/crud/create.txt | 12 ++ source/sdk/crud/read.txt | 5 + source/sdk/crud/threading.txt | 5 + source/sdk/files/configure-and-open.txt | 5 + 8 files changed, 202 insertions(+), 146 deletions(-) rename source/platforms/apple/{use-realm-with-actors.txt => use-sdk-with-actors.txt} (66%) diff --git a/source/includes/swift-api-sendable-thread-confined-reference.rst b/source/includes/swift-api-sendable-thread-confined-reference.rst index 1bff9e5e63..5aaffe805f 100644 --- a/source/includes/swift-api-sendable-thread-confined-reference.rst +++ b/source/includes/swift-api-sendable-thread-confined-reference.rst @@ -1,4 +1,4 @@ -The Realm Swift SDK public API contains types that fall into three broad +The Swift SDK public API contains types that fall into three broad categories: - Sendable diff --git a/source/platforms/apple.txt b/source/platforms/apple.txt index b4e1bcc893..df77c1169d 100644 --- a/source/platforms/apple.txt +++ b/source/platforms/apple.txt @@ -14,7 +14,7 @@ Build for Apple :titlesonly: Swift Concurrency - Use Realm with Actors + Use Realm with Actors Placeholder page for information about building for Apple. diff --git a/source/platforms/apple/swift-concurrency.txt b/source/platforms/apple/swift-concurrency.txt index 986b38cd8c..8039cfbe86 100644 --- a/source/platforms/apple/swift-concurrency.txt +++ b/source/platforms/apple/swift-concurrency.txt @@ -4,6 +4,18 @@ Swift Concurrency - Swift SDK ============================= +.. meta:: + :description: Learn how to use Atlas Device SDK with Swift language concurrency features, including which APIs support async/await syntax. + :keywords: Realm, Swift SDK + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: objective-c, swift + .. contents:: On this page :local: :backlinks: none @@ -15,20 +27,21 @@ and parallel code in a structured way. For a detailed overview of the Swift concurrency system, refer to the `Swift Programming Language Concurrency topic `__. -While the considerations on this page broadly apply to using realm with -Swift concurrency features, Realm Swift SDK version 10.39.0 adds support -for using Realm with Swift Actors. You can use Realm isolated to a single -actor or use Realm across actors. +While the considerations on this page broadly apply to using the Swift SDK with +Swift concurrency features, Swift SDK version 10.39.0 adds support +for using the SDK with Swift Actors. You can use the SDK isolated to a single +actor or use the SDK across actors. -Realm's actor support simplifies using Realm in a MainActor and background actor -context, and supersedes much of the advice on this page regarding concurrency -considerations. For more information, refer to :ref:`swift-actor-isolated-realm`. +The SDK's actor support simplifies using the SDK in a MainActor and background +actor context, and supersedes much of the advice on this page regarding +concurrency considerations. For more information, refer to +:ref:`swift-use-sdk-with-actors`. -Realm Concurrency Caveats -------------------------- +SDK Concurrency Caveats +----------------------- As you implement concurrency features in your app, consider this caveat -about Realm's threading model and Swift concurrency threading behaviors. +about the SDK's threading model and Swift concurrency threading behaviors. .. _swift-suspend-execution-with-await: @@ -41,24 +54,24 @@ subsequent code might not execute on the same thread. This means that anywhere you use ``await`` in your code, the subsequent code could be executed on a different thread than the code that precedes or follows it. -This is inherently incompatible with Realm's :ref:`live object paradigm -`. Live objects, collections, and realm instances are -**thread-confined**: that is, they are only valid on the thread on which -they were created. Practically speaking, this means you cannot pass live -instances to other threads. However, Realm offers several +This is inherently incompatible with the SDK's :ref:`live object paradigm +`. Live objects, collections, and database +instances are **thread-confined**: that is, they are only valid on the thread +on which they were created. Practically speaking, this means you cannot pass +live instances to other threads. However, the SDK offers several mechanisms for :ref:`sharing objects across threads -`. These mechanisms typically require +`. These mechanisms typically require your code to do some explicit handling to safely pass data across threads. You can use some of these mechanisms, such as :ref:`frozen objects -` or the :ref:`ThreadSafeReference -`, to safely use Realm objects and instances +` or the :ref:`ThreadSafeReference +`, to safely use SDK objects and instances across threads with the ``await`` keyword. You can also avoid -threading-related issues by marking any asynchronous Realm code with +threading-related issues by marking any asynchronous SDK code with ``@MainActor`` to ensure your apps always execute this code on the main thread. -As a general rule, keep in mind that using Realm in an ``await`` context +As a general rule, keep in mind that using the SDK in an ``await`` context *without* incorporating threading protection may yield inconsistent behavior. Sometimes, the code may succeed. In other cases, it may throw an error related to writing on an incorrect thread. @@ -68,25 +81,25 @@ related to writing on an incorrect thread. Async/Await APIs ---------------- -Many Realm Swift APIs that involve working with :ref:`an Atlas App -Services app ` or a :ref:`synchronized realm -` are compatible with Swift's async/await syntax. For -examples, check out: +Many Swift SDK APIs that involve working with :ref:`an Atlas App +Services app ` or a :ref:`synchronized database +` are compatible with Swift's +async/await syntax. For examples, check out: -- :ref:`Async/Await Login ` -- :ref:`Manage Email/Password Users ` -- :ref:`Link User Identities - Async/Await ` -- :ref:`Open a Synced Realm ` or a - :ref:`local realm ` +- :ref:`Authenticate Users ` +- :ref:`Manage Email/Password Users ` +- :ref:`Link User Identities ` +- :ref:`Open a Synced Database ` or a + :ref:`non-synced database ` - :ref:`Await notifications from another actor ` -- :ref:`Manage Flexible Sync Subscriptions ` -- :ref:`Async/Await Call a Serverless Function ` -- :ref:`Async/Await Query MongoDB ` +- :ref:`Manage Sync Subscriptions ` +- :ref:`Async/Await Call a Serverless Function ` +- :ref:`Async/Await Query MongoDB ` - :ref:`Async/Await CRUD operations ` If you have specific feature requests related to Swift async/await APIs, check out the `MongoDB Feedback Engine for Realm -`_. The Realm Swift SDK +`_. The Swift SDK team plans to continue to develop concurrency-related features based on community feedback and Swift concurrency evolution. @@ -98,7 +111,7 @@ Perform Background Writes A commonly-requested use case for asynchronous code is to perform write operations in the background without blocking the main thread. -Realm has two APIs that allow for performing asynchronous writes: +The SDK has two APIs that allow for performing asynchronous writes: - The :swift-sdk:`writeAsync() ` API allows for performing async writes using Swift completion handlers. @@ -123,7 +136,7 @@ I/O to write data to disk is done by a background worker thread. For small writes, using this function on the main thread may block the main thread for less time than manually dispatching the write to a background thread. -For more information, including code examples, refer to: :ref:`ios-async-write`. +For more information, including code examples, refer to: :ref:`sdks-create-objects-in-background`. Tasks and TaskGroups -------------------- @@ -132,42 +145,43 @@ Swift concurrency provides APIs to manage :apple:`Tasks `. The `Swift concurrency documentation `__ defines a task as a unit of work that can be run asynchronously as part of -your program. Task allows you to specificially define a unit of asynchronous +your program. Task allows you to specifically define a unit of asynchronous work. TaskGroup lets you define a collection of Tasks to execute as a unit under the parent TaskGroup. Tasks and TaskGroups provide the ability to yield the thread to other important work or to cancel a long-running task that could be blocking other operations. To get these benefits, you might be tempted to use Tasks -and TaskGroups to manage realm writes in the background. +and TaskGroups to manage database writes in the background. However, the thread-confined constraints described in :ref:`Suspending Execution with Await ` above apply in the Task context. If your Task contains ``await`` points, subsequent code -might run or resume on a different thread and violate Realm's thread confinement. +might run or resume on a different thread and violate the SDK's thread +confinement. You must annotate functions that you run in a Task context with ``@MainActor`` -to ensure code that accesses Realm only runs on the main thread. This negates -some of the benefits of using Tasks, and may mean this is not a good design -choice for apps that use Realm unless you are using Tasks solely for +to ensure code that accesses the database only runs on the main thread. This +negates some of the benefits of using Tasks, and may mean this is not a good +design choice for apps that use the SDK unless you are using Tasks solely for networking activities like managing users. Actor Isolation --------------- -.. seealso:: Use Realm with Swift Actors +.. seealso:: Use the Swift SDK with Swift Actors - The information in this section is applicable to Realm SDK versions earlier - than 10.39.0. Starting in Realm Swift SDK version 10.39.0 and newer, - the SDK supports using Realm with Swift Actors and related async functionality. + The information in this section is applicable to Swift SDK versions earlier + than 10.39.0. Starting in Swift SDK version 10.39.0 and newer, + the SDK supports using Swift Actors and related async functionality. For more information, refer to :ref:`swift-actor-isolated-realm`. -Actor isolation provides the perception of confining Realm access to a -dedicated actor, and therefore seems like a safe way to manage Realm +Actor isolation provides the perception of confining database access to a +dedicated actor, and therefore seems like a safe way to manage database access in an asynchronous context. -However, using Realm in a non-``@MainActor`` async function is currently +However, using the database in a non-``@MainActor`` async function is currently not supported. In Swift 5.6, this would often work by coincidence. Execution after an @@ -186,34 +200,35 @@ function how it did - unintentionally - in 5.6. Errors Related to Concurrency Code ---------------------------------- -Most often, the error you see related to accessing Realm through concurrency -code is ``Realm accessed from incorrect thread.`` This is due to the -thread-isolation issues described on this page. +Most often, the error you see related to accessing the database through +concurrency code is ``Realm accessed from incorrect thread.`` This is due to +the thread-isolation issues described on this page. To avoid threading-related issues in code that uses Swift concurrency features: -- Upgrade to a version of the Realm Swift SDK that supports actor-isolated realms, +- Upgrade to a version of the Swift SDK that supports actor-isolated databases, and use this as an alternative to manually managing threading. For more information, refer to :ref:`swift-actor-isolated-realm`. -- Do not change execution contexts when accessing a realm. If you open a realm - on the main thread to provide data for your UI, annotate subsequent functions - where you access the realm asynchronously with ``@MainActor`` to ensure it - always runs on the main thread. Remember that ``await`` marks a suspension - point that could change to a different thread. -- Apps that do not use actor-isolated realms can use the ``writeAsync`` API to - :ref:`perform a background write `. This manages realm - access in a thread-safe way without requiring you to write specialized code - to do it yourself. This is a special API that outsources aspects of the - write process - where it is safe to do so - to run in an async context. - Unless you are writing to an actor-isolated realm, you do not use this - method with Swift's ``async/await`` syntax. Use this method synchronously - in your code. Alternately, you can use the ``asyncWrite`` API with Swift's - ``async/await`` syntax when awaiting writes to asynchronous realms. +- Do not change execution contexts when accessing a database. If you open a + database on the main thread to provide data for your UI, annotate subsequent + functions where you access the database asynchronously with ``@MainActor`` to + ensure it always runs on the main thread. Remember that ``await`` marks a + suspension point that could change to a different thread. +- Apps that do not use actor-isolated databases can use the ``writeAsync`` + API to :ref:`perform a background write `. + This manages database access in a thread-safe way without requiring you to + write specialized code to do it yourself. This is a special API that + outsources aspects of the write process - where it is safe to do so - to run + in an async context. Unless you are writing to an actor-isolated database, + you do not use this method with Swift's ``async/await`` syntax. Use this + method synchronously in your code. Alternately, you can use the + ``asyncWrite`` API with Swift's ``async/await`` syntax when awaiting writes + to asynchronous databases. - If you want to explicitly write concurrency code that is not actor-isolated - where accessing a realm is done in a thread-safe way, you can explicitly - :ref:`pass instances across threads ` where + where accessing a database is done in a thread-safe way, you can explicitly + :ref:`pass instances across threads ` where applicable to avoid threading-related crashes. This does require a good - understanding of Realm's threading model, as well as being mindful of + understanding of the SDK's threading model, as well as being mindful of Swift concurrency threading behaviors. .. _concurrency-page-sendable-thread-confined-reference: diff --git a/source/platforms/apple/use-realm-with-actors.txt b/source/platforms/apple/use-sdk-with-actors.txt similarity index 66% rename from source/platforms/apple/use-realm-with-actors.txt rename to source/platforms/apple/use-sdk-with-actors.txt index 456bd027a3..24b4560b63 100644 --- a/source/platforms/apple/use-realm-with-actors.txt +++ b/source/platforms/apple/use-sdk-with-actors.txt @@ -1,9 +1,21 @@ .. _swift-actor-isolated-realm: -.. _swift-use-realm-with-actors: +.. _swift-use-sdk-with-actors: -================================= -Use Realm with Actors - Swift SDK -================================= +========================================== +Use Atlas Device SDK for Swift with Actors +========================================== + +.. meta:: + :description: Learn how to use Atlas Device SDK with Swift's Actor system to manage asynchronous database work. + :keywords: Realm, Swift SDK + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: objective-c, swift .. contents:: On this page :local: @@ -11,19 +23,19 @@ Use Realm with Actors - Swift SDK :depth: 2 :class: singlecol -Starting with Realm Swift SDK version 10.39.0, Realm supports built-in -functionality for using Realm with Swift Actors. Realm's actor support -provides an alternative to managing threads or dispatch queues to perform -asynchronous work. You can use Realm with actors in a few different ways: +Starting with Swift SDK version 10.39.0, Atlas Device SDK supports built-in +functionality for Swift Actors. The SDK's actor support provides an alternative +to managing threads or dispatch queues to perform asynchronous work. You can +use the SDK with actors in a few different ways: -- Work with realm *only* on a specific actor with an actor-isolated realm -- Use Realm across actors based on the needs of your application +- Work with the SDK *only* on a specific actor with an actor-isolated database +- Use the SDK across actors based on the needs of your application -You might want to use an actor-isolated realm if you want to restrict all -realm access to a single actor. This negates the need to pass data across +You might want to use an actor-isolated database if you want to restrict all +database access to a single actor. This negates the need to pass data across the actor boundary, and can simplify data race debugging. -You might want to use realms across actors in cases where you want to +You might want to use databases across actors in cases where you want to perform different types of work on different actors. For example, you might want to read objects on the MainActor but use a background actor for large writes. @@ -34,10 +46,10 @@ documentation `. Prerequisites ------------- -To use Realm in a Swift actor, your project must: +To use the Swift SDK with a Swift actor, your project must: -- Use Realm Swift SDK version 10.39.0 or later -- Use Swift 5.8/Xcode 14.3 +- Use Swift SDK version 10.39.0 or later +- Use Swift 5.8/Xcode 14.3 or later In addition, we strongly recommend enabling these settings in your project: @@ -55,86 +67,86 @@ The examples on this page use the following model: .. _swift-open-actor-confined-realm: -Open an Actor-Isolated Realm ----------------------------- +Open an Actor-Isolated Database +------------------------------- -You can use the Swift async/await syntax to await opening a realm. +You can use the Swift async/await syntax to await opening a database. -Initializing a realm with ``try await Realm()`` opens a MainActor-isolated -realm. Alternately, you can explicitly specify an actor when opening a -realm with the ``await`` syntax. +Initializing a database with ``try await Realm()`` opens a MainActor-isolated +database. Alternately, you can explicitly specify an actor when opening a +database with the ``await`` syntax. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.await-main-actor-realm.swift :language: swift You can specify a default configuration or customize your configuration when -opening an actor-isolated realm: +opening an actor-isolated database: .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-confined-realm-with-config.swift :language: swift -For more general information about configuring a realm, refer to -:ref:`ios-configure-and-open-a-realm`. +For more general information about configuring a database, refer to +:ref:`sdks-configure-and-open-database`. -You can open a synced realm as an actor-isolated realm: +You can open a synced database as an actor-isolated database: .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-confined-synced-realm.swift :language: swift -For more general information about opening a synced realm, refer to -:ref:`ios-configure-and-open-a-synced-realm`. +For more general information about opening a synced database, refer to +:ref:`sdks-configure-and-open-synced-database`. .. _swift-define-realm-actor: -Define a Custom Realm Actor ---------------------------- +Define a Custom Database Actor +------------------------------ -You can define a specific actor to manage Realm in asynchronous contexts. -You can use this actor to manage realm access and perform write operations. +You can define a specific actor to manage the database in asynchronous contexts. +You can use this actor to manage database access and perform write operations. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.define-realm-actor.swift :language: swift -An actor-isolated realm may be used with either local or global actors. +An actor-isolated database may be used with either local or global actors. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.global-actor-example.swift :language: swift .. _swift-actor-synchronous-isolated-function: -Use a Realm Actor Synchronously in an Isolated Function -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use a Database Actor Synchronously in an Isolated Function +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a function is confined to a specific actor, you can use the actor-isolated -realm synchronously. +database synchronously. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-isolated-realm-synchronous.swift :language: swift .. _swift-actor-async-nonisolated-function: -Use a Realm Actor in Async Functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use a Database Actor in Async Functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a function isn't confined to a specific actor, you can use your Realm actor -with Swift's async/await syntax. +When a function isn't confined to a specific actor, you can use your database +actor with Swift's async/await syntax. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.actor-isolated-realm-async.swift :language: swift .. _swift-write-to-actor-confined-realm: -Write to an Actor-Isolated Realm --------------------------------- +Write to an Actor-Isolated Database +----------------------------------- -Actor-isolated realms can use Swift async/await syntax for asynchronous +Actor-isolated databases can use Swift async/await syntax for asynchronous writes. Using ``try await realm.asyncWrite { ... }`` suspends the current task, acquires the write lock without blocking the current thread, and then invokes -the block. Realm writes the data to disk on a background thread and resumes +the block. The SDK writes the data to disk on a background thread and resumes the task when that completes. This function from the example ``RealmActor`` defined above shows how you might -write to an actor-isolated realm: +write to an actor-isolated database: .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.write-async.swift :language: swift @@ -150,16 +162,16 @@ use from ``@MainActor`` functions without blocking the UI. Writes that negatively impact your app's performance due to complexity and/or platform resource constraints may still benefit from being done on a background thread. -Asynchronous writes are only supported for actor-isolated Realms or in +Asynchronous writes are only supported for actor-isolated databases or in ``@MainActor`` functions. .. _swift-realm-cannot-cross-actor-boundary: -Pass Realm Data Across the Actor Boundary ------------------------------------------ +Pass SDK Data Across the Actor Boundary +--------------------------------------- -Realm objects are not :apple:`Sendable `, -and cannot cross the actor boundary directly. To pass Realm data across +SDK objects are not :apple:`Sendable `, +and cannot cross the actor boundary directly. To pass SDK data across the actor boundary, you have two options: - Pass a ``ThreadSafeReference`` to or from the actor @@ -174,7 +186,8 @@ Pass a ThreadSafeReference You can create a :swift-sdk:`ThreadSafeReference ` on an actor where you have access to the object. In this case, we create a -``ThreadSafeReference`` on the ``MainActor``. Then, pass the ``ThreadSafeReference`` to the destination actor. +``ThreadSafeReference`` on the ``MainActor``. Then, pass the +``ThreadSafeReference`` to the destination actor. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.pass-tsr-across-actor-boundaries.swift :language: swift @@ -189,33 +202,34 @@ object local to that actor. .. important:: You must resolve a ``ThreadSafeReference`` exactly once. Otherwise, - the source realm remains pinned until the reference gets + the source database remains pinned until the reference gets deallocated. For this reason, ``ThreadSafeReference`` should be short-lived. - If you may need to share the same realm object across actors more than + If you may need to share the same database object across actors more than once, you may prefer to share the :ref:`primary key ` - and :ref:`query for it ` on + and :ref:`query for it ` on the actor where you want to use it. Refer to the "Pass a Primary Key - and Query for the Object on Another Actor" section on this page for an example. + and Query for the Object on Another Actor" section on this page for an + example. Pass a Sendable Type ~~~~~~~~~~~~~~~~~~~~ -While Realm objects are not Sendable, you can work around this by passing +While SDK objects are not Sendable, you can work around this by passing Sendable types across actor boundaries. You can use a few strategies to pass Sendable types and work with data across actor boundaries: -- Pass Sendable Realm types or primitive values instead of complete Realm objects +- Pass Sendable SDK types or primitive values instead of complete SDK objects - Pass an object's primary key and query for the object on another actor -- Create a Sendable representation of your Realm object, such as a struct +- Create a Sendable representation of your SDK object, such as a struct -Pass Sendable Realm Types and Primitive Values -`````````````````````````````````````````````` +Pass Sendable SDK Types and Primitive Values +```````````````````````````````````````````` -If you only need a piece of information from the Realm object, such as a +If you only need a piece of information from the SDK object, such as a ``String`` or ``Int``, you can pass the value directly across actors instead -of passing the Realm object. For a full list of which Realm types are Sendable, +of passing the SDK object. For a full list of which SDK types are Sendable, refer to :ref:`concurrency-page-sendable-thread-confined-reference`. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.pass-primitive-data-across-actors.swift @@ -224,7 +238,7 @@ refer to :ref:`concurrency-page-sendable-thread-confined-reference`. Pass a Primary Key and Query for the Object on Another Actor ```````````````````````````````````````````````````````````` -If you want to use a Realm object on another actor, you can share the +If you want to use a database object on another actor, you can share the :ref:`primary key ` and :ref:`query for it ` on the actor where you want to use it. @@ -241,7 +255,7 @@ different actors, you can create a struct or other Sendable representation of your data to pass across the actor boundary. For example, your actor might have a function that creates a struct -representation of the Realm object. +representation of the database object. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.pass-data-as-struct.swift :language: swift @@ -266,18 +280,18 @@ each time the object or collection changes. The SDK asynchronously calls the block on the given actor's executor. For write transactions performed on different threads or in different -processes, the SDK calls the block when the realm is (auto)refreshed +processes, the SDK calls the block when the database is (auto)refreshed to a version including the changes. For local writes, the SDK calls the block at some point in the future after the write transaction is committed. -Like :ref:`other Realm notifications `, you can -only observe objects or collections managed by a realm. You must retain the +Like :ref:`other notifications `, you can +only observe objects or collections managed by a database. You must retain the returned token for as long as you want to watch for updates. -If you need to manually advance the state of an observed realm on the main +If you need to manually advance the state of an observed database on the main thread or on another actor, call ``await realm.asyncRefresh()``. -This updates the realm and outstanding objects managed by the Realm to point to -the most recent data and deliver any applicable notifications. +This updates the database and outstanding objects managed by the database to +point to the most recent data and deliver any applicable notifications. Observation Limitations ~~~~~~~~~~~~~~~~~~~~~~~ @@ -285,8 +299,8 @@ Observation Limitations You *cannot* call the ``.observe()`` method: - During a write transaction -- When the containing realm is read-only -- On an actor-confined realm from outside the actor +- When the containing database is read-only +- On an actor-confined database from outside the actor .. _swift-actor-collection-change-listener: @@ -309,9 +323,9 @@ The SDK calls a collection notification block after each write transaction which These notifications provide information about the actor on which the change occurred. Like non-actor-isolated :ref:`collection notifications -`, they also provide -a ``change`` parameter that reports which objects are deleted, added, or -modified during the write transaction. This +`, they also provide a ``change`` parameter +that reports which objects are deleted, added, or modified during the write +transaction. This :swift-sdk:`RealmCollectionChange ` resolves to an array of index paths that you can pass to a ``UITableView``'s batch update methods. diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index f7bd20a619..4cb82ee963 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -4,6 +4,18 @@ Create Objects ============== +.. meta:: + :description: Provide a short description of the consolidated page. This is critical for SEO. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + +.. 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 diff --git a/source/sdk/crud/read.txt b/source/sdk/crud/read.txt index c8686404fc..a138b4078c 100644 --- a/source/sdk/crud/read.txt +++ b/source/sdk/crud/read.txt @@ -19,3 +19,8 @@ Read Objects :class: singlecol Placeholder page for content related to reading realm objects. + +.. _sdks-find-object-by-primary-key: + +Find an Object by Primary Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/crud/threading.txt b/source/sdk/crud/threading.txt index 4123a619ed..8d7ba8c70b 100644 --- a/source/sdk/crud/threading.txt +++ b/source/sdk/crud/threading.txt @@ -17,6 +17,11 @@ Threading :depth: 2 :class: singlecol +.. _sdks-communication-across-threads: + +Communication Across Threads +---------------------------- + .. _sdks-thread-safe-reference: Thread-Safe Reference diff --git a/source/sdk/files/configure-and-open.txt b/source/sdk/files/configure-and-open.txt index 2d15768a84..34f7ea30ed 100644 --- a/source/sdk/files/configure-and-open.txt +++ b/source/sdk/files/configure-and-open.txt @@ -30,3 +30,8 @@ schema). i.e. it's a collection of all the object schemas that the database file can manage. Some SDKs require explicit realm file schemas, while others automatically manage schemas for any object in your project, and you can specify a subset of schemas (objects) when opening a realm. + +.. _sdks-open-database-asynchronously: + +Open a Database Asynchronously +------------------------------ From d1a72eeb224de68e800edd3d94d77939c4d3adac Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 15:40:38 -0400 Subject: [PATCH 24/37] Fix snooty build errors --- source/platforms/apple/use-sdk-with-actors.txt | 6 +++--- source/sdk/model-data/object-models.txt | 5 +++++ 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/source/platforms/apple/use-sdk-with-actors.txt b/source/platforms/apple/use-sdk-with-actors.txt index 24b4560b63..b394e5c226 100644 --- a/source/platforms/apple/use-sdk-with-actors.txt +++ b/source/platforms/apple/use-sdk-with-actors.txt @@ -207,7 +207,7 @@ object local to that actor. short-lived. If you may need to share the same database object across actors more than - once, you may prefer to share the :ref:`primary key ` + once, you may prefer to share the :ref:`primary key ` and :ref:`query for it ` on the actor where you want to use it. Refer to the "Pass a Primary Key and Query for the Object on Another Actor" section on this page for an @@ -239,8 +239,8 @@ Pass a Primary Key and Query for the Object on Another Actor ```````````````````````````````````````````````````````````` If you want to use a database object on another actor, you can share the -:ref:`primary key ` and -:ref:`query for it ` on the actor +:ref:`primary key ` and +:ref:`query for it ` on the actor where you want to use it. .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.query-for-data-on-another-actor.swift diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 8590061623..df44f59a14 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -50,3 +50,8 @@ Define a Full-Text Search Property Define Optional Property Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-primary-key: + +Define a Primary Key +~~~~~~~~~~~~~~~~~~~~ From 0aa049e15ca3f2e7d0abf4c201a4d474a8aa9bbe Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 16:03:04 -0400 Subject: [PATCH 25/37] Split Create content across multiple pages --- source/sdk/crud/create.txt | 1609 +---------------- source/sdk/crud/create/create-methods.rst | 609 +++++++ .../sdk/crud/create/create-object-types.rst | 349 ++++ .../sdk/crud/create/create-property-types.rst | 731 ++++++++ 4 files changed, 1700 insertions(+), 1598 deletions(-) create mode 100644 source/sdk/crud/create/create-methods.rst create mode 100644 source/sdk/crud/create/create-object-types.rst create mode 100644 source/sdk/crud/create/create-property-types.rst diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 4cb82ee963..ba4e1e6d5e 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1,1611 +1,24 @@ -.. _sdks-crud-create: - ============== Create Objects ============== -.. meta:: - :description: Provide a short description of the consolidated page. This is critical for SEO. - :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example - -.. 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: 2 :class: singlecol -.. tabs-selector:: drivers - -This page describes the concepts of write transactions and managed objects in -a database, then explains how to create and persist a new object to a local or -synced database using Atlas Device SDK. To learn more about object models and -how to define them, refer to :ref:`sdks-object-models`. - -You can create objects whose object type is managed by the database instance. -For more information, refer to -:ref:`sdks-configure-and-open-database` or -:ref:`sdks-configure-and-open-synced-database`. - -.. note:: Write to a Synced Database - - The syntax to write a new object to the database is the same for a local or - a synced database. However, there are additional considerations that determine - whether the write operation in a synced database is successful. For more - information, refer to :ref:`sdks-write-synced-database`. - -.. _sdks-write-transactions: - -Write Transactions ------------------- - -The Atlas Device SDK persistence layer handles writes in terms of transactions. -All writes must happen within a transaction. A **transaction** is a list of -read and write operations that the database treats as a single indivisible -operation: either *all* of the operations succeed or *none* of the operations -in the transaction take effect. - -The SDK represents each transaction as a callback function -that contains zero or more read and write operations. To run -a transaction, you define a transaction callback and pass it to -one of the database's write methods. Within this callback, you can access a -database instance and then create, read, update, and delete objects within the -database. - -A database file allows only one open write transaction at a time. The SDK -blocks other writes on other threads until the open transaction on the database -file is complete. This means there is never a race condition when reading -values from the database within a transaction. - -When you are done with your transaction, the SDK either commits it or cancels -it: - -- When the SDK commits a transaction, it writes all changes to disk. For - synced databases, the SDK then queues the change for synchronization with the - backend. -- When the SDK cancels a write transaction or an operation in - the transaction causes an error, all changes are discarded. - -.. _sdks-managed-vs-unmanaged-objects: - -Managed and Unmanaged Objects ------------------------------ - -The SDK's APIs may refer to objects as managed or unmanaged. When you create -an object with the SDK, it is unmanaged until it is added to the database, -which creates a managed instance. - -- **Managed objects** are SDK objects that persist in a database instance. - Managed objects can only be accessed from an open database file. They can be - updated with changes within write transactions as long as that database - remains open. Managed objects are tied to the database instance from which - they originated and cannot be directly written to another database. However, - some of the SDKs supply a method to copy managed objects from one database - file to another. - - You can use the SDK's APIs with managed objects. For example, managed - objects can have relationships with other objects and you can observe them - for changes. You can also create an unmanaged copy of a managed object. - Refer to the :ref:`Create an Unmanaged Copy of an Object or Collection - ` section on this page. - -- **Unmanaged objects** are SDK objects that behave like normal objects, - but they are not persisted in the database. All SDK objects are unmanaged - until you add them to a database within a write transaction. - You cannot use the SDK's APIs with unmanaged objects or observe them for - changes. - -.. tip:: - - You can check if an object is managed with the - ``isManaged`` API. - -.. _sdks-create-object-methods: - -Create Object Methods ---------------------- - -The SDK provides many methods to create objects. - -.. _sdks-create-one-object: - -Create One Object -~~~~~~~~~~~~~~~~~ - -To create a new object and persist it to the database: - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-procedure.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-procedure.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-procedure.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-procedure.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-procedure.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-procedure.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-procedure.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-procedure.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-procedure.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-procedure.rst - -.. include:: /includes/sdk-examples/crud/create-realm-object.rst - -You can also upsert into a database using specific criteria. For more -information, refer to :ref:`sdks-upsert-an-object`. - -.. _sdks-create-multiple-objects: - -Create Multiple Objects -~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide a dedicated API to create multiple objects from -a sequence or collection. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - -.. include:: /includes/sdk-examples/crud/create-multiple-objects.rst - -.. _sdks-upsert-an-object: - -Create or Update an Object (Upsert) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -An **upsert** is a write operation that either inserts a new object -with a given primary key or updates an existing object that already has -that primary key. We call this an upsert because it is an "**update** or -**insert**" operation. This is useful when an object may or may not -already exist, such as when bulk importing a dataset into an existing -realm. Upserting lets you update existing entries while adding any new entries. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/api-not-supported-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-or-update-object-java-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-or-update-object-kotlin-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst - -.. include:: /includes/sdk-examples/crud/create-or-update-object.rst - -.. _sdks-create-objects-with-value: - -Initialize Objects with a Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide specific methods to initialize objects with a value. -Others use language-idiomatic methods to set the values of objects during -initialization. - -Some Property Types are Only Mutable in a Write Transaction -``````````````````````````````````````````````````````````` - -Some property types are only mutable in a write transaction. For example, -you can instantiate an object with a :ref:`Set ` -property, but you can only set that property's value in a write transaction. -You cannot initialize the object with a value for that property unless -you do so inside a write transaction. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - -.. include:: /includes/sdk-examples/crud/create-initialize-objects-with-value.rst - -.. _sdks-create-objects-from-json: - -Create Objects from JSON -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - -.. include:: /includes/sdk-examples/crud/create-objects-from-json.rst - -.. _sdks-create-unmanaged-copy: - -Create an Unmanaged Copy of an Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a -managed object or collection. In other SDKs, this API is not needed or not -currently implemented. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - -.. include:: /includes/sdk-examples/crud/create-unmanaged-object.rst - -.. _sdks-create-copy-object-to-another-database: - -Copy an Object to Another Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can copy objects that are managed by one database instance to another -database instance. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst - -.. include:: /includes/sdk-examples/crud/create-copy-object-to-another-database.rst - -.. _sdks-create-objects-in-background: - -Create Objects in the Background -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When performing large write operations, you may want to create objects in the -background. This avoids blocking the UI thread while performing large write -operations. This is particularly useful when using Device Sync, where you don't -know when and for how long the Sync client will be writing. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-objects-in-background-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-objects-in-background-description.rst - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-objects-in-background-description.rst - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/crud/create-objects-in-background.rst - -Create Specific SDK Object Types --------------------------------- - -Before you can create a new object and persist it to the database, you must -:ref:`sdks-object-models`. Then, include that object type in your database -schema when you open the database. - -.. important:: Object Types Must Be in Your Schema - - You can only write objects whose object type is included in the database - schema. If you try to reference or write an object of an object type - that isn't in your schema, the SDK returns a schema validation error. - -.. _sdks-create-realm-object: - -Create a Realm Object -~~~~~~~~~~~~~~~~~~~~~ - -The SDKs refer to the base object type as a Realm object. This is a legacy -of the former product name, Realm Database. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-realm-object-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-realm-object-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-realm-object-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-realm-object-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-realm-object-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-realm-object-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-realm-object-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-realm-object-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-realm-object-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-realm-object-description.rst - -.. include:: /includes/sdk-examples/crud/create-realm-object.rst - -Model -````` - -For more information about modeling an object, refer to: -:ref:`sdks-object-models`. - -.. include:: /includes/sdk-examples/crud/create-realm-object-model.rst - -.. _sdks-create-an-embedded-object: - -Create an Embedded Object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create a new embedded object instance, assign an instance of an -:ref:`embedded object type ` to a -parent object's property. This can be in a one-to-one, one-to-many, or -inverse :ref:`relationship ` -depending on how you defined the embedded object within the parent -object type. - -.. note:: Embedded Objects Must Be Created Within a Parent Object - - An embedded object requires a parent object and *cannot* exist as an - independent SDK object. - -Embedded objects have strict ownership with their parent object. -After you create the embedded object, you *cannot* reassign it to a -different parent object or share it between multiple parent objects. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst - -.. include:: /includes/sdk-examples/crud/create-embedded-object.rst - -Model -````` - -For more information about modeling an embedded object, refer to: -:ref:`sdks-embedded-objects`. - -.. include:: /includes/sdk-examples/crud/create-embedded-object-model.rst - -.. _sdks-create-asymmetric-object: - -Create an Asymmetric Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Asymmetric objects are write-only. Once inserted, the asymmetric object syncs -to Atlas. You *cannot* access the managed data locally, remove it from the -database, or query for it. - -For information on how to use asymmetric objects in your application, -refer to :ref:`sdks-stream-data-to-atlas`. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst - -.. include:: /includes/sdk-examples/crud/create-asymmetric-object.rst - -Model -````` - -For more information about modeling an asymmetric object, refer to: -:ref:`sdks-asymmetric-objects`. - -.. include:: /includes/sdk-examples/crud/create-asymmetric-object-model.rst - -.. _sdks-create-geospatial-data: - -Create a Geospatial Data Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After you :ref:`define a geospatial object type `, -you can use that type to create objects that persist geospatial data. - -Initialize objects that use the geospatial data class, and add them to the -database like you would any other object type. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-geospatial-object-not-supported.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-geospatial-object-not-supported.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst - - .. tab:: - :tabid: kotlin - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst - - -.. include:: /includes/sdk-examples/crud/create-geospatial-data-object.rst - -The following image shows the results of creating these two company objects: - -.. figure:: /images/geopoints.png - :alt: 2 GeoPoints - :width: 150 - :lightbox: - -Model -````` - -.. include:: /includes/sdk-examples/crud/create-geospatial-data-model.rst - -.. _sdks-create-special-property-types: - -Create Special Property Types ------------------------------ - -Depending on how you define your object type, you might have properties -that are special SDK-specific types. These may be custom data types, or -familiar language types that have specific requirements or limitations when -used with Atlas Device SDK. - -.. _sdks-create-mixed-property-type: - -Create a Generic (Mixed) Property -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SDK provides a generic mixed property type that could contain a -number of property types. It's the closest analog to a polymorphic data type -that the SDK provides. - -For a list of the value types that a mixed property can hold, refer to -:ref:`sdks-mixed-data-type`. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-mixed-property-type-description.rst - -.. include:: /includes/sdk-examples/crud/create-mixed-property-type.rst - -.. _sdks-create-counter-property-type: - -Create a Counter Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide a special property type you can use as a logical -counter. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-counter-property-type-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-counter-property-type-not-supported.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-counter-property-type-java-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-counter-property-type-kotlin-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-counter-property-type-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-counter-property-type-not-supported.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-counter-property-type-not-supported.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-counter-property-type-not-supported.rst - -.. include:: /includes/sdk-examples/crud/create-counter-property-type.rst - -.. _sdks-create-timestamp-property-type: - -Create a Timestamp Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-timestamp-property-type-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst - -.. include:: /includes/sdk-examples/crud/create-timestamp-property-type.rst - -.. _sdks-create-object-id-property-type: - -Create an Object ID Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-object-id-property-type-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-object-id-property-type-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-object-id-property-type-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-object-id-property-type-java-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-object-id-property-type-kotlin-description.rst - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-object-id-property-type-description.rst - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-object-id-property-type-description.rst - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/crud/create-object-id-property-type.rst - -.. _sdks-create-uuid-property-type: - -Create a UUID Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-uuid-property-type-description.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-uuid-property-type-description.rst - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-uuid-property-type-description.rst - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-uuid-property-type-description.rst - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/crud/create-uuid-property-type.rst - -.. _sdks-create-collection-property-types: - -Create Collection Property Types --------------------------------- - -The SDK provides a few collection type properties: - -- List -- Set -- Map - -Collections are mutable within a write transaction. - -.. tip:: Listen for Changes to a Created Collection - - After you create a collection, you can register a notification handler to - listen for changes. For more information, refer to - :ref:``. - -.. _sdks-create-list-properties: - -Create List Properties -~~~~~~~~~~~~~~~~~~~~~~ - -The SDK's list data type is a container that holds a collection of primitive -values or objects. These values may be of any supported type except another -collection. - -The SDK uses the List container type to define to-many relationships. A -**to-many** relationship means that an object is related in a specific -way to multiple objects. - -For a list of the value types that a list property can hold, refer to -:ref:``. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-list-property-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-list-property-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-list-property-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-list-property-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-list-property-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-list-property-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-mixed-property-type-description.rst - -.. include:: /includes/sdk-examples/crud/create-list-property.rst - -.. _flutter-create-Uint8List-property-type: - -Create a Uint8List Property Type (Dart) -``````````````````````````````````````` - -The Flutter SDK provides a ``Uint8List`` from Dart. For more details about -defining a ``Uint8List`` type, refer to -:ref:`dart-define-uint8list-property-type`. - -To add ``Uint8List`` to a Realm object, call ``Uint8List.fromList()`` on the data. - -.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.binary-from-list.dart - :language: dart - -.. _sdks-create-set-properties: - -Create Set Properties -~~~~~~~~~~~~~~~~~~~~~ - -Like their native counterparts, the SDK's set data type stores unique values. -These values may be of any supported type except another collection. - -The SDK uses the Set container type to define to-many relationships. A -**to-many** relationship means that an object is related in a specific -way to multiple objects. - -For a list of the value types that a set property can hold, refer to -:ref:``. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-set-property-description.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-set-properties-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-set-properties-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-set-properties-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-set-properties-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-set-properties-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/javascript/crud/create-set-properties-description.rst - -.. include:: /includes/sdk-examples/crud/create-set-property.rst - -.. _sdks-create-dictionary-properties: - -Create Dictionary Properties -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SDK supports a dictionary (map) property type. Dictionary keys must be -strings, but values can be any of the supported value types. For a list of the -value types that a dictionary property can hold, refer to -:ref:``. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-dictionary-property-description.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-dictionary-property-java-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-dictionary-property-kotlin-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-dictionary-property-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-dictionary-property-description.rst - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-dictionary-property-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/javascript/crud/create-dictionary-property-description.rst - -.. include:: /includes/sdk-examples/crud/create-dictionary-property.rst - -.. _sdks-create-relationship-property-types: - -Create Relationship Property Types ----------------------------------- - -When you have properties whose type references another SDK object, this creates -a relationship between the objects. This can be a to-one, to-many, or -inverse relationship. For more information about relationships, refer to -:ref:`sdks-relationships`. - -.. _sdks-create-to-one-relationship: - -Create a To-One Relationship -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create a new object instance with a -:ref:`to-one relationship ` -property, instantiate both objects and pass the referenced object to the -relationship property. - -You can optionally create an inverse relationship to refer to the main object -from the related object. For more information, refer to the -:ref:`sdks-create-object-with-inverse-relationship` section on this page. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-to-one-relationship-description.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-to-one-relationship-description.rst - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/crud/create-to-one-relationship.rst - -.. _sdks-create-to-many-relationship: - -Create a To-Many Relationship -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create a new object instance with a -:ref:`to-many relationship ` -property, instantiate all objects and pass any referenced objects to the -relationship collection property. - -You may use a List or a Set to represent a to-many relationship, depending -on whether you require the values to be unique, or whether you want to use any -of the special collection type methods. - -You can optionally create an inverse relationship to refer to the main object -from the related object. For more information, refer to the -:ref:`sdks-create-object-with-inverse-relationship` section on this page. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-to-many-relationship-description.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-to-many-relationship-description.rst - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/crud/create-to-many-relationship.rst - -.. _sdks-create-object-with-inverse-relationship: - -Create an Inverse Relationship -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create a new object instance with an -:ref:`inverse relationship ` -property, instantiate the parent object and pass any referenced child -objects to the inverse relationship property. - -After you create an object that has an inverse relationship, you can access -the inverse relationship property to get the child objects. However, you -*cannot* directly modify the backlink itself. For more information, refer to -:ref:``. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-to-many-relationship-description.rst - - .. tab:: - :tabid: csharp - - .. tab:: - :tabid: dart - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-to-many-relationship-description.rst - - .. tab:: - :tabid: objectivec +.. toctree:: + :titlesonly: - .. tab:: - :tabid: swift + Create Object Methods + Create Object Types + Create Property Types - .. tab:: - :tabid: typescript +The following pages contain information about how to perform write +transactions, how to create specific object types, and how to create specific +property types using Atlas Device SDK. -.. include:: /includes/sdk-examples/crud/create-inverse-relationship.rst +- :ref:`sdks-create-object-methods` +- :ref:`sdks-create-specific-object-types` +- :ref:`sdks-create-specific-property-types` diff --git a/source/sdk/crud/create/create-methods.rst b/source/sdk/crud/create/create-methods.rst new file mode 100644 index 0000000000..b5fc71063f --- /dev/null +++ b/source/sdk/crud/create/create-methods.rst @@ -0,0 +1,609 @@ +.. _sdks-create-object-methods: + +===================== +Create Object Methods +===================== + +.. meta:: + :description: Learn about performing write transactions and the different ways to create objects with Atlas Device SDK. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + +.. 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: 2 + :class: singlecol + +.. tabs-selector:: drivers + +This page describes the concepts of write transactions and managed objects in +a database, then explains how to create and persist a new object to a local or +synced database using Atlas Device SDK. To learn more about object models and +how to define them, refer to :ref:`sdks-object-models`. + +You can create objects whose object type is managed by the database instance. +For more information, refer to +:ref:`sdks-configure-and-open-database` or +:ref:`sdks-configure-and-open-synced-database`. + +.. note:: Write to a Synced Database + + The syntax to write a new object to the database is the same for a local or + a synced database. However, there are additional considerations that determine + whether the write operation in a synced database is successful. For more + information, refer to :ref:`sdks-write-synced-database`. + +.. _sdks-write-transactions: + +Write Transactions +------------------ + +The Atlas Device SDK persistence layer handles writes in terms of transactions. +All writes must happen within a transaction. A **transaction** is a list of +read and write operations that the database treats as a single indivisible +operation: either *all* of the operations succeed or *none* of the operations +in the transaction take effect. + +The SDK represents each transaction as a callback function +that contains zero or more read and write operations. To run +a transaction, you define a transaction callback and pass it to +one of the database's write methods. Within this callback, you can access a +database instance and then create, read, update, and delete objects within the +database. + +A database file allows only one open write transaction at a time. The SDK +blocks other writes on other threads until the open transaction on the database +file is complete. This means there is never a race condition when reading +values from the database within a transaction. + +When you are done with your transaction, the SDK either commits it or cancels +it: + +- When the SDK commits a transaction, it writes all changes to disk. For + synced databases, the SDK then queues the change for synchronization with the + backend. +- When the SDK cancels a write transaction or an operation in + the transaction causes an error, all changes are discarded. + +.. _sdks-managed-vs-unmanaged-objects: + +Managed and Unmanaged Objects +----------------------------- + +The SDK's APIs may refer to objects as managed or unmanaged. When you create +an object with the SDK, it is unmanaged until it is added to the database, +which creates a managed instance. + +- **Managed objects** are SDK objects that persist in a database instance. + Managed objects can only be accessed from an open database file. They can be + updated with changes within write transactions as long as that database + remains open. Managed objects are tied to the database instance from which + they originated and cannot be directly written to another database. However, + some of the SDKs supply a method to copy managed objects from one database + file to another. + + You can use the SDK's APIs with managed objects. For example, managed + objects can have relationships with other objects and you can observe them + for changes. You can also create an unmanaged copy of a managed object. + Refer to the :ref:`Create an Unmanaged Copy of an Object or Collection + ` section on this page. + +- **Unmanaged objects** are SDK objects that behave like normal objects, + but they are not persisted in the database. All SDK objects are unmanaged + until you add them to a database within a write transaction. + You cannot use the SDK's APIs with unmanaged objects or observe them for + changes. + +.. _sdks-create-object-methods: + +Create Object Methods +--------------------- + +The SDK provides a variety of methods to create objects and perform write +operations. + +.. _sdks-create-one-object: + +Create One Object +~~~~~~~~~~~~~~~~~ + +To create a new object and persist it to the database: + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-procedure.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-procedure.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-procedure.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-procedure.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-procedure.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-procedure.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-procedure.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-procedure.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-procedure.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-procedure.rst + +.. include:: /includes/sdk-examples/crud/create-realm-object.rst + +You can also upsert into a database using specific criteria. For more +information, refer to :ref:`sdks-upsert-an-object`. + +.. _sdks-create-multiple-objects: + +Create Multiple Objects +~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide a dedicated API to create multiple objects from +a sequence or collection. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + +.. include:: /includes/sdk-examples/crud/create-multiple-objects.rst + +.. _sdks-upsert-an-object: + +Create or Update an Object (Upsert) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An **upsert** is a write operation that either inserts a new object +with a given primary key or updates an existing object that already has +that primary key. We call this an upsert because it is an "**update** or +**insert**" operation. This is useful when an object may or may not +already exist, such as when bulk importing a dataset into an existing +realm. Upserting lets you update existing entries while adding any new entries. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/api-not-supported-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-or-update-object-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-or-update-object-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst + +.. include:: /includes/sdk-examples/crud/create-or-update-object.rst + +.. _sdks-create-objects-with-value: + +Initialize Objects with a Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide specific methods to initialize objects with a value. +Others use language-idiomatic methods to set the values of objects during +initialization. + +Some Property Types are Only Mutable in a Write Transaction +``````````````````````````````````````````````````````````` + +Some property types are only mutable in a write transaction. For example, +you can instantiate an object with a :ref:`Set ` +property, but you can only set that property's value in a write transaction. +You cannot initialize the object with a value for that property unless +you do so inside a write transaction. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + +.. include:: /includes/sdk-examples/crud/create-initialize-objects-with-value.rst + +.. _sdks-create-objects-from-json: + +Create Objects from JSON +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + +.. include:: /includes/sdk-examples/crud/create-objects-from-json.rst + +.. _sdks-create-unmanaged-copy: + +Create an Unmanaged Copy of an Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a +managed object or collection. In other SDKs, this API is not needed or not +currently implemented. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + +.. include:: /includes/sdk-examples/crud/create-unmanaged-object.rst + +.. _sdks-create-copy-object-to-another-database: + +Copy an Object to Another Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can copy objects that are managed by one database instance to another +database instance. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst + +.. include:: /includes/sdk-examples/crud/create-copy-object-to-another-database.rst + +.. _sdks-create-objects-in-background: + +Create Objects in the Background +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When performing large write operations, you may want to create objects in the +background. This avoids blocking the UI thread while performing large write +operations. This is particularly useful when using Device Sync, where you don't +know when and for how long the Sync client will be writing. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-objects-in-background.rst diff --git a/source/sdk/crud/create/create-object-types.rst b/source/sdk/crud/create/create-object-types.rst new file mode 100644 index 0000000000..24680920b1 --- /dev/null +++ b/source/sdk/crud/create/create-object-types.rst @@ -0,0 +1,349 @@ +.. _sdks-create-specific-object-types: + +============================ +Create Specific Object Types +============================ + +.. meta:: + :description: Learn how to create specific types of objects with Atlas Device SDK, including constraints for certain object types. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + +.. 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: 2 + :class: singlecol + +.. tabs-selector:: drivers + +This page describes how to create specific types of objects using Atlas Device +SDK. To learn more about object models and how to define them, refer to +:ref:`sdks-object-models`. + +You can create objects whose object type is managed by the database instance. +For more information, refer to +:ref:`sdks-configure-and-open-database` or +:ref:`sdks-configure-and-open-synced-database`. + +For more information about write transactions and the methods you can use to +create an object, refer to :ref:`sdks-create-object-methods`. + +For information about creating specific property types, including special +types, collections, and relationship properties, refer to +:ref:`sdks-create-specific-property-types`. + +Create Specific SDK Object Types +-------------------------------- + +Before you can create a new object and persist it to the database, you must +:ref:`sdks-object-models`. Then, include that object type in your database +schema when you open the database. + +.. important:: Object Types Must Be in Your Schema + + You can only write objects whose object type is included in the database + schema. If you try to reference or write an object of an object type + that isn't in your schema, the SDK returns a schema validation error. + +.. _sdks-create-realm-object: + +Create a Realm Object +~~~~~~~~~~~~~~~~~~~~~ + +The SDKs refer to the base object type as a Realm object. This is a legacy +of the former product name, Realm Database. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-realm-object-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-realm-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-realm-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-realm-object-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-realm-object-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-realm-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-realm-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-realm-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-realm-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-realm-object-description.rst + +.. include:: /includes/sdk-examples/crud/create-realm-object.rst + +Model +````` + +For more information about modeling an object, refer to: +:ref:`sdks-object-models`. + +.. include:: /includes/sdk-examples/crud/create-realm-object-model.rst + +.. _sdks-create-an-embedded-object: + +Create an Embedded Object +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a new embedded object instance, assign an instance of an +:ref:`embedded object type ` to a +parent object's property. This can be in a one-to-one, one-to-many, or +inverse :ref:`relationship ` +depending on how you defined the embedded object within the parent +object type. + +.. note:: Embedded Objects Must Be Created Within a Parent Object + + An embedded object requires a parent object and *cannot* exist as an + independent SDK object. + +Embedded objects have strict ownership with their parent object. +After you create the embedded object, you *cannot* reassign it to a +different parent object or share it between multiple parent objects. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-embedded-object-description.rst + +.. include:: /includes/sdk-examples/crud/create-embedded-object.rst + +Model +````` + +For more information about modeling an embedded object, refer to: +:ref:`sdks-embedded-objects`. + +.. include:: /includes/sdk-examples/crud/create-embedded-object-model.rst + +.. _sdks-create-asymmetric-object: + +Create an Asymmetric Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Asymmetric objects are write-only. Once inserted, the asymmetric object syncs +to Atlas. You *cannot* access the managed data locally, remove it from the +database, or query for it. + +For information on how to use asymmetric objects in your application, +refer to :ref:`sdks-stream-data-to-atlas`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-asymmetric-object-description.rst + +.. include:: /includes/sdk-examples/crud/create-asymmetric-object.rst + +Model +````` + +For more information about modeling an asymmetric object, refer to: +:ref:`sdks-asymmetric-objects`. + +.. include:: /includes/sdk-examples/crud/create-asymmetric-object-model.rst + +.. _sdks-create-geospatial-data: + +Create a Geospatial Data Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After you :ref:`define a geospatial object type `, +you can use that type to create objects that persist geospatial data. + +Initialize objects that use the geospatial data class, and add them to the +database like you would any other object type. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-geospatial-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-geospatial-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst + + +.. include:: /includes/sdk-examples/crud/create-geospatial-data-object.rst + +The following image shows the results of creating these two company objects: + +.. figure:: /images/geopoints.png + :alt: 2 GeoPoints + :width: 150 + :lightbox: + +Model +````` + +.. include:: /includes/sdk-examples/crud/create-geospatial-data-model.rst diff --git a/source/sdk/crud/create/create-property-types.rst b/source/sdk/crud/create/create-property-types.rst new file mode 100644 index 0000000000..9dfbe14789 --- /dev/null +++ b/source/sdk/crud/create/create-property-types.rst @@ -0,0 +1,731 @@ +.. _sdks-create-specific-property-types: + +============================== +Create Specific Property Types +============================== + +.. meta:: + :description: Learn how to create specific property types with Atlas Device SDK. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + +.. 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: 2 + :class: singlecol + +.. tabs-selector:: drivers + +This page describes how to create specific property types, including: + +- Special SDK-specific types, such as counters or mixed data types +- Collection property types, such as lists, sets, and maps +- Relationship property types, including to-one, to-many, and inverse + relationships + +To learn more about how to define these property types in the object model, +refer to :ref:`sdks-object-models`. + +For information about how to create specific types of objects, refer to +:ref:`sdks-create-specific-object-types`. + +For information about write transactions and the methods you can use to create +objects, refer to :ref:`sdks-create-object-methods`. + +.. _sdks-create-special-property-types: + +Create Special Property Types +----------------------------- + +Depending on how you define your object type, you might have properties +that are special SDK-specific types. These may be custom data types, or +familiar language types that have specific requirements or limitations when +used with Atlas Device SDK. + +.. _sdks-create-mixed-property-type: + +Create a Generic (Mixed) Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SDK provides a generic mixed property type that could contain a +number of property types. It's the closest analog to a polymorphic data type +that the SDK provides. + +For a list of the value types that a mixed property can hold, refer to +:ref:`sdks-mixed-data-type`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-mixed-property-type-description.rst + +.. include:: /includes/sdk-examples/crud/create-mixed-property-type.rst + +.. _sdks-create-counter-property-type: + +Create a Counter Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide a special property type you can use as a logical +counter. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-counter-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-counter-property-type-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-counter-property-type-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-counter-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-counter-property-type-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-counter-property-type-not-supported.rst + +.. include:: /includes/sdk-examples/crud/create-counter-property-type.rst + +.. _sdks-create-timestamp-property-type: + +Create a Timestamp Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-timestamp-property-type-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst + +.. include:: /includes/sdk-examples/crud/create-timestamp-property-type.rst + +.. _sdks-create-object-id-property-type: + +Create an Object ID Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-object-id-property-type-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-object-id-property-type-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-object-id-property-type-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-object-id-property-type.rst + +.. _sdks-create-uuid-property-type: + +Create a UUID Property Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-uuid-property-type-description.rst + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-uuid-property-type.rst + +.. _sdks-create-collection-property-types: + +Create Collection Property Types +-------------------------------- + +The SDK provides a few collection type properties: + +- List +- Set +- Map + +Collections are mutable within a write transaction. + +.. tip:: Listen for Changes to a Created Collection + + After you create a collection, you can register a notification handler to + listen for changes. For more information, refer to + :ref:``. + +.. _sdks-create-list-properties: + +Create List Properties +~~~~~~~~~~~~~~~~~~~~~~ + +The SDK's list data type is a container that holds a collection of primitive +values or objects. These values may be of any supported type except another +collection. + +The SDK uses the List container type to define to-many relationships. A +**to-many** relationship means that an object is related in a specific +way to multiple objects. + +For a list of the value types that a list property can hold, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-list-property-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-list-property-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-list-property-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-list-property-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-list-property-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-list-property-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-mixed-property-type-description.rst + +.. include:: /includes/sdk-examples/crud/create-list-property.rst + +.. _flutter-create-Uint8List-property-type: + +Create a Uint8List Property Type (Dart) +``````````````````````````````````````` + +The Flutter SDK provides a ``Uint8List`` from Dart. For more details about +defining a ``Uint8List`` type, refer to +:ref:`dart-define-uint8list-property-type`. + +To add ``Uint8List`` to a Realm object, call ``Uint8List.fromList()`` on the data. + +.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.binary-from-list.dart + :language: dart + +.. _sdks-create-set-properties: + +Create Set Properties +~~~~~~~~~~~~~~~~~~~~~ + +Like their native counterparts, the SDK's set data type stores unique values. +These values may be of any supported type except another collection. + +The SDK uses the Set container type to define to-many relationships. A +**to-many** relationship means that an object is related in a specific +way to multiple objects. + +For a list of the value types that a set property can hold, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-set-property-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-set-properties-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-set-properties-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-set-properties-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-mixed-property-type-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-set-properties-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-set-properties-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/crud/create-set-properties-description.rst + +.. include:: /includes/sdk-examples/crud/create-set-property.rst + +.. _sdks-create-dictionary-properties: + +Create Dictionary Properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SDK supports a dictionary (map) property type. Dictionary keys must be +strings, but values can be any of the supported value types. For a list of the +value types that a dictionary property can hold, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-dictionary-property-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-dictionary-property-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-dictionary-property-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/crud/create-dictionary-property-description.rst + +.. include:: /includes/sdk-examples/crud/create-dictionary-property.rst + +.. _sdks-create-relationship-property-types: + +Create Relationship Property Types +---------------------------------- + +When you have properties whose type references another SDK object, this creates +a relationship between the objects. This can be a to-one, to-many, or +inverse relationship. For more information about relationships, refer to +:ref:`sdks-relationships`. + +.. _sdks-create-to-one-relationship: + +Create a To-One Relationship +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a new object instance with a +:ref:`to-one relationship ` +property, instantiate both objects and pass the referenced object to the +relationship property. + +You can optionally create an inverse relationship to refer to the main object +from the related object. For more information, refer to the +:ref:`sdks-create-object-with-inverse-relationship` section on this page. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-to-one-relationship-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-to-one-relationship-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-to-one-relationship.rst + +.. _sdks-create-to-many-relationship: + +Create a To-Many Relationship +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a new object instance with a +:ref:`to-many relationship ` +property, instantiate all objects and pass any referenced objects to the +relationship collection property. + +You may use a List or a Set to represent a to-many relationship, depending +on whether you require the values to be unique, or whether you want to use any +of the special collection type methods. + +You can optionally create an inverse relationship to refer to the main object +from the related object. For more information, refer to the +:ref:`sdks-create-object-with-inverse-relationship` section on this page. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-to-many-relationship.rst + +.. _sdks-create-object-with-inverse-relationship: + +Create an Inverse Relationship +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a new object instance with an +:ref:`inverse relationship ` +property, instantiate the parent object and pass any referenced child +objects to the inverse relationship property. + +After you create an object that has an inverse relationship, you can access +the inverse relationship property to get the child objects. However, you +*cannot* directly modify the backlink itself. For more information, refer to +:ref:``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-to-many-relationship-description.rst + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/crud/create-inverse-relationship.rst \ No newline at end of file From 3b6a6dca02bb11de864d589d6f640c0d634da3a6 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 16:11:44 -0400 Subject: [PATCH 26/37] Update ToC and refs --- source/sdk/crud/create.txt | 6 +++--- source/sdk/crud/create/create-methods.rst | 2 -- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index ba4e1e6d5e..5eb9f4796b 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -19,6 +19,6 @@ The following pages contain information about how to perform write transactions, how to create specific object types, and how to create specific property types using Atlas Device SDK. -- :ref:`sdks-create-object-methods` -- :ref:`sdks-create-specific-object-types` -- :ref:`sdks-create-specific-property-types` +- :ref:`Create Object Methods ` +- :ref:`Create Object Types ` +- :ref:`Create Property Types ` diff --git a/source/sdk/crud/create/create-methods.rst b/source/sdk/crud/create/create-methods.rst index b5fc71063f..63ae4fb933 100644 --- a/source/sdk/crud/create/create-methods.rst +++ b/source/sdk/crud/create/create-methods.rst @@ -102,8 +102,6 @@ which creates a managed instance. You cannot use the SDK's APIs with unmanaged objects or observe them for changes. -.. _sdks-create-object-methods: - Create Object Methods --------------------- From 61a47a91fc8b585236e0698154c5de89a780b00f Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 16:12:13 -0400 Subject: [PATCH 27/37] Remove OTP --- source/sdk/crud/create.txt | 6 ------ 1 file changed, 6 deletions(-) diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 5eb9f4796b..659c13a44c 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -2,12 +2,6 @@ Create Objects ============== -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - .. toctree:: :titlesonly: From 6df10409a4df3df15c23edf6b65c632a158df582 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 16:15:24 -0400 Subject: [PATCH 28/37] Rename rst to txt --- source/sdk/crud/create/{create-methods.rst => create-methods.txt} | 0 .../create/{create-object-types.rst => create-object-types.txt} | 0 .../{create-property-types.rst => create-property-types.txt} | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename source/sdk/crud/create/{create-methods.rst => create-methods.txt} (100%) rename source/sdk/crud/create/{create-object-types.rst => create-object-types.txt} (100%) rename source/sdk/crud/create/{create-property-types.rst => create-property-types.txt} (100%) diff --git a/source/sdk/crud/create/create-methods.rst b/source/sdk/crud/create/create-methods.txt similarity index 100% rename from source/sdk/crud/create/create-methods.rst rename to source/sdk/crud/create/create-methods.txt diff --git a/source/sdk/crud/create/create-object-types.rst b/source/sdk/crud/create/create-object-types.txt similarity index 100% rename from source/sdk/crud/create/create-object-types.rst rename to source/sdk/crud/create/create-object-types.txt diff --git a/source/sdk/crud/create/create-property-types.rst b/source/sdk/crud/create/create-property-types.txt similarity index 100% rename from source/sdk/crud/create/create-property-types.rst rename to source/sdk/crud/create/create-property-types.txt From 9d2b19c0a02ae0d3894a5386a6e96a88aa3dcc68 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 16:18:46 -0400 Subject: [PATCH 29/37] Fix snooty build errors --- source/index.txt | 2 +- source/sdk/crud.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/index.txt b/source/index.txt index fb684ed1cf..43c349c890 100644 --- a/source/index.txt +++ b/source/index.txt @@ -144,7 +144,7 @@ other clients. .. step:: Read and Write Data - :ref:`Create `, :ref:`read `, + :ref:`Create `, :ref:`read `, :ref:`update `, and :ref:`delete ` objects from the device database. Filter data using the :ref:`query engines ` provided by the SDK. diff --git a/source/sdk/crud.txt b/source/sdk/crud.txt index 1dd90517b4..2505e09065 100644 --- a/source/sdk/crud.txt +++ b/source/sdk/crud.txt @@ -15,7 +15,7 @@ Read and Write Data The following pages contain information about how to read and write data, manage objects across threads, and use the Atlas Device SDK query engines: -- :ref:`sdks-crud-create` +- :ref:`sdks-create-object-methods` - :ref:`sdks-crud-read` - :ref:`sdks-crud-update` - :ref:`sdks-crud-delete` From f39ab91573fd867aee5dc74db2559fe74b1ece4a Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 24 May 2024 17:02:30 -0400 Subject: [PATCH 30/37] Update naming --- source/platforms/apple.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/platforms/apple.txt b/source/platforms/apple.txt index df77c1169d..cb469465eb 100644 --- a/source/platforms/apple.txt +++ b/source/platforms/apple.txt @@ -14,7 +14,7 @@ Build for Apple :titlesonly: Swift Concurrency - Use Realm with Actors + Swift Actor Support Placeholder page for information about building for Apple. From c8657b2b650adf0a92213532a67fa3277901797e Mon Sep 17 00:00:00 2001 From: Dachary Date: Tue, 25 Jun 2024 10:17:00 -0400 Subject: [PATCH 31/37] Apply suggestions from review Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com> --- ...counter-property-type-java-description.rst | 1 - ...eate-or-update-object-java-description.rst | 5 ++- ...te-or-update-object-kotlin-description.rst | 5 ++- ...eate-objects-in-background-description.rst | 8 ++--- .../crud/create-or-update-object.rst | 4 +-- .../sdk-examples/crud/create-realm-object.rst | 2 -- source/platforms/apple/swift-concurrency.txt | 12 +++---- .../platforms/apple/use-sdk-with-actors.txt | 4 +-- source/sdk/crud/create/create-methods.txt | 17 +++++----- .../sdk/crud/create/create-object-types.txt | 11 +++--- .../sdk/crud/create/create-property-types.txt | 34 +++++++++---------- 11 files changed, 48 insertions(+), 55 deletions(-) diff --git a/source/includes/api-details/java/crud/create-counter-property-type-java-description.rst b/source/includes/api-details/java/crud/create-counter-property-type-java-description.rst index c1fdc88044..ce9cc49e4a 100644 --- a/source/includes/api-details/java/crud/create-counter-property-type-java-description.rst +++ b/source/includes/api-details/java/crud/create-counter-property-type-java-description.rst @@ -38,7 +38,6 @@ within a write transaction. .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-set.java :language: java - :copyable: false Since ``MutableRealmInteger`` instances retain a reference to their parent object, neither object can be garbage collected while you still diff --git a/source/includes/api-details/java/crud/create-or-update-object-java-description.rst b/source/includes/api-details/java/crud/create-or-update-object-java-description.rst index be8db936a6..e3bf1f8de9 100644 --- a/source/includes/api-details/java/crud/create-or-update-object-java-description.rst +++ b/source/includes/api-details/java/crud/create-or-update-object-java-description.rst @@ -5,8 +5,7 @@ update their name to "Andy" using :java-sdk:`insertOrUpdate() .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.upsert-an-object.java :language: java - :emphasize-lines: 14-16 - :copyable: false + :emphasize-lines: 16 You can also use :java-sdk:`copyToRealmOrUpdate() ` to @@ -14,7 +13,7 @@ either create a new object based on a supplied object or update an existing object with the same primary key value. Use the ``CHECK_SAME_VALUES_BEFORE_SET`` :java-sdk:`ImportFlag ` to only update fields -that are different in the supplied object: +that are different in the supplied object. The following example demonstrates how to insert an object or, if an object already exists with the same primary key, update only those fields that differ: diff --git a/source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst b/source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst index e491605d38..5ed7628137 100644 --- a/source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst +++ b/source/includes/api-details/java/crud/create-or-update-object-kotlin-description.rst @@ -5,8 +5,7 @@ update their name to "Andy" using :java-sdk:`insertOrUpdate() .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.upsert-an-object.kt :language: kotlin - :emphasize-lines: 14-16 - :copyable: false + :emphasize-lines: 16 You can also use :java-sdk:`copyToRealmOrUpdate() ` to @@ -14,7 +13,7 @@ either create a new object based on a supplied object or update an existing object with the same primary key value. Use the ``CHECK_SAME_VALUES_BEFORE_SET`` :java-sdk:`ImportFlag ` to only update fields -that are different in the supplied object: +that are different in the supplied object. The following example demonstrates how to insert an object or, if an object already exists with the same primary key, update only those fields that differ: diff --git a/source/includes/api-details/swift/crud/create-objects-in-background-description.rst b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst index 6a7266ceb8..705d193e3d 100644 --- a/source/includes/api-details/swift/crud/create-objects-in-background-description.rst +++ b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst @@ -11,7 +11,7 @@ the write completes or fails. Things to consider when performing background writes: -- Async writes block closing or invalidating the realm +- Async writes block closing or invalidating the database - You can explicitly commit or cancel transactions Wait for Async Writes to Complete @@ -87,8 +87,8 @@ of the ``beginAsyncWrite`` or the ``commitAsyncWrite`` you want to cancel. You can use Swift concurrency features to write asynchronously to an actor-isolated database. -This function from the example ``RealmActor`` :ref:`defined on the -Use Realm with Actors page ` shows how you might +The following function is taken from the example ``RealmActor`` defined on the +:ref:`swift-define-realm-actor` page. It shows how you might write to an actor-isolated database: .. literalinclude:: /examples/generated/code/start/RealmActor.snippet.write-async.swift @@ -100,7 +100,7 @@ And you might perform this write using Swift's async syntax: :language: swift This operation does not block or perform I/O on the calling thread. For -more information about writing to realm using Swift concurrency features, +more information about writing to a database using Swift concurrency features, refer to :ref:`swift-actor-isolated-realm`. *Perform Writes using Async/Await Syntax* diff --git a/source/includes/sdk-examples/crud/create-or-update-object.rst b/source/includes/sdk-examples/crud/create-or-update-object.rst index 478dfd9e16..22f6a0b00a 100644 --- a/source/includes/sdk-examples/crud/create-or-update-object.rst +++ b/source/includes/sdk-examples/crud/create-or-update-object.rst @@ -25,7 +25,6 @@ .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.copy-or-update-same-values-flag.java :language: java :emphasize-lines: 16 - :copyable: false - id: java-kotlin content: | @@ -33,14 +32,13 @@ .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.copy-or-update-same-values-flag.kt :language: kotlin :emphasize-lines: 15-16 - :copyable: false - id: javascript content: | .. literalinclude:: /examples/generated/node/read-and-write-data.snippet.read-and-write-upsert-an-object.js :language: javascript - :emphasize-lines: 4, 13 + :emphasize-lines: 4, 7, 13, 16 - id: kotlin content: | diff --git a/source/includes/sdk-examples/crud/create-realm-object.rst b/source/includes/sdk-examples/crud/create-realm-object.rst index 991d20cc6a..033ac37b58 100644 --- a/source/includes/sdk-examples/crud/create-realm-object.rst +++ b/source/includes/sdk-examples/crud/create-realm-object.rst @@ -25,7 +25,6 @@ .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.create-an-object.java :language: java :emphasize-lines: 3 - :copyable: false - id: java-kotlin content: | @@ -33,7 +32,6 @@ .. literalinclude:: /examples/generated/java/sync/WritesTest.snippet.create-an-object.kt :language: kotlin :emphasize-lines: 3 - :copyable: false - id: javascript content: | diff --git a/source/platforms/apple/swift-concurrency.txt b/source/platforms/apple/swift-concurrency.txt index 8039cfbe86..bb64760b16 100644 --- a/source/platforms/apple/swift-concurrency.txt +++ b/source/platforms/apple/swift-concurrency.txt @@ -12,10 +12,6 @@ Swift Concurrency - Swift SDK :name: genre :values: reference -.. facet:: - :name: programming_language - :values: objective-c, swift - .. contents:: On this page :local: :backlinks: none @@ -25,7 +21,7 @@ Swift Concurrency - Swift SDK Swift's concurrency system provides built-in support for writing asynchronous and parallel code in a structured way. For a detailed overview of the Swift concurrency system, refer to the `Swift Programming Language Concurrency -topic `__. +topic `__. While the considerations on this page broadly apply to using the Swift SDK with Swift concurrency features, Swift SDK version 10.39.0 adds support @@ -136,14 +132,14 @@ I/O to write data to disk is done by a background worker thread. For small writes, using this function on the main thread may block the main thread for less time than manually dispatching the write to a background thread. -For more information, including code examples, refer to: :ref:`sdks-create-objects-in-background`. +For more information, including code examples, refer to :ref:`sdks-create-objects-in-background`. Tasks and TaskGroups -------------------- Swift concurrency provides APIs to manage :apple:`Tasks ` and :apple:`TaskGroups `. The `Swift concurrency -documentation `__ +documentation `__ defines a task as a unit of work that can be run asynchronously as part of your program. Task allows you to specifically define a unit of asynchronous work. TaskGroup lets you define a collection of Tasks to execute as a unit @@ -233,7 +229,7 @@ To avoid threading-related issues in code that uses Swift concurrency features: .. _concurrency-page-sendable-thread-confined-reference: -Sendable, Non-Sendable and Thread-Confined Types +Sendable, Non-Sendable, and Thread-Confined Types ------------------------------------------------ .. include:: /includes/swift-api-sendable-thread-confined-reference.rst diff --git a/source/platforms/apple/use-sdk-with-actors.txt b/source/platforms/apple/use-sdk-with-actors.txt index b394e5c226..f5ebc3db98 100644 --- a/source/platforms/apple/use-sdk-with-actors.txt +++ b/source/platforms/apple/use-sdk-with-actors.txt @@ -7,7 +7,7 @@ Use Atlas Device SDK for Swift with Actors .. meta:: :description: Learn how to use Atlas Device SDK with Swift's Actor system to manage asynchronous database work. - :keywords: Realm, Swift SDK + :keywords: Realm, Swift SDK, code examples .. facet:: :name: genre @@ -15,7 +15,7 @@ Use Atlas Device SDK for Swift with Actors .. facet:: :name: programming_language - :values: objective-c, swift + :values: swift .. contents:: On this page :local: diff --git a/source/sdk/crud/create/create-methods.txt b/source/sdk/crud/create/create-methods.txt index 63ae4fb933..fcdc41de06 100644 --- a/source/sdk/crud/create/create-methods.txt +++ b/source/sdk/crud/create/create-methods.txt @@ -6,7 +6,7 @@ Create Object Methods .. meta:: :description: Learn about performing write transactions and the different ways to create objects with Atlas Device SDK. - :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + :keywords: Realm, C++ SDK, Flutter SDK, .NET SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre @@ -67,11 +67,11 @@ values from the database within a transaction. When you are done with your transaction, the SDK either commits it or cancels it: -- When the SDK commits a transaction, it writes all changes to disk. For +- When the SDK commits a write transaction, it writes all changes to disk. For synced databases, the SDK then queues the change for synchronization with the backend. - When the SDK cancels a write transaction or an operation in - the transaction causes an error, all changes are discarded. + the transaction causes an error, it discards all changes. .. _sdks-managed-vs-unmanaged-objects: @@ -88,7 +88,8 @@ which creates a managed instance. remains open. Managed objects are tied to the database instance from which they originated and cannot be directly written to another database. However, some of the SDKs supply a method to copy managed objects from one database - file to another. + file to another. Refer to the :ref:`sdks-create-copy-object-to-another-database` + section on this page. You can use the SDK's APIs with managed objects. For example, managed objects can have relationships with other objects and you can observe them @@ -169,8 +170,8 @@ To create a new object and persist it to the database: .. include:: /includes/sdk-examples/crud/create-realm-object.rst -You can also upsert into a database using specific criteria. For more -information, refer to :ref:`sdks-upsert-an-object`. +You can also upsert into a database using specific criteria. Refer to the +:ref:`sdks-upsert-an-object` section on this page. .. _sdks-create-multiple-objects: @@ -244,7 +245,7 @@ with a given primary key or updates an existing object that already has that primary key. We call this an upsert because it is an "**update** or **insert**" operation. This is useful when an object may or may not already exist, such as when bulk importing a dataset into an existing -realm. Upserting lets you update existing entries while adding any new entries. +database. Upserting lets you update existing entries while adding any new entries. .. tabs-drivers:: @@ -313,7 +314,7 @@ Some Property Types are Only Mutable in a Write Transaction ``````````````````````````````````````````````````````````` Some property types are only mutable in a write transaction. For example, -you can instantiate an object with a :ref:`Set ` +you can instantiate an object with a Set property, but you can only set that property's value in a write transaction. You cannot initialize the object with a value for that property unless you do so inside a write transaction. diff --git a/source/sdk/crud/create/create-object-types.txt b/source/sdk/crud/create/create-object-types.txt index 24680920b1..6c5c6b90c7 100644 --- a/source/sdk/crud/create/create-object-types.txt +++ b/source/sdk/crud/create/create-object-types.txt @@ -6,7 +6,7 @@ Create Specific Object Types .. meta:: :description: Learn how to create specific types of objects with Atlas Device SDK, including constraints for certain object types. - :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + :keywords: Realm, C++ SDK, .NET SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre @@ -118,7 +118,7 @@ of the former product name, Realm Database. Model ````` -For more information about modeling an object, refer to: +For more information about modeling an object, refer to :ref:`sdks-object-models`. .. include:: /includes/sdk-examples/crud/create-realm-object-model.rst @@ -201,7 +201,7 @@ different parent object or share it between multiple parent objects. Model ````` -For more information about modeling an embedded object, refer to: +For more information about modeling an embedded object, refer to :ref:`sdks-embedded-objects`. .. include:: /includes/sdk-examples/crud/create-embedded-object-model.rst @@ -275,7 +275,7 @@ refer to :ref:`sdks-stream-data-to-atlas`. Model ````` -For more information about modeling an asymmetric object, refer to: +For more information about modeling an asymmetric object, refer to :ref:`sdks-asymmetric-objects`. .. include:: /includes/sdk-examples/crud/create-asymmetric-object-model.rst @@ -346,4 +346,7 @@ The following image shows the results of creating these two company objects: Model ````` +For more information about modeling a geospatial object, refer to +:ref:`sdks-define-geospatial-object`. + .. include:: /includes/sdk-examples/crud/create-geospatial-data-model.rst diff --git a/source/sdk/crud/create/create-property-types.txt b/source/sdk/crud/create/create-property-types.txt index 9dfbe14789..b83ffe15ba 100644 --- a/source/sdk/crud/create/create-property-types.txt +++ b/source/sdk/crud/create/create-property-types.txt @@ -6,7 +6,7 @@ Create Specific Property Types .. meta:: :description: Learn how to create specific property types with Atlas Device SDK. - :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + :keywords: Realm, C++ SDK, Flutter SDK, .NET SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre @@ -42,7 +42,7 @@ objects, refer to :ref:`sdks-create-object-methods`. .. _sdks-create-special-property-types: -Create Special Property Types +Create Special Properties ----------------------------- Depending on how you define your object type, you might have properties @@ -118,10 +118,10 @@ For a list of the value types that a mixed property can hold, refer to .. _sdks-create-counter-property-type: -Create a Counter Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create a Counter Property +~~~~~~~~~~~~~~~~~~~~~~~~~ -Some of the SDKs provide a special property type you can use as a logical +Some of the SDKs provide a special property type that you can use as a logical counter. .. tabs-drivers:: @@ -180,8 +180,8 @@ counter. .. _sdks-create-timestamp-property-type: -Create a Timestamp Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create a Timestamp Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabs-drivers:: @@ -239,8 +239,8 @@ Create a Timestamp Property Type .. _sdks-create-object-id-property-type: -Create an Object ID Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create an Object ID Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabs-drivers:: @@ -292,8 +292,8 @@ Create an Object ID Property Type .. _sdks-create-uuid-property-type: -Create a UUID Property Type -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Create a UUID Property +~~~~~~~~~~~~~~~~~~~~~~ .. tabs-drivers:: @@ -339,10 +339,10 @@ Create a UUID Property Type .. _sdks-create-collection-property-types: -Create Collection Property Types --------------------------------- +Create Collection Properties +---------------------------- -The SDK provides a few collection type properties: +The SDK provides the following collection type properties: - List - Set @@ -561,10 +561,10 @@ value types that a dictionary property can hold, refer to .. _sdks-create-relationship-property-types: -Create Relationship Property Types ----------------------------------- +Create Relationship Properties +------------------------------ -When you have properties whose type references another SDK object, this creates +When you have a property whose type references another SDK object, this creates a relationship between the objects. This can be a to-one, to-many, or inverse relationship. For more information about relationships, refer to :ref:`sdks-relationships`. From ba686c79316c6f3df7a690a3a12bfa38178ff673 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 25 Jun 2024 13:21:18 -0400 Subject: [PATCH 32/37] Fix snooty build errors and make missing placeholders non-copyable --- .../crud/create-asymmetric-object-model.rst | 3 +++ .../sdk-examples/crud/create-asymmetric-object.rst | 5 +++++ .../crud/create-copy-object-to-another-database.rst | 10 ++++++++++ .../sdk-examples/crud/create-counter-property-type.rst | 8 ++++++-- .../sdk-examples/crud/create-dictionary-property.rst | 6 ++++++ .../sdk-examples/crud/create-embedded-object-model.rst | 7 +++++-- .../sdk-examples/crud/create-embedded-object.rst | 4 ++-- .../sdk-examples/crud/create-geospatial-data-model.rst | 4 ++++ .../crud/create-geospatial-data-object.rst | 5 +++++ .../crud/create-initialize-objects-with-value.rst | 8 ++++++++ .../sdk-examples/crud/create-inverse-relationship.rst | 8 ++++++++ .../sdk-examples/crud/create-list-property.rst | 7 +++++++ .../sdk-examples/crud/create-mixed-property-type.rst | 5 +++++ .../sdk-examples/crud/create-multiple-objects.rst | 9 +++++++++ .../crud/create-object-id-property-type.rst | 9 +++++++++ .../sdk-examples/crud/create-objects-from-json.rst | 8 ++++++-- .../sdk-examples/crud/create-objects-in-background.rst | 7 +++++++ .../sdk-examples/crud/create-or-update-object.rst | 2 ++ .../sdk-examples/crud/create-realm-object-model.rst | 6 ++++++ .../includes/sdk-examples/crud/create-realm-object.rst | 1 + .../includes/sdk-examples/crud/create-set-property.rst | 6 ++++++ .../crud/create-timestamp-property-type.rst | 8 ++++++++ .../sdk-examples/crud/create-to-many-relationship.rst | 8 ++++++++ .../sdk-examples/crud/create-to-one-relationship.rst | 8 ++++++++ .../sdk-examples/crud/create-unmanaged-object.rst | 9 +++++++++ .../sdk-examples/crud/create-uuid-property-type.rst | 7 +++++++ source/sdk/crud/create/create-property-types.txt | 4 ++-- source/sdk/quick-start.txt | 2 +- 28 files changed, 163 insertions(+), 11 deletions(-) diff --git a/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst b/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst index f05116c5e1..b115ea6477 100644 --- a/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst +++ b/source/includes/sdk-examples/crud/create-asymmetric-object-model.rst @@ -12,6 +12,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -25,12 +26,14 @@ .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | diff --git a/source/includes/sdk-examples/crud/create-asymmetric-object.rst b/source/includes/sdk-examples/crud/create-asymmetric-object.rst index 26bdca8d65..c9d7c2dc1d 100644 --- a/source/includes/sdk-examples/crud/create-asymmetric-object.rst +++ b/source/includes/sdk-examples/crud/create-asymmetric-object.rst @@ -12,6 +12,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -24,18 +25,21 @@ .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -49,6 +53,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | diff --git a/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst b/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst index ea9861cca1..dcc256a747 100644 --- a/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst +++ b/source/includes/sdk-examples/crud/create-copy-object-to-another-database.rst @@ -6,57 +6,67 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example.kt :language: kotlin + :copyable: false - id: objectivec content: | .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-counter-property-type.rst b/source/includes/sdk-examples/crud/create-counter-property-type.rst index 2e6c0758d6..341c05b2fc 100644 --- a/source/includes/sdk-examples/crud/create-counter-property-type.rst +++ b/source/includes/sdk-examples/crud/create-counter-property-type.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -18,26 +19,26 @@ .. literalinclude:: /examples/MissingPlaceholders/api.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-increment-decrement.java :language: java - :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-increment-decrement.kt :language: kotlin - :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/api.js :language: javascript + :copyable: false - id: kotlin content: | @@ -50,15 +51,18 @@ .. literalinclude:: /examples/MissingPlaceholders/api.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/api.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/api.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-dictionary-property.rst b/source/includes/sdk-examples/crud/create-dictionary-property.rst index 0bf5258739..3d42c38a6b 100644 --- a/source/includes/sdk-examples/crud/create-dictionary-property.rst +++ b/source/includes/sdk-examples/crud/create-dictionary-property.rst @@ -12,24 +12,28 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | @@ -48,6 +52,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | @@ -60,3 +65,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-embedded-object-model.rst b/source/includes/sdk-examples/crud/create-embedded-object-model.rst index 487ad17016..de1a91108d 100644 --- a/source/includes/sdk-examples/crud/create-embedded-object-model.rst +++ b/source/includes/sdk-examples/crud/create-embedded-object-model.rst @@ -18,20 +18,19 @@ .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/EmbeddedObjects/DefineEmbeddedObjects.java :language: java - :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/EmbeddedObjects/DefineEmbeddedObjects.kt :language: kotlin - :copyable: false - id: javascript content: | @@ -45,21 +44,25 @@ .. literalinclude:: /examples/MissingPlaceholders/example.kt :language: kotlin + :copyable: false - id: objectivec content: | .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-embedded-object.rst b/source/includes/sdk-examples/crud/create-embedded-object.rst index c989b7b407..6626e84ab6 100644 --- a/source/includes/sdk-examples/crud/create-embedded-object.rst +++ b/source/includes/sdk-examples/crud/create-embedded-object.rst @@ -18,20 +18,19 @@ .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/EmbeddedObjects/CreateEmbeddedObject.java :language: java - :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/EmbeddedObjects/CreateEmbeddedObject.kt :language: kotlin - :copyable: false - id: javascript content: | @@ -63,3 +62,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-geospatial-data-model.rst b/source/includes/sdk-examples/crud/create-geospatial-data-model.rst index f042b1640c..4b9751ab71 100644 --- a/source/includes/sdk-examples/crud/create-geospatial-data-model.rst +++ b/source/includes/sdk-examples/crud/create-geospatial-data-model.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -25,12 +26,14 @@ .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | @@ -50,6 +53,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | diff --git a/source/includes/sdk-examples/crud/create-geospatial-data-object.rst b/source/includes/sdk-examples/crud/create-geospatial-data-object.rst index 3633b9f35b..6d848c390b 100644 --- a/source/includes/sdk-examples/crud/create-geospatial-data-object.rst +++ b/source/includes/sdk-examples/crud/create-geospatial-data-object.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -24,12 +25,14 @@ .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | @@ -48,12 +51,14 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | diff --git a/source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst b/source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst index 7b97b86286..2a224154bd 100644 --- a/source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst +++ b/source/includes/sdk-examples/crud/create-initialize-objects-with-value.rst @@ -6,42 +6,49 @@ .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/api.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/api.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/api.js :language: javascript + :copyable: false - id: kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api.kt :language: kotlin + :copyable: false - id: objectivec content: | @@ -72,3 +79,4 @@ .. literalinclude:: /examples/MissingPlaceholders/api.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-inverse-relationship.rst b/source/includes/sdk-examples/crud/create-inverse-relationship.rst index afb2c9e763..1e05ec7027 100644 --- a/source/includes/sdk-examples/crud/create-inverse-relationship.rst +++ b/source/includes/sdk-examples/crud/create-inverse-relationship.rst @@ -12,30 +12,35 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -48,15 +53,18 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-list-property.rst b/source/includes/sdk-examples/crud/create-list-property.rst index 23cbbc56e0..807c2a1125 100644 --- a/source/includes/sdk-examples/crud/create-list-property.rst +++ b/source/includes/sdk-examples/crud/create-list-property.rst @@ -12,6 +12,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -24,18 +25,21 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -48,15 +52,18 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-mixed-property-type.rst b/source/includes/sdk-examples/crud/create-mixed-property-type.rst index 509d6ad17e..1bbd9670e3 100644 --- a/source/includes/sdk-examples/crud/create-mixed-property-type.rst +++ b/source/includes/sdk-examples/crud/create-mixed-property-type.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -24,12 +25,14 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | @@ -48,6 +51,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | @@ -60,3 +64,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-multiple-objects.rst b/source/includes/sdk-examples/crud/create-multiple-objects.rst index e753cac0d6..41ac6c9a07 100644 --- a/source/includes/sdk-examples/crud/create-multiple-objects.rst +++ b/source/includes/sdk-examples/crud/create-multiple-objects.rst @@ -6,12 +6,14 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -24,39 +26,46 @@ .. literalinclude:: /examples/MissingPlaceholders/api.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/api.js :language: javascript + :copyable: false - id: kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/api.kt :language: kotlin + :copyable: false - id: objectivec content: | .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/api.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-object-id-property-type.rst b/source/includes/sdk-examples/crud/create-object-id-property-type.rst index 5c89b1e8b4..c4d65efb2e 100644 --- a/source/includes/sdk-examples/crud/create-object-id-property-type.rst +++ b/source/includes/sdk-examples/crud/create-object-id-property-type.rst @@ -6,12 +6,14 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -24,39 +26,46 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example.kt :language: kotlin + :copyable: false - id: objectivec content: | .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-objects-from-json.rst b/source/includes/sdk-examples/crud/create-objects-from-json.rst index b6fd5d3332..023e01669d 100644 --- a/source/includes/sdk-examples/crud/create-objects-from-json.rst +++ b/source/includes/sdk-examples/crud/create-objects-from-json.rst @@ -6,44 +6,47 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.create-an-object-json.java :language: java - :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/generated/java/local/WritesTest.snippet.create-an-object-json.kt :language: kotlin - :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example.kt :language: kotlin + :copyable: false - id: objectivec content: | @@ -62,3 +65,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-objects-in-background.rst b/source/includes/sdk-examples/crud/create-objects-in-background.rst index 70a5bfaa48..c03f01469b 100644 --- a/source/includes/sdk-examples/crud/create-objects-in-background.rst +++ b/source/includes/sdk-examples/crud/create-objects-in-background.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -24,30 +25,35 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example.kt :language: kotlin + :copyable: false - id: objectivec content: | .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | @@ -60,3 +66,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-or-update-object.rst b/source/includes/sdk-examples/crud/create-or-update-object.rst index 22f6a0b00a..c7ba1347cc 100644 --- a/source/includes/sdk-examples/crud/create-or-update-object.rst +++ b/source/includes/sdk-examples/crud/create-or-update-object.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -63,3 +64,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-realm-object-model.rst b/source/includes/sdk-examples/crud/create-realm-object-model.rst index 1518ee892e..1cf3f1ae7c 100644 --- a/source/includes/sdk-examples/crud/create-realm-object-model.rst +++ b/source/includes/sdk-examples/crud/create-realm-object-model.rst @@ -24,18 +24,21 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -48,15 +51,18 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-realm-object.rst b/source/includes/sdk-examples/crud/create-realm-object.rst index 033ac37b58..bbb27ba0a4 100644 --- a/source/includes/sdk-examples/crud/create-realm-object.rst +++ b/source/includes/sdk-examples/crud/create-realm-object.rst @@ -63,3 +63,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-set-property.rst b/source/includes/sdk-examples/crud/create-set-property.rst index 8eb739aba9..01f035f230 100644 --- a/source/includes/sdk-examples/crud/create-set-property.rst +++ b/source/includes/sdk-examples/crud/create-set-property.rst @@ -12,24 +12,28 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | @@ -48,6 +52,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | @@ -60,3 +65,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-timestamp-property-type.rst b/source/includes/sdk-examples/crud/create-timestamp-property-type.rst index 85eff10c22..09737ce38d 100644 --- a/source/includes/sdk-examples/crud/create-timestamp-property-type.rst +++ b/source/includes/sdk-examples/crud/create-timestamp-property-type.rst @@ -6,12 +6,14 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -24,18 +26,21 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -48,15 +53,18 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-to-many-relationship.rst b/source/includes/sdk-examples/crud/create-to-many-relationship.rst index bdaf66e034..c070f12221 100644 --- a/source/includes/sdk-examples/crud/create-to-many-relationship.rst +++ b/source/includes/sdk-examples/crud/create-to-many-relationship.rst @@ -12,30 +12,35 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -48,15 +53,18 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-to-one-relationship.rst b/source/includes/sdk-examples/crud/create-to-one-relationship.rst index 4d8901ff19..7bf9025f03 100644 --- a/source/includes/sdk-examples/crud/create-to-one-relationship.rst +++ b/source/includes/sdk-examples/crud/create-to-one-relationship.rst @@ -12,30 +12,35 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/example.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -48,15 +53,18 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-unmanaged-object.rst b/source/includes/sdk-examples/crud/create-unmanaged-object.rst index 4b60290825..c398f0a513 100644 --- a/source/includes/sdk-examples/crud/create-unmanaged-object.rst +++ b/source/includes/sdk-examples/crud/create-unmanaged-object.rst @@ -6,36 +6,42 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/api.cs :language: csharp + :copyable: false - id: dart content: | .. literalinclude:: /examples/MissingPlaceholders/api.dart :language: dart + :copyable: false - id: java content: | .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | .. literalinclude:: /examples/MissingPlaceholders/api.js :language: javascript + :copyable: false - id: kotlin content: | @@ -55,15 +61,18 @@ .. literalinclude:: /examples/MissingPlaceholders/api.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/api.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/api.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/crud/create-uuid-property-type.rst b/source/includes/sdk-examples/crud/create-uuid-property-type.rst index fa168dd756..febb9e9b55 100644 --- a/source/includes/sdk-examples/crud/create-uuid-property-type.rst +++ b/source/includes/sdk-examples/crud/create-uuid-property-type.rst @@ -6,12 +6,14 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cpp :language: cpp + :copyable: false - id: csharp content: | .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -24,12 +26,14 @@ .. literalinclude:: /examples/MissingPlaceholders/example.java :language: java + :copyable: false - id: java-kotlin content: | .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt :language: kotlin + :copyable: false - id: javascript content: | @@ -48,15 +52,18 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/example.swift :language: swift + :copyable: false - id: typescript content: | .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/sdk/crud/create/create-property-types.txt b/source/sdk/crud/create/create-property-types.txt index b83ffe15ba..8835b5b5f7 100644 --- a/source/sdk/crud/create/create-property-types.txt +++ b/source/sdk/crud/create/create-property-types.txt @@ -43,7 +43,7 @@ objects, refer to :ref:`sdks-create-object-methods`. .. _sdks-create-special-property-types: Create Special Properties ------------------------------ +------------------------- Depending on how you define your object type, you might have properties that are special SDK-specific types. These may be custom data types, or @@ -728,4 +728,4 @@ the inverse relationship property to get the child objects. However, you .. tab:: :tabid: typescript -.. include:: /includes/sdk-examples/crud/create-inverse-relationship.rst \ No newline at end of file +.. include:: /includes/sdk-examples/crud/create-inverse-relationship.rst diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index eb855cd9aa..2a102d196c 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -184,7 +184,7 @@ To instantiate a new object and add it to the database in a write block: .. include:: /includes/sdk-examples/quick-start/quick-start-create-objects.rst -For more information, refer to :ref:`sdks-crud-create`. +For more information, refer to :ref:`sdks-create-object-methods`. Read and Filter ~~~~~~~~~~~~~~~ From 4a4640f1098576b725abde0564f0738af34d74dc Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 25 Jun 2024 13:51:05 -0400 Subject: [PATCH 33/37] Try include with proper section headers --- .../crud/create-realm-object-description.rst | 7 ------- .../create-objects-in-background-description.rst | 16 ++++++++++------ 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/source/includes/api-details/dart/crud/create-realm-object-description.rst b/source/includes/api-details/dart/crud/create-realm-object-description.rst index fbcfcee003..b5aac7f6e7 100644 --- a/source/includes/api-details/dart/crud/create-realm-object-description.rst +++ b/source/includes/api-details/dart/crud/create-realm-object-description.rst @@ -8,10 +8,3 @@ Once you've opened a database, you can create objects within it using a }); You can also return values from the write transaction callback function. - -.. warning:: Write RealmObjects to One Realm File - - You can only write ``RealmObjects`` to a single database file. - If you already wrote a ``RealmObject`` to one database file, - the SDK throws a ``RealmException`` if you try to write it to another - database. diff --git a/source/includes/api-details/swift/crud/create-objects-in-background-description.rst b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst index 705d193e3d..5f4a485bef 100644 --- a/source/includes/api-details/swift/crud/create-objects-in-background-description.rst +++ b/source/includes/api-details/swift/crud/create-objects-in-background-description.rst @@ -1,4 +1,5 @@ -**Use the Background Write API** +Use the Background Write API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can add, modify, or delete objects in the background using :swift-sdk:`writeAsync `. @@ -15,7 +16,7 @@ Things to consider when performing background writes: - You can explicitly commit or cancel transactions Wait for Async Writes to Complete -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +````````````````````````````````` The SDK provides a ``Bool`` to signal whether the database is currently performing an async write. The @@ -32,7 +33,7 @@ While this is true, this blocks closing or :swift-sdk:`invalidating ` the database. Commit or Cancel an Async Write -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``````````````````````````````` To complete an async write, you or the SDK must call either: @@ -80,9 +81,11 @@ cancels only an ``onComplete`` block you may have passed to ``commitAsyncWrite``. It does not cancel the commit itself. You need the ID of the ``beginAsyncWrite`` or the ``commitAsyncWrite`` you want to cancel. -**Use Swift Concurrency Features** +Use Swift Concurrency Features +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -*Write to an Actor-Isolated Realm* +Write to an Actor-Isolated Realm +```````````````````````````````` You can use Swift concurrency features to write asynchronously to an actor-isolated database. @@ -103,7 +106,8 @@ This operation does not block or perform I/O on the calling thread. For more information about writing to a database using Swift concurrency features, refer to :ref:`swift-actor-isolated-realm`. -*Perform Writes using Async/Await Syntax* +Perform Writes using Async/Await Syntax +``````````````````````````````````````` The :swift-sdk:`asyncWrite() ` API allows for performing async writes using Swift async/await syntax. From d91db0434143a3b3689f00883c25f29baf4cfc71 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 25 Jun 2024 13:57:11 -0400 Subject: [PATCH 34/37] Try Create as landing page with content --- snooty.toml | 3 + source/sdk/crud.txt | 2 +- source/sdk/crud/create.txt | 615 +++++++++++++++++- source/sdk/crud/create/create-methods.txt | 608 ----------------- .../sdk/crud/create/create-object-types.txt | 2 +- .../sdk/crud/create/create-property-types.txt | 2 +- source/sdk/quick-start.txt | 2 +- 7 files changed, 613 insertions(+), 621 deletions(-) delete mode 100644 source/sdk/crud/create/create-methods.txt diff --git a/snooty.toml b/snooty.toml index e6939c0f89..e44369c119 100644 --- a/snooty.toml +++ b/snooty.toml @@ -9,6 +9,9 @@ intersphinx = [ # These are the pages that open when you click on them (instead of just being containers) toc_landing_pages = [ + # New IA + "/sdk/crud/create", + # Tutorial "/tutorial", # SDKs diff --git a/source/sdk/crud.txt b/source/sdk/crud.txt index 2505e09065..1dd90517b4 100644 --- a/source/sdk/crud.txt +++ b/source/sdk/crud.txt @@ -15,7 +15,7 @@ Read and Write Data The following pages contain information about how to read and write data, manage objects across threads, and use the Atlas Device SDK query engines: -- :ref:`sdks-create-object-methods` +- :ref:`sdks-crud-create` - :ref:`sdks-crud-read` - :ref:`sdks-crud-update` - :ref:`sdks-crud-delete` diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index 659c13a44c..b5fb8137cb 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -1,3 +1,5 @@ +.. _sdks-crud-create: + ============== Create Objects ============== @@ -5,14 +7,609 @@ Create Objects .. toctree:: :titlesonly: - Create Object Methods - Create Object Types - Create Property Types + Create Objects + Create Properties + +.. meta:: + :description: Learn about performing write transactions and the different ways to create objects with Atlas Device SDK. + :keywords: Realm, C++ SDK, Flutter SDK, .NET SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example + +.. 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: 2 + :class: singlecol + +.. tabs-selector:: drivers + +This page describes the concepts of write transactions and managed objects in +a database, then explains how to create and persist a new object to a local or +synced database using Atlas Device SDK. To learn more about object models and +how to define them, refer to :ref:`sdks-object-models`. + +You can create objects whose object type is managed by the database instance. +For more information, refer to +:ref:`sdks-configure-and-open-database` or +:ref:`sdks-configure-and-open-synced-database`. + +.. note:: Write to a Synced Database + + The syntax to write a new object to the database is the same for a local or + a synced database. However, there are additional considerations that determine + whether the write operation in a synced database is successful. For more + information, refer to :ref:`sdks-write-synced-database`. + +.. _sdks-write-transactions: + +Write Transactions +------------------ + +The Atlas Device SDK persistence layer handles writes in terms of transactions. +All writes must happen within a transaction. A **transaction** is a list of +read and write operations that the database treats as a single indivisible +operation: either *all* of the operations succeed or *none* of the operations +in the transaction take effect. + +The SDK represents each transaction as a callback function +that contains zero or more read and write operations. To run +a transaction, you define a transaction callback and pass it to +one of the database's write methods. Within this callback, you can access a +database instance and then create, read, update, and delete objects within the +database. + +A database file allows only one open write transaction at a time. The SDK +blocks other writes on other threads until the open transaction on the database +file is complete. This means there is never a race condition when reading +values from the database within a transaction. + +When you are done with your transaction, the SDK either commits it or cancels +it: + +- When the SDK commits a write transaction, it writes all changes to disk. For + synced databases, the SDK then queues the change for synchronization with the + backend. +- When the SDK cancels a write transaction or an operation in + the transaction causes an error, it discards all changes. + +.. _sdks-managed-vs-unmanaged-objects: + +Managed and Unmanaged Objects +----------------------------- + +The SDK's APIs may refer to objects as managed or unmanaged. When you create +an object with the SDK, it is unmanaged until it is added to the database, +which creates a managed instance. + +- **Managed objects** are SDK objects that persist in a database instance. + Managed objects can only be accessed from an open database file. They can be + updated with changes within write transactions as long as that database + remains open. Managed objects are tied to the database instance from which + they originated and cannot be directly written to another database. However, + some of the SDKs supply a method to copy managed objects from one database + file to another. Refer to the :ref:`sdks-create-copy-object-to-another-database` + section on this page. + + You can use the SDK's APIs with managed objects. For example, managed + objects can have relationships with other objects and you can observe them + for changes. You can also create an unmanaged copy of a managed object. + Refer to the :ref:`Create an Unmanaged Copy of an Object or Collection + ` section on this page. + +- **Unmanaged objects** are SDK objects that behave like normal objects, + but they are not persisted in the database. All SDK objects are unmanaged + until you add them to a database within a write transaction. + You cannot use the SDK's APIs with unmanaged objects or observe them for + changes. + +Create Object Methods +--------------------- + +The SDK provides a variety of methods to create objects and perform write +operations. + +.. _sdks-create-one-object: + +Create One Object +~~~~~~~~~~~~~~~~~ + +To create a new object and persist it to the database: + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-procedure.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-procedure.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-procedure.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-procedure.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-procedure.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-procedure.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-procedure.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-procedure.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-procedure.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-procedure.rst + +.. include:: /includes/sdk-examples/crud/create-realm-object.rst + +You can also upsert into a database using specific criteria. Refer to the +:ref:`sdks-upsert-an-object` section on this page. + +.. _sdks-create-multiple-objects: + +Create Multiple Objects +~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide a dedicated API to create multiple objects from +a sequence or collection. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-multiple-objects-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst + +.. include:: /includes/sdk-examples/crud/create-multiple-objects.rst + +.. _sdks-upsert-an-object: + +Create or Update an Object (Upsert) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An **upsert** is a write operation that either inserts a new object +with a given primary key or updates an existing object that already has +that primary key. We call this an upsert because it is an "**update** or +**insert**" operation. This is useful when an object may or may not +already exist, such as when bulk importing a dataset into an existing +database. Upserting lets you update existing entries while adding any new entries. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/api-not-supported-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-or-update-object-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-or-update-object-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-or-update-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst + +.. include:: /includes/sdk-examples/crud/create-or-update-object.rst + +.. _sdks-create-objects-with-value: + +Initialize Objects with a Value +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide specific methods to initialize objects with a value. +Others use language-idiomatic methods to set the values of objects during +initialization. + +Some Property Types are Only Mutable in a Write Transaction +``````````````````````````````````````````````````````````` + +Some property types are only mutable in a write transaction. For example, +you can instantiate an object with a Set +property, but you can only set that property's value in a write transaction. +You cannot initialize the object with a value for that property unless +you do so inside a write transaction. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst + +.. include:: /includes/sdk-examples/crud/create-initialize-objects-with-value.rst + +.. _sdks-create-objects-from-json: + +Create Objects from JSON +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-objects-from-json-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst + +.. include:: /includes/sdk-examples/crud/create-objects-from-json.rst + +.. _sdks-create-unmanaged-copy: + +Create an Unmanaged Copy of an Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a +managed object or collection. In other SDKs, this API is not needed or not +currently implemented. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst + +.. include:: /includes/sdk-examples/crud/create-unmanaged-object.rst + +.. _sdks-create-copy-object-to-another-database: + +Copy an Object to Another Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can copy objects that are managed by one database instance to another +database instance. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst + +.. include:: /includes/sdk-examples/crud/create-copy-object-to-another-database.rst + +.. _sdks-create-objects-in-background: + +Create Objects in the Background +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When performing large write operations, you may want to create objects in the +background. This avoids blocking the UI thread while performing large write +operations. This is particularly useful when using Device Sync, where you don't +know when and for how long the Sync client will be writing. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/create-objects-in-background-description.rst + + .. tab:: + :tabid: typescript -The following pages contain information about how to perform write -transactions, how to create specific object types, and how to create specific -property types using Atlas Device SDK. +.. include:: /includes/sdk-examples/crud/create-objects-in-background.rst -- :ref:`Create Object Methods ` -- :ref:`Create Object Types ` -- :ref:`Create Property Types ` diff --git a/source/sdk/crud/create/create-methods.txt b/source/sdk/crud/create/create-methods.txt deleted file mode 100644 index fcdc41de06..0000000000 --- a/source/sdk/crud/create/create-methods.txt +++ /dev/null @@ -1,608 +0,0 @@ -.. _sdks-create-object-methods: - -===================== -Create Object Methods -===================== - -.. meta:: - :description: Learn about performing write transactions and the different ways to create objects with Atlas Device SDK. - :keywords: Realm, C++ SDK, Flutter SDK, .NET SDK, Kotlin SDK, Java SDK, Node.js SDK, Swift SDK, code example - -.. 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: 2 - :class: singlecol - -.. tabs-selector:: drivers - -This page describes the concepts of write transactions and managed objects in -a database, then explains how to create and persist a new object to a local or -synced database using Atlas Device SDK. To learn more about object models and -how to define them, refer to :ref:`sdks-object-models`. - -You can create objects whose object type is managed by the database instance. -For more information, refer to -:ref:`sdks-configure-and-open-database` or -:ref:`sdks-configure-and-open-synced-database`. - -.. note:: Write to a Synced Database - - The syntax to write a new object to the database is the same for a local or - a synced database. However, there are additional considerations that determine - whether the write operation in a synced database is successful. For more - information, refer to :ref:`sdks-write-synced-database`. - -.. _sdks-write-transactions: - -Write Transactions ------------------- - -The Atlas Device SDK persistence layer handles writes in terms of transactions. -All writes must happen within a transaction. A **transaction** is a list of -read and write operations that the database treats as a single indivisible -operation: either *all* of the operations succeed or *none* of the operations -in the transaction take effect. - -The SDK represents each transaction as a callback function -that contains zero or more read and write operations. To run -a transaction, you define a transaction callback and pass it to -one of the database's write methods. Within this callback, you can access a -database instance and then create, read, update, and delete objects within the -database. - -A database file allows only one open write transaction at a time. The SDK -blocks other writes on other threads until the open transaction on the database -file is complete. This means there is never a race condition when reading -values from the database within a transaction. - -When you are done with your transaction, the SDK either commits it or cancels -it: - -- When the SDK commits a write transaction, it writes all changes to disk. For - synced databases, the SDK then queues the change for synchronization with the - backend. -- When the SDK cancels a write transaction or an operation in - the transaction causes an error, it discards all changes. - -.. _sdks-managed-vs-unmanaged-objects: - -Managed and Unmanaged Objects ------------------------------ - -The SDK's APIs may refer to objects as managed or unmanaged. When you create -an object with the SDK, it is unmanaged until it is added to the database, -which creates a managed instance. - -- **Managed objects** are SDK objects that persist in a database instance. - Managed objects can only be accessed from an open database file. They can be - updated with changes within write transactions as long as that database - remains open. Managed objects are tied to the database instance from which - they originated and cannot be directly written to another database. However, - some of the SDKs supply a method to copy managed objects from one database - file to another. Refer to the :ref:`sdks-create-copy-object-to-another-database` - section on this page. - - You can use the SDK's APIs with managed objects. For example, managed - objects can have relationships with other objects and you can observe them - for changes. You can also create an unmanaged copy of a managed object. - Refer to the :ref:`Create an Unmanaged Copy of an Object or Collection - ` section on this page. - -- **Unmanaged objects** are SDK objects that behave like normal objects, - but they are not persisted in the database. All SDK objects are unmanaged - until you add them to a database within a write transaction. - You cannot use the SDK's APIs with unmanaged objects or observe them for - changes. - -Create Object Methods ---------------------- - -The SDK provides a variety of methods to create objects and perform write -operations. - -.. _sdks-create-one-object: - -Create One Object -~~~~~~~~~~~~~~~~~ - -To create a new object and persist it to the database: - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-procedure.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-procedure.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-procedure.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-procedure.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-procedure.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-procedure.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-procedure.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-procedure.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-procedure.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-procedure.rst - -.. include:: /includes/sdk-examples/crud/create-realm-object.rst - -You can also upsert into a database using specific criteria. Refer to the -:ref:`sdks-upsert-an-object` section on this page. - -.. _sdks-create-multiple-objects: - -Create Multiple Objects -~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide a dedicated API to create multiple objects from -a sequence or collection. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-multiple-objects-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst - -.. include:: /includes/sdk-examples/crud/create-multiple-objects.rst - -.. _sdks-upsert-an-object: - -Create or Update an Object (Upsert) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -An **upsert** is a write operation that either inserts a new object -with a given primary key or updates an existing object that already has -that primary key. We call this an upsert because it is an "**update** or -**insert**" operation. This is useful when an object may or may not -already exist, such as when bulk importing a dataset into an existing -database. Upserting lets you update existing entries while adding any new entries. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/api-not-supported-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-or-update-object-java-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-or-update-object-kotlin-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/javascript/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-or-update-object-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/typescript/crud/create-or-update-object-description.rst - -.. include:: /includes/sdk-examples/crud/create-or-update-object.rst - -.. _sdks-create-objects-with-value: - -Initialize Objects with a Value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide specific methods to initialize objects with a value. -Others use language-idiomatic methods to set the values of objects during -initialization. - -Some Property Types are Only Mutable in a Write Transaction -``````````````````````````````````````````````````````````` - -Some property types are only mutable in a write transaction. For example, -you can instantiate an object with a Set -property, but you can only set that property's value in a write transaction. -You cannot initialize the object with a value for that property unless -you do so inside a write transaction. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-initialize-objects-with-value-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-initialize-objects-with-value-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst - -.. include:: /includes/sdk-examples/crud/create-initialize-objects-with-value.rst - -.. _sdks-create-objects-from-json: - -Create Objects from JSON -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-objects-from-json-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-objects-from-json-missing-example.rst - -.. include:: /includes/sdk-examples/crud/create-objects-from-json.rst - -.. _sdks-create-unmanaged-copy: - -Create an Unmanaged Copy of an Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some of the SDKs provide APIs to create an unmanaged, in-memory copy of a -managed object or collection. In other SDKs, this API is not needed or not -currently implemented. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/cpp/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-unmanaged-copy-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst - -.. include:: /includes/sdk-examples/crud/create-unmanaged-object.rst - -.. _sdks-create-copy-object-to-another-database: - -Copy an Object to Another Database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can copy objects that are managed by one database instance to another -database instance. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst - - .. tab:: - :tabid: java - - .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: java-kotlin - - .. include:: /includes/api-details/java/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: javascript - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst - - .. tab:: - :tabid: kotlin - - .. include:: /includes/api-details/kotlin/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: objectivec - - .. include:: /includes/api-details/objectivec/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-copy-object-to-another-database-description.rst - - .. tab:: - :tabid: typescript - - .. include:: /includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst - -.. include:: /includes/sdk-examples/crud/create-copy-object-to-another-database.rst - -.. _sdks-create-objects-in-background: - -Create Objects in the Background -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When performing large write operations, you may want to create objects in the -background. This avoids blocking the UI thread while performing large write -operations. This is particularly useful when using Device Sync, where you don't -know when and for how long the Sync client will be writing. - -.. tabs-drivers:: - - .. tab:: - :tabid: cpp-sdk - - .. tab:: - :tabid: csharp - - .. include:: /includes/api-details/csharp/crud/create-objects-in-background-description.rst - - .. tab:: - :tabid: dart - - .. include:: /includes/api-details/dart/crud/create-objects-in-background-description.rst - - .. tab:: - :tabid: java - - .. tab:: - :tabid: java-kotlin - - .. tab:: - :tabid: javascript - - .. tab:: - :tabid: kotlin - - .. tab:: - :tabid: objectivec - - .. tab:: - :tabid: swift - - .. include:: /includes/api-details/swift/crud/create-objects-in-background-description.rst - - .. tab:: - :tabid: typescript - -.. include:: /includes/sdk-examples/crud/create-objects-in-background.rst diff --git a/source/sdk/crud/create/create-object-types.txt b/source/sdk/crud/create/create-object-types.txt index 6c5c6b90c7..6520931df1 100644 --- a/source/sdk/crud/create/create-object-types.txt +++ b/source/sdk/crud/create/create-object-types.txt @@ -34,7 +34,7 @@ For more information, refer to :ref:`sdks-configure-and-open-synced-database`. For more information about write transactions and the methods you can use to -create an object, refer to :ref:`sdks-create-object-methods`. +create an object, refer to :ref:`sdks-crud-create`. For information about creating specific property types, including special types, collections, and relationship properties, refer to diff --git a/source/sdk/crud/create/create-property-types.txt b/source/sdk/crud/create/create-property-types.txt index 8835b5b5f7..b83b09aebb 100644 --- a/source/sdk/crud/create/create-property-types.txt +++ b/source/sdk/crud/create/create-property-types.txt @@ -38,7 +38,7 @@ For information about how to create specific types of objects, refer to :ref:`sdks-create-specific-object-types`. For information about write transactions and the methods you can use to create -objects, refer to :ref:`sdks-create-object-methods`. +objects, refer to :ref:`sdks-crud-create`. .. _sdks-create-special-property-types: diff --git a/source/sdk/quick-start.txt b/source/sdk/quick-start.txt index 2a102d196c..eb855cd9aa 100644 --- a/source/sdk/quick-start.txt +++ b/source/sdk/quick-start.txt @@ -184,7 +184,7 @@ To instantiate a new object and add it to the database in a write block: .. include:: /includes/sdk-examples/quick-start/quick-start-create-objects.rst -For more information, refer to :ref:`sdks-create-object-methods`. +For more information, refer to :ref:`sdks-crud-create`. Read and Filter ~~~~~~~~~~~~~~~ From 6239d0c79699aeeb3fbba89417f7b8df2a78d40e Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 25 Jun 2024 14:48:44 -0400 Subject: [PATCH 35/37] Fix snooty build error --- source/index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index.txt b/source/index.txt index 43c349c890..fb684ed1cf 100644 --- a/source/index.txt +++ b/source/index.txt @@ -144,7 +144,7 @@ other clients. .. step:: Read and Write Data - :ref:`Create `, :ref:`read `, + :ref:`Create `, :ref:`read `, :ref:`update `, and :ref:`delete ` objects from the device database. Filter data using the :ref:`query engines ` provided by the SDK. From fb89087fa0c30f2d7905d402082f4d6e684034aa Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 25 Jun 2024 15:04:06 -0400 Subject: [PATCH 36/37] Apply review feedback --- .../sdk/crud/create/create-object-types.txt | 5 +- .../sdk/crud/create/create-property-types.txt | 50 +++++++++++++++---- 2 files changed, 44 insertions(+), 11 deletions(-) diff --git a/source/sdk/crud/create/create-object-types.txt b/source/sdk/crud/create/create-object-types.txt index 6520931df1..0751637fae 100644 --- a/source/sdk/crud/create/create-object-types.txt +++ b/source/sdk/crud/create/create-object-types.txt @@ -58,8 +58,9 @@ schema when you open the database. Create a Realm Object ~~~~~~~~~~~~~~~~~~~~~ -The SDKs refer to the base object type as a Realm object. This is a legacy -of the former product name, Realm Database. +The SDK refers to the base object type as a Realm object. This identifies it +as an object type that can be managed by the device persistence layer, Realm +database. .. tabs-drivers:: diff --git a/source/sdk/crud/create/create-property-types.txt b/source/sdk/crud/create/create-property-types.txt index b83b09aebb..8de11cf3f4 100644 --- a/source/sdk/crud/create/create-property-types.txt +++ b/source/sdk/crud/create/create-property-types.txt @@ -422,19 +422,51 @@ For a list of the value types that a list property can hold, refer to .. include:: /includes/sdk-examples/crud/create-list-property.rst -.. _flutter-create-Uint8List-property-type: +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. _flutter-create-Uint8List-property-type: + + Create a Uint8List Property Type (Dart) + ``````````````````````````````````````` + + The Flutter SDK provides a ``Uint8List`` from Dart. For more details about + defining a ``Uint8List`` type, refer to + :ref:`dart-define-uint8list-property-type`. + + To add ``Uint8List`` to a Realm object, call ``Uint8List.fromList()`` on the data. + + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.binary-from-list.dart + :language: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript -Create a Uint8List Property Type (Dart) -``````````````````````````````````````` + .. tab:: + :tabid: kotlin -The Flutter SDK provides a ``Uint8List`` from Dart. For more details about -defining a ``Uint8List`` type, refer to -:ref:`dart-define-uint8list-property-type`. + .. tab:: + :tabid: objectivec -To add ``Uint8List`` to a Realm object, call ``Uint8List.fromList()`` on the data. + .. tab:: + :tabid: swift -.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.binary-from-list.dart - :language: dart + .. tab:: + :tabid: typescript .. _sdks-create-set-properties: From 19b0f29e979ccf1ac13bbd2d0a701a3362b4487c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 25 Jun 2024 15:29:35 -0400 Subject: [PATCH 37/37] Apply review feedback --- source/sdk/crud/create.txt | 15 ++++++++++++--- source/sdk/crud/create/create-property-types.txt | 3 ++- source/sdk/model-data/object-models.txt | 4 ++++ 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/source/sdk/crud/create.txt b/source/sdk/crud/create.txt index b5fb8137cb..444109eb7f 100644 --- a/source/sdk/crud/create.txt +++ b/source/sdk/crud/create.txt @@ -36,9 +36,10 @@ synced database using Atlas Device SDK. To learn more about object models and how to define them, refer to :ref:`sdks-object-models`. You can create objects whose object type is managed by the database instance. -For more information, refer to -:ref:`sdks-configure-and-open-database` or -:ref:`sdks-configure-and-open-synced-database`. +For more information, refer to: + +- With Sync: :ref:`sdks-configure-and-open-synced-database` +- Without Sync: :ref:`sdks-configure-and-open-database` .. note:: Write to a Synced Database @@ -384,6 +385,14 @@ you do so inside a write transaction. Create Objects from JSON ~~~~~~~~~~~~~~~~~~~~~~~~ +Working with JSON returned from an API is a common development use case. Most +of the supported SDK languages do not directly support creating objects from +JSON. However, you may use language or platform-idiomatic APIs to transform +JSON to a structure that matches your object schema, and create a matching +object. Or you may :ref:`model unstructured data ` +to work with **unstructured data** that is highly variable or whose structure +is unknown at runtime. + .. tabs-drivers:: .. tab:: diff --git a/source/sdk/crud/create/create-property-types.txt b/source/sdk/crud/create/create-property-types.txt index 8de11cf3f4..4229f7e3b4 100644 --- a/source/sdk/crud/create/create-property-types.txt +++ b/source/sdk/crud/create/create-property-types.txt @@ -474,7 +474,8 @@ Create Set Properties ~~~~~~~~~~~~~~~~~~~~~ Like their native counterparts, the SDK's set data type stores unique values. -These values may be of any supported type except another collection. +These values may be a Realm object or one of the supported data types. +It cannot be another collection, an embedded object, or an asymmetric object. The SDK uses the Set container type to define to-many relationships. A **to-many** relationship means that an object is related in a specific diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 729b0dc07a..9cb67efbdc 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -67,3 +67,7 @@ Define a Primary Key Placeholder for .NET nullability info, and any other SDKs with similar APIs/requirements +.. _sdks-model-unstructured-data: + +Model Unstructured Data +~~~~~~~~~~~~~~~~~~~~~~~