From 5fbfe93fbda675273a62e5b67a40671562cb5576 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 9 Aug 2024 17:17:56 -0400 Subject: [PATCH] Add info about querying relationships --- ...query-inverse-relationship-description.rst | 3 + ...query-to-many-relationship-description.rst | 9 + ...-query-to-one-relationship-description.rst | 2 + ...query-inverse-relationship-description.rst | 16 ++ ...-inverse-relationship-java-description.rst | 13 ++ ...nverse-relationship-kotlin-description.rst | 13 ++ ...y-to-one-relationship-java-description.rst | 14 ++ ...to-one-relationship-kotlin-description.rst | 14 ++ ...inverse-relationship-js-ts-description.rst | 10 + ...query-inverse-relationship-description.rst | 13 ++ ...query-to-many-relationship-description.rst | 2 + ...-query-to-one-relationship-description.rst | 2 + ...query-inverse-relationship-description.rst | 7 + ...query-inverse-relationship-description.rst | 6 + .../crud/read-query-inverse-relationship.rst | 66 +++++++ .../crud/read-query-to-many-relationship.rst | 69 +++++++ .../crud/read-query-to-one-relationship.rst | 70 +++++++ source/sdk/crud/read.txt | 187 ++++++++++++++++++ 18 files changed, 516 insertions(+) create mode 100644 source/includes/api-details/csharp/crud/read-query-inverse-relationship-description.rst create mode 100644 source/includes/api-details/csharp/crud/read-query-to-many-relationship-description.rst create mode 100644 source/includes/api-details/csharp/crud/read-query-to-one-relationship-description.rst create mode 100644 source/includes/api-details/dart/crud/read-query-inverse-relationship-description.rst create mode 100644 source/includes/api-details/java/crud/read-query-inverse-relationship-java-description.rst create mode 100644 source/includes/api-details/java/crud/read-query-inverse-relationship-kotlin-description.rst create mode 100644 source/includes/api-details/java/crud/read-query-to-one-relationship-java-description.rst create mode 100644 source/includes/api-details/java/crud/read-query-to-one-relationship-kotlin-description.rst create mode 100644 source/includes/api-details/javascript/crud/read-query-inverse-relationship-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/crud/read-query-inverse-relationship-description.rst create mode 100644 source/includes/api-details/kotlin/crud/read-query-to-many-relationship-description.rst create mode 100644 source/includes/api-details/kotlin/crud/read-query-to-one-relationship-description.rst create mode 100644 source/includes/api-details/objectivec/crud/read-query-inverse-relationship-description.rst create mode 100644 source/includes/api-details/swift/crud/read-query-inverse-relationship-description.rst create mode 100644 source/includes/sdk-examples/crud/read-query-inverse-relationship.rst create mode 100644 source/includes/sdk-examples/crud/read-query-to-many-relationship.rst create mode 100644 source/includes/sdk-examples/crud/read-query-to-one-relationship.rst diff --git a/source/includes/api-details/csharp/crud/read-query-inverse-relationship-description.rst b/source/includes/api-details/csharp/crud/read-query-inverse-relationship-description.rst new file mode 100644 index 0000000000..6578914172 --- /dev/null +++ b/source/includes/api-details/csharp/crud/read-query-inverse-relationship-description.rst @@ -0,0 +1,3 @@ +To query an inverse relationship in C#, you cannot use LINQ. Instead, pass a +string predicate using RQL. The following example shows how you could find +all Users who have Items that contain the word "oscillator". diff --git a/source/includes/api-details/csharp/crud/read-query-to-many-relationship-description.rst b/source/includes/api-details/csharp/crud/read-query-to-many-relationship-description.rst new file mode 100644 index 0000000000..82facd1137 --- /dev/null +++ b/source/includes/api-details/csharp/crud/read-query-to-many-relationship-description.rst @@ -0,0 +1,9 @@ +An application could use the following object schemas to indicate +that a Person may own multiple Dogs by including them in its ``dog`` +property: + +.. literalinclude:: /examples/generated/dotnet/Relationships.snippet.one-to-many.cs + :language: csharp + +To see the to-many relationship of Person to Dog, you query for the +Person and get that person's Dogs. diff --git a/source/includes/api-details/csharp/crud/read-query-to-one-relationship-description.rst b/source/includes/api-details/csharp/crud/read-query-to-one-relationship-description.rst new file mode 100644 index 0000000000..47b9c81c12 --- /dev/null +++ b/source/includes/api-details/csharp/crud/read-query-to-one-relationship-description.rst @@ -0,0 +1,2 @@ +To query a direct relationship, you can use LINQ syntax. +See the following example for how to query a one-to-one relationship. diff --git a/source/includes/api-details/dart/crud/read-query-inverse-relationship-description.rst b/source/includes/api-details/dart/crud/read-query-inverse-relationship-description.rst new file mode 100644 index 0000000000..a42eb273b2 --- /dev/null +++ b/source/includes/api-details/dart/crud/read-query-inverse-relationship-description.rst @@ -0,0 +1,16 @@ +In Dart, there are two ways to query inverse relationships. + +You can use the :flutter-sdk:`getBacklinks() +` method to retrieve an object at +the origin of the relationship from the related object. + +Here, we use the ``getBacklinks()`` method to find any ``User`` objects that +link to the specified tasks through the ``tasks`` backlinks property: + +.. literalinclude:: /examples/generated/flutter/backlinks_test.snippet.query-backlink-inverse-relationship.dart + :language: dart + +You can also filter by inverse relationships using the +``@links..`` syntax. For example, a filter can match +a ``Task`` object based on properties of the ``User`` +object that references it. diff --git a/source/includes/api-details/java/crud/read-query-inverse-relationship-java-description.rst b/source/includes/api-details/java/crud/read-query-inverse-relationship-java-description.rst new file mode 100644 index 0000000000..6d7f3edb6f --- /dev/null +++ b/source/includes/api-details/java/crud/read-query-inverse-relationship-java-description.rst @@ -0,0 +1,13 @@ +Consider the following relationship between classes ``Cat`` and +``Human``. In this example, all cats link to their human (or +multiple humans, if multiple human objects refer to the same cat). +Realm calculates the owners of each cat for you based on the field +name you provide to the ``@LinkingObjects`` annotation: + +.. include:: /examples/generated/java/sync/Cat.snippet.complete.java.rst + +.. include:: /examples/generated/java/sync/Human.snippet.complete.java.rst + +To query this relationship, use dot notation in a +:ref:`query ` to access any property +of the linked object. diff --git a/source/includes/api-details/java/crud/read-query-inverse-relationship-kotlin-description.rst b/source/includes/api-details/java/crud/read-query-inverse-relationship-kotlin-description.rst new file mode 100644 index 0000000000..0a458a470e --- /dev/null +++ b/source/includes/api-details/java/crud/read-query-inverse-relationship-kotlin-description.rst @@ -0,0 +1,13 @@ +Consider the following relationship between classes ``Dog`` and +``Person``. In this example, all dogs link to their owner (or +multiple owners, if multiple person objects refer to the same dog). +Realm calculates the owners of each dog for you based on the field +name you provide to the ``@LinkingObjects`` annotation: + +.. include:: /examples/generated/java/sync/Dog.snippet.complete.kt.rst + +.. include:: /examples/generated/java/sync/Person.snippet.complete.kt.rst + +To query this relationship, use dot notation in a +:ref:`query ` to access any property +of the linked object. diff --git a/source/includes/api-details/java/crud/read-query-to-one-relationship-java-description.rst b/source/includes/api-details/java/crud/read-query-to-one-relationship-java-description.rst new file mode 100644 index 0000000000..975fc4ee7e --- /dev/null +++ b/source/includes/api-details/java/crud/read-query-to-one-relationship-java-description.rst @@ -0,0 +1,14 @@ +Consider the following relationship between classes ``Human`` and +``Cat``. This arrangement allows each human to own a single cat: + +.. literalinclude:: /examples/generated/java/sync/Human.snippet.complete.java + :language: java + :emphasize-lines: 12 + :copyable: false + +.. literalinclude:: /examples/generated/java/sync/Cat.snippet.complete.java + :language: java + :copyable: false + +To query this relationship, use dot notation in a :ref:`query +` to access any property of the linked object. diff --git a/source/includes/api-details/java/crud/read-query-to-one-relationship-kotlin-description.rst b/source/includes/api-details/java/crud/read-query-to-one-relationship-kotlin-description.rst new file mode 100644 index 0000000000..ed276dc831 --- /dev/null +++ b/source/includes/api-details/java/crud/read-query-to-one-relationship-kotlin-description.rst @@ -0,0 +1,14 @@ +Consider the following relationship between classes ``Person`` and +``Dog``. This arrangement allows each person to own a single dog: + +.. literalinclude:: /examples/generated/java/sync/Person.snippet.complete.kt + :language: kotlin + :emphasize-lines: 10 + :copyable: false + +.. literalinclude:: /examples/generated/java/sync/Dog.snippet.complete.kt + :language: kotlin + :copyable: false + +To query this relationship, use dot notation in a :ref:`query +` to access any propertyof the linked object: diff --git a/source/includes/api-details/javascript/crud/read-query-inverse-relationship-js-ts-description.rst b/source/includes/api-details/javascript/crud/read-query-inverse-relationship-js-ts-description.rst new file mode 100644 index 0000000000..58dfca970d --- /dev/null +++ b/source/includes/api-details/javascript/crud/read-query-inverse-relationship-js-ts-description.rst @@ -0,0 +1,10 @@ +You can dynamically retrieve an object with an inverse relationship without +defining a ``linkingObjects`` type in its schema. When you need to retrieve +the linked object, call the :js-sdk:`Realm.Object.linkingObjects() +` query. + +The ``.linkingObjects()`` method returns a :ref:`Results collection +` of objects whose property inverts the relationship. + +In this example, only one manufacturer makes the Sentra car model, so we +can expect that manufacturer to be named Nissan. diff --git a/source/includes/api-details/kotlin/crud/read-query-inverse-relationship-description.rst b/source/includes/api-details/kotlin/crud/read-query-inverse-relationship-description.rst new file mode 100644 index 0000000000..e9e07180fc --- /dev/null +++ b/source/includes/api-details/kotlin/crud/read-query-inverse-relationship-description.rst @@ -0,0 +1,13 @@ +In the following example, a parent object of type ``User`` has an inverse +relationship to a child object of type ``Post``. We can query the parent +object's ``User.posts`` relationship ("User has many Posts") as well +as the inverse ``Post.user`` relationship ("Post belongs to User"): + +.. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.query-inverse-relationship.kt + :language: kotlin + +.. important:: Querying Inverse Relationship by Remapped Class Names + + If the inverse relationship property is an object type with a + remapped (persisted) class name, you *must* use the remapped class + name in the raw RQL query. diff --git a/source/includes/api-details/kotlin/crud/read-query-to-many-relationship-description.rst b/source/includes/api-details/kotlin/crud/read-query-to-many-relationship-description.rst new file mode 100644 index 0000000000..525cca271a --- /dev/null +++ b/source/includes/api-details/kotlin/crud/read-query-to-many-relationship-description.rst @@ -0,0 +1,2 @@ +In the following example, the ``Forest`` object type has a property called +``nearbyPonds`` that is a ``RealmList`` of type ``Pond``. diff --git a/source/includes/api-details/kotlin/crud/read-query-to-one-relationship-description.rst b/source/includes/api-details/kotlin/crud/read-query-to-one-relationship-description.rst new file mode 100644 index 0000000000..5ef8210c61 --- /dev/null +++ b/source/includes/api-details/kotlin/crud/read-query-to-one-relationship-description.rst @@ -0,0 +1,2 @@ +In the following example, the ``Frog`` object type has a property called +``favoritePond`` of type ``Pond``. diff --git a/source/includes/api-details/objectivec/crud/read-query-inverse-relationship-description.rst b/source/includes/api-details/objectivec/crud/read-query-inverse-relationship-description.rst new file mode 100644 index 0000000000..7a09ac77d5 --- /dev/null +++ b/source/includes/api-details/objectivec/crud/read-query-inverse-relationship-description.rst @@ -0,0 +1,7 @@ +You can query :swift-sdk:`RLMLinkingObjects +`, an auto-updating container type, +to access zero or more objects that are linked to its owning model object +through a property relationship. You can query ``RLMLinkingObjects`` with the +same APIs and predicates as +:swift-sdk:`RLMArray\ ` and +:swift-sdk:`RLMResults\ `. diff --git a/source/includes/api-details/swift/crud/read-query-inverse-relationship-description.rst b/source/includes/api-details/swift/crud/read-query-inverse-relationship-description.rst new file mode 100644 index 0000000000..280f80ebc0 --- /dev/null +++ b/source/includes/api-details/swift/crud/read-query-inverse-relationship-description.rst @@ -0,0 +1,6 @@ +You can query :swift-sdk:`LinkingObjects `, +an auto-updating container type, to access zero or more objects that are +linked to its owning model object through a property relationship. You can +query ``LinkingObjects`` with the same APIs and predicates as +:swift-sdk:`List\ ` and +:swift-sdk:`Results\ `. diff --git a/source/includes/sdk-examples/crud/read-query-inverse-relationship.rst b/source/includes/sdk-examples/crud/read-query-inverse-relationship.rst new file mode 100644 index 0000000000..ea61a2afe1 --- /dev/null +++ b/source/includes/sdk-examples/crud/read-query-inverse-relationship.rst @@ -0,0 +1,66 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Relationships.snippet.inverse-query.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/backlinks_test.snippet.filter-backlinks-rql.dart + :language: dart + + - id: java + content: | + + .. include:: /examples/generated/java/sync/RealmQueryTest.snippet.query-an-inverse-relationship.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/sync/RealmQueryTest.snippet.query-an-inverse-relationship.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.obtain-inverse-relationship-dynamically.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.persisted-name-inverse.kt + :language: kotlin + :emphasize-lines: 1 + + .. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.query-inverse-persisted-name.kt + :language: kotlin + :emphasize-lines: 4 + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ReadWriteData.snippet.query-an-inverse-relationship.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ReadRealmObjects.snippet.query-an-inverse-relationship.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/relationships.test.snippet.obtain-inverse-relationship-dynamically.ts + :language: typescript diff --git a/source/includes/sdk-examples/crud/read-query-to-many-relationship.rst b/source/includes/sdk-examples/crud/read-query-to-many-relationship.rst new file mode 100644 index 0000000000..fc55b71d36 --- /dev/null +++ b/source/includes/sdk-examples/crud/read-query-to-many-relationship.rst @@ -0,0 +1,69 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Relationships.snippet.one-to-many-query.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realmlist-use.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/RealmQueryTest.snippet.query-a-relationship.java + :language: java + :emphasize-lines: 16 + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/RealmQueryTest.snippet.query-a-relationship.kt + :language: kotlin + :emphasize-lines: 15 + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.query-to-many-relationship.kt + :language: kotlin + + - 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/read-query-to-one-relationship.rst b/source/includes/sdk-examples/crud/read-query-to-one-relationship.rst new file mode 100644 index 0000000000..d9314ed4e8 --- /dev/null +++ b/source/includes/sdk-examples/crud/read-query-to-one-relationship.rst @@ -0,0 +1,70 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Relationships.snippet.one-to-one-query.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/RealmQueryTest.snippet.query-a-relationship.java + :language: java + :emphasize-lines: 16 + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/RealmQueryTest.snippet.query-a-relationship.kt + :language: kotlin + :emphasize-lines: 15 + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/ReadTest.snippet.query-to-one-relationship.kt + :language: kotlin + + - 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/sdk/crud/read.txt b/source/sdk/crud/read.txt index d3a66f5b60..ed88719da6 100644 --- a/source/sdk/crud/read.txt +++ b/source/sdk/crud/read.txt @@ -1821,12 +1821,199 @@ Filter Relationships Query a To-One Relationship ``````````````````````````` +A :ref:`to-one relationship ` property maps to +a single instance of another object type. You can filter by the relationship +property using dot notation, the same way you would a nested object. + +The SDK requires to-one relationships to be optional. Your code should handle +the possible nil or null value. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/read-query-to-one-relationship-description.rst + + .. tab:: + :tabid: dart + + + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/read-query-to-one-relationship-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/read-query-to-one-relationship-kotlin-description.rst + + .. tab:: + :tabid: javascript + + + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/read-query-to-one-relationship-description.rst + + .. tab:: + :tabid: objectivec + + + + .. tab:: + :tabid: swift + + + + .. tab:: + :tabid: typescript + + + +.. include:: /includes/sdk-examples/crud/read-query-to-one-relationship.rst + .. _sdks-read-query-to-many-relationship: Query a To-Many Relationship ```````````````````````````` +:ref:`To-many relationships ` properties are +collections to another object type: + +- :ref:`List ` +- :ref:`Set ` +- :ref:`Dictionary ` + +You can filter by and iterate through the relationship property the same way +you would any other collection property. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/read-query-to-many-relationship-description.rst + + .. tab:: + :tabid: dart + + + + .. tab:: + :tabid: java + + + + .. tab:: + :tabid: java-kotlin + + + + .. tab:: + :tabid: javascript + + + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/read-query-to-many-relationship-description.rst + + .. tab:: + :tabid: objectivec + + + + .. tab:: + :tabid: swift + + + + .. tab:: + :tabid: typescript + + + +.. include:: /includes/sdk-examples/crud/read-query-to-many-relationship.rst + .. _sdks-read-query-inverse-relationships: Query an Inverse Relationship ````````````````````````````` + +An **inverse relationship** links an object back to any other objects that refer +to it in a defined to-one or to-many relationship. Relationship definitions are +unidirectional, so you must explicitly define a property in the object's model +as an inverse relationship. + +When you follow an inverse relationship, the result may include zero or more +objects. You must access the collection to work with an originating object. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/crud/read-query-inverse-relationship-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/crud/read-query-inverse-relationship-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/crud/read-query-inverse-relationship-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/crud/read-query-inverse-relationship-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/crud/read-query-inverse-relationship-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/crud/read-query-inverse-relationship-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/crud/read-query-inverse-relationship-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/crud/read-query-inverse-relationship-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/crud/read-query-inverse-relationship-js-ts-description.rst + +.. include:: /includes/sdk-examples/crud/read-query-inverse-relationship.rst