Add info about querying relationships

Author: dacharyc

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".

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.

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.

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()
+<realm/RealmObjectBase/getBacklinks.html>` 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.<Type>.<Property>`` syntax. For example, a filter can match 
+a ``Task`` object based on properties of the ``User``
+object that references it.

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 <sdks-java-filter-data>` to access any property
+of the linked object.

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 <sdks-java-filter-data>` to access any property
+of the linked object.

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
+<sdks-java-filter-data>` to access any property of the linked object.

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
+<sdks-java-filter-data>` to access any propertyof the linked object:

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()
+<classes/Object.html#linkingObjects>` query.
+
+The ``.linkingObjects()`` method returns a :ref:`Results collection 
+<sdks-read-access-results>` 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.

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.