From f0a1a47cc775020a040b96a2415f774e913d113d 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 +++++++- .../sdk/kotlin/realm-database/crud/read.txt | 11 +++ .../sdk/kotlin/realm-database/crud/update.txt | 74 ++++++++++------ .../schemas/define-realm-object-model.txt | 46 ++++++---- .../realm-database/schemas/relationships.txt | 84 +------------------ 6 files changed, 140 insertions(+), 127 deletions(-) diff --git a/source/sdk/kotlin/realm-database/crud/create.txt b/source/sdk/kotlin/realm-database/crud/create.txt index 9c08b98183..bd603154c4 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 :ref:`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 e6712d71d3..d02b2f54c9 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/read.txt b/source/sdk/kotlin/realm-database/crud/read.txt index 20d81dac65..4b0937c060 100644 --- a/source/sdk/kotlin/realm-database/crud/read.txt +++ b/source/sdk/kotlin/realm-database/crud/read.txt @@ -57,6 +57,17 @@ as you would a Kotlin Map. .. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.read-realm-dictionary.kt :language: kotlin +Find an Embedded Object +~~~~~~~~~~~~~~~~~~~~~~~ + +You can query an :ref:`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 + .. _kotlin-filter-data: Filter Results diff --git a/source/sdk/kotlin/realm-database/crud/update.txt b/source/sdk/kotlin/realm-database/crud/update.txt index 94566b5301..3451621852 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 6532e31d49..75d02c6319 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 3fc396906d..e1c9e9a716 100644 --- a/source/sdk/kotlin/realm-database/schemas/relationships.txt +++ b/source/sdk/kotlin/realm-database/schemas/relationships.txt @@ -142,91 +142,11 @@ Because of this, embedded objects have the following constraints: - You cannot reassign an embedded object to a different parent object. - You cannot link to an embedded object from multiple parent objects. +To define an embedded object, refer to :ref:`Define an Embedded Object `. + .. tip:: Embedded Object Types are Reusable and Composable You can use the same embedded object type in multiple parent object types, and you can embed objects inside other embedded objects. You can even 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