From 2b267efe8a785316c8fb6c1f3658aa628344476d Mon Sep 17 00:00:00 2001 From: cbullinger Date: Tue, 1 Aug 2023 11:05:04 -0400 Subject: [PATCH] Move embedded object content to respective CRUD pages --- .../sdk/kotlin/realm-database/crud/create.txt | 17 +++- .../sdk/kotlin/realm-database/crud/delete.txt | 35 +++++++- .../realm-database/crud/filter-data.txt | 0 .../sdk/kotlin/realm-database/crud/update.txt | 74 +++++++++++------ .../schemas/define-realm-object-model.txt | 46 +++++++---- .../realm-database/schemas/relationships.txt | 82 +------------------ 6 files changed, 128 insertions(+), 126 deletions(-) create mode 100644 source/sdk/kotlin/realm-database/crud/filter-data.txt diff --git a/source/sdk/kotlin/realm-database/crud/create.txt b/source/sdk/kotlin/realm-database/crud/create.txt index 9c08b981836..bff15d6b061 100644 --- a/source/sdk/kotlin/realm-database/crud/create.txt +++ b/source/sdk/kotlin/realm-database/crud/create.txt @@ -45,6 +45,21 @@ To persist a new object to a realm: .. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.create-a-new-object.kt :language: kotlin +.. tip:: + + You can also upsert into a realm using specific criteria. See + :ref:`Upsert a Realm Object `. + +Create an Embedded Object +------------------------- + +To create an embedded object, assign an instance of the +`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__ +to a parent object's property: + +.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.create-embedded-object.kt + :language: kotlin + Create an Object with a Dictionary Property ------------------------------------------- @@ -80,7 +95,7 @@ For more information, see :ref:`Asymmetric Objects `. You must create an `AsymmetricRealmObject <{+kotlin-sync-prefix+}io.realm.kotlin.types/-asymmetric-realm-object/index.html>`__ using the `insert() <{+kotlin-sync-prefix+}io.realm.kotlin.mongodb.ext/insert.html>`__ -extension method within a write transaction. +extension method within a write transaction: .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt :language: kotlin diff --git a/source/sdk/kotlin/realm-database/crud/delete.txt b/source/sdk/kotlin/realm-database/crud/delete.txt index e6712d71d3a..d02b2f54c98 100644 --- a/source/sdk/kotlin/realm-database/crud/delete.txt +++ b/source/sdk/kotlin/realm-database/crud/delete.txt @@ -17,10 +17,13 @@ Delete Realm Objects - Kotlin SDK To delete a realm file, refer to :ref:`Delete a Realm `. +Delete a Realm Object +--------------------- + .. _kotlin-delete-an-object: -Delete an Object ----------------- +Delete a Single Object +~~~~~~~~~~~~~~~~~~~~~~ To delete an object from a realm: @@ -47,7 +50,7 @@ To delete an object from a realm: .. _kotlin-delete-multiple-objects: Delete Multiple Objects ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ To delete multiple objects from a realm at the same time: @@ -73,7 +76,7 @@ To delete multiple objects from a realm at the same time: .. _kotlin-delete-all-objects-of-a-type: Delete All Objects of a Type ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To delete all objects of a type from a realm: @@ -110,3 +113,27 @@ entries in a few ways: .. literalinclude:: /examples/generated/kotlin/DeleteTest.snippet.delete-realm-dictionary.kt :language: kotlin + +Delete an Embedded Object +------------------------- + +.. warning:: Realm Uses Cascading Deletes for Embedded Objects + + When you delete a Realm object, Realm automatically deletes any + embedded objects referenced by that object. + If you want the referenced objects to persist after the deletion of the + parent object, use a regular Realm object with a :ref:`to-one relationship + ` instead. + +You can delete an +`EmbeddedRealmObject.parent() <{+kotlin-local-prefix+}io.realm.kotlin.ext/parent.html>`__ +directly or through the parent object. + +To delete only an embedded object, you can fetch and delete a specific +embedded object or clear the parent's reference to the embedded object, +which also deletes the embedded object instance. + +Deleting the parent object automatically deletes all of its embedded objects. + +.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.delete-embedded-object.kt + :language: kotlin diff --git a/source/sdk/kotlin/realm-database/crud/filter-data.txt b/source/sdk/kotlin/realm-database/crud/filter-data.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/source/sdk/kotlin/realm-database/crud/update.txt b/source/sdk/kotlin/realm-database/crud/update.txt index 94566b53012..3451621852c 100644 --- a/source/sdk/kotlin/realm-database/crud/update.txt +++ b/source/sdk/kotlin/realm-database/crud/update.txt @@ -50,10 +50,56 @@ as you would a Kotlin Map. .. literalinclude:: /examples/generated/kotlin/UpdateTest.snippet.update-realm-dictionary.kt :language: kotlin +Update an Embedded Object Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To update a property in an +`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__, +fetch the object and reassign the embedded object properties in a write +transaction: + +.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.update-embedded-object.kt + :language: kotlin + +Update Realm Objects +-------------------- + +.. _kotlin-update-collection: + +Update a Collection +~~~~~~~~~~~~~~~~~~~ + +To update a collection of objects in a realm: + +1. Query a realm for a collection of objects + with `realm.query() + <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-query/query.html>`__. + +#. 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>`__. + +#. Update elements of the set of `RealmResults + <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-results/index.html>`__ + returned by the query. + +.. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.update-a-collection.kt + :language: kotlin + +Overwrite an Embedded Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To overwrite an embedded object, assign a new embedded object instance to the +property in a write transaction: + +.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.overwrite-embedded-object.kt + :language: kotlin + .. _kotlin-upsert-an-object: -Upsert Objects --------------- +Upsert a Realm Object +--------------------- The **upsert** operation either inserts a new instance of an object or updates an existing object that meets certain criteria. @@ -82,27 +128,3 @@ to use when you upsert an object with an existing primary key: .. literalinclude:: /examples/generated/kotlin/UpdateTest.snippet.upsert-an-object.kt :language: kotlin - -.. _kotlin-update-collection: - -Update a Collection -------------------- - -To update a collection of objects in a realm: - -1. Query a realm for a collection of objects - with `realm.query() - <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-query/query.html>`__. - -#. 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>`__. - -#. Update elements of the set of `RealmResults - <{+kotlin-local-prefix+}io.realm.kotlin.query/-realm-results/index.html>`__ - returned by the query. - -.. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.update-a-collection.kt - :language: kotlin - \ No newline at end of file diff --git a/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt b/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt index 6532e31d494..75d02c6319c 100644 --- a/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt +++ b/source/sdk/kotlin/realm-database/schemas/define-realm-object-model.txt @@ -50,6 +50,23 @@ Realm Schema .. include:: /includes/realm-schema.rst +Property Annotations +~~~~~~~~~~~~~~~~~~~~ + +Annotations add functionality to properties in your Realm object models. +You can use annotations for things like marking a property as nullable, setting a primary key, ignoring a property, and more. + +To learn more about the available property annotations, refer to :ref:`Property Annotations `. + +Relationship Properties +~~~~~~~~~~~~~~~~~~~~~~~ + +You can define relationships between Realm objects in your schema. +The Realm Kotlin SDK supports to-one relationships, to-many relationships, +inverse relationships, and embedding objects within other objects. + +To learn more about how to define relationships in your Realm object schema, refer to :ref:`Relationships `. + .. _kotlin-define-a-new-object-type: Define a New Object Type @@ -59,8 +76,6 @@ To define a Realm object type: 1. Create a uniquely named Kotlin class that implements the `RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__ - or - `EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__ interface. #. Add fields to your class. You can add any :ref:`supported data types ` as a field in your class. @@ -81,23 +96,26 @@ when you :ref:`open the realm `. .. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.open-with-class.kt :language: kotlin :emphasize-lines: 2 - -Add Property Annotations -~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _kotlin-define-embedded-object: -Use annotations to add functionality to properties in your Realm object models. -You can use annotations for things like marking a property as nullable, setting a primary key, ignoring a property, and more. +Define an Embedded Object +------------------------- -To learn more about the available property annotations, refer to :ref:`Property Annotations `. +To define an :ref:`embedded object `, derive a class from +`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__: -Define Relationship Properties -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.embedded-object-model.kt + :language: kotlin -You can define relationships between Realm objects in your schema. -The Realm Kotlin SDK supports to-one relationships, to-many relationships, -inverse relationships, and embedding objects within other objects. +Once your embedded object class is defined, you must include its schema in the +realm's +`configuration <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__ +to use it in your realm instance: -To learn more about how to define relationships in your Realm object schema, refer to :ref:`Relationships `. +.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.open-realm-embedded-object.kt + :language: kotlin + :emphasize-lines: 3 Define an Asymmetric Object --------------------------- diff --git a/source/sdk/kotlin/realm-database/schemas/relationships.txt b/source/sdk/kotlin/realm-database/schemas/relationships.txt index 3fc396906d4..0d5ae51b3b7 100644 --- a/source/sdk/kotlin/realm-database/schemas/relationships.txt +++ b/source/sdk/kotlin/realm-database/schemas/relationships.txt @@ -149,84 +149,4 @@ Because of this, embedded objects have the following constraints: recursively reference an embedded object type as an optional property in its own definition. -Define an Embedded Object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To define an embedded object, derive a class from -`EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__: - -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.embedded-object-model.kt - :language: kotlin - -Once your embedded object class is defined, you must include its schema in the -realm's -`configuration <{+kotlin-local-prefix+}io.realm.kotlin/-realm-configuration/index.html>`__ -to use it in your realm instance: - -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.open-realm-embedded-object.kt - :language: kotlin - :emphasize-lines: 3 - -Create an Embedded Object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create an embedded object, assign an instance of the embedded object -to a parent object's property: - -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.create-embedded-object.kt - :language: kotlin - - -Update Embedded Object Properties -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To update a property in an embedded object, fetch the object and reassign the -embedded object properties in a write transaction: - -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.update-embedded-object.kt - :language: kotlin - - -Overwrite an Embedded Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To overwrite an embedded object, assign a new embedded object instance to the -property in a write transaction: - -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.overwrite-embedded-object.kt - :language: kotlin - - -Query an Embedded Object -~~~~~~~~~~~~~~~~~~~~~~~~ - -You can query the embedded object directly or through the parent object. -You can also use the -`EmbeddedRealmObject.parent() <{+kotlin-local-prefix+}io.realm.kotlin.ext/parent.html>`__ -method to access the parent of the embedded object. - -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.query-embedded-objects.kt - :language: kotlin - - -Delete an Embedded Object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. warning:: Realm Uses Cascading Deletes for Embedded Objects - - When you delete a Realm object, Realm automatically deletes any - embedded objects referenced by that object. - If you want the referenced objects to persist after the deletion of the - parent object, use a regular Realm object with a :ref:`to-one relationship - ` instead. - -You can delete an embedded object directly or through the parent object. - -To delete only an embedded object, you can fetch and delete a specific embedded object -or clear the parent's reference to the embedded object, which also deletes -the embedded object instance. - -Deleting the parent object automatically deletes all of its embedded objects. - -.. literalinclude:: /examples/generated/kotlin/DataTypesTest.snippet.delete-embedded-object.kt - :language: kotlin +To define an embedded object, refer to :ref:`Define an Embedded Object `.