Skip to content

Commit 81be17c

Browse files
dacharycdacharyc
authored
(DOCSP-39503): Consolidate Relationships page (#3287)
## Pull Request Info - SDK Docs Consolidation Jira ticket: https://jira.mongodb.org/browse/DOCSP-39503 *Staged Page* - [Relationships](https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39503/sdk/model-data/relationships/) *Page Source* Add links to every SDK's pages where you got the SDK-specific information: - [C++: Relationships](https://www.mongodb.com/docs/atlas/device-sdks/sdk/cpp/model-data/relationships/) - [Flutter: Relationships](https://www.mongodb.com/docs/atlas/device-sdks/sdk/flutter/realm-database/model-data/relationships/) - [Java: Relationships](https://www.mongodb.com/docs/atlas/device-sdks/sdk/java/model-data/relationships/) - [Kotlin: Relationships](https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/realm-database/schemas/relationships/) - [.NET: Relationships](https://www.mongodb.com/docs/atlas/device-sdks/sdk/dotnet/model-data/relationships/) - [Node.js: Relationships and Embedded Objects](https://www.mongodb.com/docs/atlas/device-sdks/sdk/node/model-data/relationships-and-embedded-objects/) - [Swift: Relationships](https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/model-data/relationships/) ### PR Author Checklist Before requesting a review for your PR, please check these items: - [x] Open the PR against the `feature-consolidated-sdk-docs` branch instead of `master` - [x] Tag the consolidated page for: - genre - meta.keywords - meta.description #### Naming - [x] Update Realm naming and the language around persistence layer/local/device per [this document](https://docs.google.com/document/d/126OczVxBWAwZ4P5ZsSM29WI3REvONEr1ald-mAwPtyQ/edit?usp=sharing) - [x] Include `.rst` files comply with [the naming guidelines](https://docs.google.com/document/d/1h8cr66zoEVeXytVfvDxlCSsUS5IZwvUQvfSCEXNMpek/edit#heading=h.ulh8b5f2hu9) #### Links and Refs - [x] Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections - [x] Remove or update any SDK-specific refs to use the new consolidated SDK ref targets - [x] [Update any Kotlin API links](https://jira.mongodb.org/browse/DOCSP-32519) to use the new Kotlin SDK roles #### Content - [x] Shared code boxes have snippets or placeholders for all 9 languages - [x] API description sections have API details or a generic placeholder for all 9 languages - [x] Check related pages for relevant content to include - [x] Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic ### Reviewer Checklist As a reviewer, please check these items: - [x] Shared code example boxes contain language-specific snippets or placeholders for every language - [x] API reference details contain working API reference links or generic content - [x] Realm naming/language has been updated - [x] All relevant content from individual SDK pages is present on the consolidated page
1 parent 1021196 commit 81be17c

14 files changed

+457
-9
lines changed

‎source/includes/api-details/cpp/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
To define an inverse relationship, use ``linking_objects`` in your object
2+
model. The ``linking_objects`` definition specifies the object type and
3+
property name of the relationship that it inverts.
4+
5+
In this example, we define a ``Person`` having a to-one relationship with
6+
a ``Dog``. The ``Dog`` has an inverse relationship to any ``Person``
7+
objects through its ``owners`` property.

‎source/includes/api-details/csharp/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
To define the inverse relationship, define a getter-only ``IQueryable<T>``
2+
property in your object model, where ``T`` is the source type of the
3+
relationship. Then, annotate this property with a
4+
:dotnet-sdk:`[Backlink(sourceProperty)] <reference/Realms.BacklinkAttribute.html>`
5+
attribute, where "sourceProperty" is the name of the property on the other
6+
side of the relationship. The following example shows how to do this with the
7+
"User has many Items" scenario.
8+
9+
In this example, note that:
10+
11+
- The Item object's ``Assignee`` property is a ``User`` object.
12+
13+
- The ``User`` object's ``Items`` property inverts the relationship and
14+
refers to all ``Item`` objects that contain this specific ``User`` in their
15+
``Assignee`` property.
16+
17+
This, then, allows us to query the ``Item`` collection to get all ``Items``
18+
assigned to a specific ``User``.

‎source/includes/api-details/dart/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Use the `Backlink <https://pub.dev/documentation/realm_common/latest/realm_common/Backlink-class.html>`__
2+
property annotation to define an inverse relationship.
3+
Pass a `Symbol <https://api.dart.dev/stable/2.18.4/dart-core/Symbol/Symbol.html>`__
4+
of the field name of the to-one or to-many field for which you are creating the
5+
backlink as an argument to ``Backlink()``. Include an ``Iterable`` of the
6+
object model you are backlinking to in the field below the annotation.

‎source/includes/api-details/java/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
To define an inverse relationship, define a ``LinkingObjects`` property in your
2+
object model. The ``LinkingObjects`` definition specifies the object type and
3+
property name of the relationship that it inverts.
4+
5+
Fields annotated with ``@LinkingObjects`` must be:
6+
7+
- marked ``final``
8+
- of type ``RealmResults<T>`` where ``T`` is the type at the opposite
9+
end of the relationship

‎source/includes/api-details/javascript/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
To define an inverse relationship, define a ``linkingObjects`` property in your
2+
object model. ``linkingObjects`` specifies the object type and
3+
property name of the relationship that it inverts.
4+
5+
.. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-inverse.js
6+
:language: javascript
7+
8+
**Dynamically Obtain an Inversely Linked Object**
9+
10+
You can dynamically retrieve an object with an inverse relationship without
11+
defining a ``linkingObjects`` type in its schema. Remove the
12+
``linkingObjects`` type from your schema, so your schemas look like a standard
13+
**to-many** relationship. When you need to retrieve the linked object, call the
14+
:js-sdk:`Realm.Object.linkingObjects() <classes/Object.html#linkingObjects>`
15+
query.
16+
17+
In the following continuation from the inverse relationship example, we
18+
have removed the ``manufacturer`` field with type 'linkingObjects' from
19+
the ``Car`` schema. An application developer creates several manufacturers
20+
and car objects, and the application pushes the newly-created cars into a
21+
manufacturer's ``cars`` field.
22+
23+
To find the manufacturer who makes a specific car object, call ``.linkingObjects()``
24+
and pass the "Manufacturer" class name and "cars" field as parameters.
25+
26+
The ``.linkingObjects()`` method returns a Results collection of objects whose
27+
property inverts the relationship. In this example, only one manufacturer makes
28+
the Sentra car model, so we can expect that manufacturer to be named Nissan.

‎source/includes/api-details/kotlin/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
To define an inverse relationship between objects, first define a
2+
collection property in the parent object whose type is a
3+
``RealmList<E>``, ``RealmSet<E>``, or ``RealmDictionary<E>``, where
4+
``<E>`` is a ``RealmObject`` object type defined in your data model.
5+
This can be a different Realm object type or the same Realm object
6+
type:
7+
8+
.. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-inverse-property-parent.kt
9+
:language: kotlin
10+
11+
Then, define an immutable :kotlin-sdk:`backlinks
12+
<io.realm.kotlin.ext/backlinks.html>` property in the child object of
13+
``RealmResults<E>``, where ``<E>`` is the parent object type:

‎source/includes/api-details/objectivec/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
To define an inverse relationship, use
2+
:objc-sdk:`RLMLinkingObjects
3+
<Classes.html#/c:objc(cs)RLMLinkingObjects>` in your object model.
4+
Override :objc-sdk:`+[RLMObject linkingObjectProperties]
5+
<Classes/RLMObject.html#/c:objc(cs)RLMObject(cm)linkingObjectsProperties>`
6+
method in your class to specify the object type and property name
7+
of the relationship that it inverts.

‎source/includes/api-details/swift/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
To define an inverse relationship, use :swift-sdk:`LinkingObjects
2+
<Structs/LinkingObjects.html>` in your object model. The
3+
``LinkingObjects`` definition specifies the object type and
4+
property name of the relationship that it inverts.

‎source/includes/api-details/typescript/model-data/relationships-inverse-relationship-description.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
To define an inverse relationship, define a ``linkingObjects`` property in your
2+
object model. ``linkingObjects`` specifies the object type and
3+
property name of the relationship that it inverts.
4+
5+
.. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.define-inverse.ts
6+
:language: typescript
7+
8+
**Dynamically Obtain an Inversely Linked Object**
9+
10+
You can dynamically retrieve an object with an inverse relationship without
11+
defining a ``linkingObjects`` type in its schema. Remove the
12+
``linkingObjects`` type from your schema, so your schemas look like a standard
13+
**to-many** relationship. When you need to retrieve the linked object, call the
14+
:js-sdk:`Realm.Object.linkingObjects() <classes/Object.html#linkingObjects>`
15+
query.
16+
17+
In the following continuation from the inverse relationship example, we
18+
have removed the ``manufacturer`` field with type 'linkingObjects' from
19+
the ``Car`` schema. An application developer creates several manufacturers
20+
and car objects, and the application pushes the newly-created cars into a
21+
manufacturer's ``cars`` field.
22+
23+
To find the manufacturer who makes a specific car object, call ``.linkingObjects()``
24+
and pass the "Manufacturer" class name and "cars" field as parameters.
25+
26+
The ``.linkingObjects()`` method returns a Results collection of objects whose
27+
property inverts the relationship. In this example, only one manufacturer makes
28+
the Sentra car model, so we can expect that manufacturer to be named Nissan.

‎source/includes/note-to-one-relationships-must-be-optional.rst‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

0 commit comments

Comments
 (0)