Add more examples

examples/dart/test/backlinks_test.dart

@@ -31,13 +31,13 @@ class _Task {
 // :snippet-end:
 
 void main() {
-  test('Filter Backlinks with RQL', () {
+  test('Query Inverse Backlinks', () {
     final config = Configuration.local([User.schema, Task.schema]);
     final realm = Realm(config);
 
     final han = User(ObjectId(), 'han', tasks: [
       Task(ObjectId(), 'Pay Chewie back', false),
-      Task(ObjectId(), 'Get a haircut', true)
+      Task(ObjectId(), 'Get a haircut', false)
     ]);
     realm.write(() => realm.add(han));
     final jarjar = User(ObjectId(), 'jarjar_binks', tasks: [
@@ -48,20 +48,39 @@ void main() {
     realm.write(() => realm.add(jarjar));
 
     // :snippet-start: filter-backlinks-rql
-    // Filter tasks through the User's backlink property
+    // Filter Tasks through the User's backlink property
     // using `@links.<ObjectType>.<PropertyName>` syntax
     final jarjarsIncompleteTasks = realm.query<Task>(
         "ALL @links.User.tasks.username == 'jarjar_binks' AND isComplete == false");
 
-    final tasksForHan = realm.query<Task>("ALL @links.User.tasks.username == 'han'");
+    final tasksForHan =
+        realm.query<Task>("ALL @links.User.tasks.username == 'han'");
     // :snippet-end:
 
     expect(jarjarsIncompleteTasks.length, 2);
     expect(tasksForHan.length, 2);
+
+    // :snippet-start: query-backlink-inverse-relationship
+    // Tasks have an inverse relationship to Users
+    final inCompleteTasks = realm.query<Task>("isComplete == false");
+
+    // Find all Users who have an incomplete Task
+    for (final task in inCompleteTasks) {
+      final ownersWithIncompleteTasks = task.getBacklinks<User>('tasks');
+      for (final user in ownersWithIncompleteTasks) {
+        print("User ${user.username} has incomplete tasks.");
+      }
+    }
+    // :snippet-end:
+    expect(
+        inCompleteTasks
+            .any((element) => element.description == 'Get a haircut'),
+        true);
+
     cleanUpRealm(realm);
   });
 
-  test('Query Backlinks', () {
+  test('Query To-One Backlinks', () {
     // Use to-one models from Schemas.dart
     final config = Configuration.local([Person.schema, Bike.schema]);
     final realm = Realm(config);
@@ -78,15 +97,52 @@ void main() {
       realm.add(Bike(ObjectId(), 'Speeder Bike', owner: owner));
     });
 
-    // :snippet-start: query-backlinks
+    // :snippet-start: query-backlink-to-one-relationship
+    // Persons have a to-one relationship with Bikes
     final person = realm.query<Person>("firstName == 'Anakin'").first;
 
-    // Find all bikes that have an owner named Anakin
+    // Find all Bikes that have an Owner named 'Anakin'
     final allBikes = person.getBacklinks<Bike>('owner');
     // :snippet-end:
     expect(allBikes.length, 2);
     expect(allBikes.any((element) => element.id == bikeId), true);
     expect(allBikes.any((element) => element.owner!.id == ownerId), true);
     cleanUpRealm(realm);
   });
+
+  test('Query To-Many Backlinks', () {
+    // Use to-many models from Schemas.dart
+    final config = Configuration.local(
+        [Scooter.schema, ScooterShop.schema, Person.schema]);
+    final realm = Realm(config);
+
+    final scooterId = ObjectId();
+    final shopId = ObjectId();
+
+    realm.write(() {
+      Scooter roadHog = realm.add(Scooter(ObjectId(), 'Road Hog 9000'));
+      Scooter scooterbug = realm.add(Scooter(scooterId, 'Scooterbug'));
+      Scooter bigBen = realm.add(Scooter(ObjectId(), 'Big Ben'));
+
+      realm.add(ScooterShop(ObjectId(), 'The Scoot Zone',
+          scooters: [roadHog, bigBen, scooterbug]));
+
+      realm.add(
+          ScooterShop(ObjectId(), 'Scooterz', scooters: [scooterbug, bigBen]));
+
+      realm.add(ScooterShop(shopId, 'Scoot n Shop', scooters: [roadHog]));
+    });
+    // :snippet-start: query-backlinks-to-many-relationship
+    // Scooters have a to-many relationship with ScooterShops
+    final scooters = realm.query<Scooter>("name == 'Scooterbug'").first;
+
+    // Find all ScooterShops that sell the Scooterbug
+    final shops = scooters.getBacklinks<ScooterShop>('scooters');
+
+    // :snippet-end:
+    expect(shops.length, 2);
+    expect(scooters.id, scooterId);
+    expect(shops.any((element) => element.id == shopId), false);
+    cleanUpRealm(realm);
+  });
 }

examples/dart/test/schemas.dart

@@ -64,7 +64,7 @@ class _ScooterShop {
   late ObjectId id;
 
   late String name;
-  late List<_Scooter> owner;
+  late List<_Scooter> scooters;
 }
 // :snippet-end:
 

source/examples/generated/flutter/backlinks_test.snippet.filter-backlinks-rql.dart

@@ -1,6 +1,7 @@
-// Filter tasks through the User's backlink property
+// Filter Tasks through the User's backlink property
 // using `@links.<ObjectType>.<PropertyName>` syntax
 final jarjarsIncompleteTasks = realm.query<Task>(
     "ALL @links.User.tasks.username == 'jarjar_binks' AND isComplete == false");
 
-final tasksForHan = realm.query<Task>("ALL @links.User.tasks.username == 'han'");
+final tasksForHan =
+    realm.query<Task>("ALL @links.User.tasks.username == 'han'");

source/examples/generated/flutter/backlinks_test.snippet.query-backlink-inverse-relationship.dart

@@ -0,0 +1,10 @@
+// Tasks have an inverse relationship to Users
+final inCompleteTasks = realm.query<Task>("isComplete == false");
+
+// Find all Users who have an incomplete Task
+for (final task in inCompleteTasks) {
+  final ownersWithIncompleteTasks = task.getBacklinks<User>('tasks');
+  for (final user in ownersWithIncompleteTasks) {
+    print("User ${user.username} has incomplete tasks.");
+  }
+}

source/examples/generated/flutter/backlinks_test.snippet.query-backlinks.dart → source/examples/generated/flutter/backlinks_test.snippet.query-backlink-to-one-relationship.dart

@@ -1,4 +1,5 @@
+// Persons have a to-one relationship with Bikes
 final person = realm.query<Person>("firstName == 'Anakin'").first;
 
-// Find all bikes that have an owner named Anakin
+// Find all Bikes that have an Owner named 'Anakin'
 final allBikes = person.getBacklinks<Bike>('owner');

source/examples/generated/flutter/backlinks_test.snippet.query-backlinks-to-many-relationship.dart

@@ -0,0 +1,6 @@
+// Scooters have a to-many relationship with ScooterShops
+final scooters = realm.query<Scooter>("name == 'Scooterbug'").first;
+
+// Find all ScooterShops that sell the Scooterbug
+final shops = scooters.getBacklinks<ScooterShop>('scooters');
+

source/examples/generated/flutter/schemas.snippet.many-to-many-models.dart

@@ -13,5 +13,5 @@ class _ScooterShop {
   late ObjectId id;
 
   late String name;
-  late List<_Scooter> owner;
+  late List<_Scooter> scooters;
 }

source/sdk/flutter/crud/read.txt

@@ -152,25 +152,35 @@ Retrieve a collection of all objects of a data model in the database with the
 
 .. _flutter-get-backlinks:
 
-Query Linked Objects
-~~~~~~~~~~~~~~~~~~~~
+Query Related Objects
+~~~~~~~~~~~~~~~~~~~~~
 
 .. versionadded:: 1.9.0
 
-You can find all objects with an inverse relationship to a given object by calling the
-object's :flutter-sdk:`getBacklinks() <realm/RealmObjectBase/getBacklinks.html>` method.
+If your data model includes objects that reference other objects, you can query the :ref:`relationship <flutter-client-relationships>` using the :flutter-sdk:`getBacklinks() <realm/RealmObjectBase/getBacklinks.html>` method.
 
-In this example, we have a ``Bike`` object model with an ``owner`` property of type ``Person``: 
+This method returns a :flutter-sdk:`results collection <realm/RealmResults-class.html>` of all objects that link to the given object through a to-one, to-many, or inverse relationship. The following examples use the models defined on the :ref:`Relationships <flutter-client-relationships>` page.
 
-.. literalinclude:: /examples/generated/flutter/schemas.snippet.many-to-one-models.dart
-   :language: dart
+- **To-one relationship:** In this example, we have a ``Bike`` object model with a to-one relationship with a ``Person`` object. 
 
-We can use the ``getBacklinks()`` method to find any linked objects. This
-method returns a :flutter-sdk:`results collection <realm/RealmResults-class.html>` of ``Bike``
-objects that link to the specified person:
+  We use the ``getBacklinks()`` method to find any ``Bike`` objects that link to the specified person through the ``owner`` property:
 
-.. literalinclude:: /examples/generated/flutter/backlinks_test.snippet.query-backlinks.dart
-   :language: dart
+   .. literalinclude:: /examples/generated/flutter/backlinks_test.snippet.query-backlink-to-one-relationship.dart
+      :language: dart
+
+- **To-many relationship:** In this example, we have a ``Scooter`` object model with a to-many relationship with a ``ScooterShop`` object. 
+
+  We use the ``getBacklinks()`` method to find any ``ScooterShops`` objects that link to the specified scooter through the ``scooters`` list property:
+
+   .. literalinclude:: /examples/generated/flutter/backlinks_test.snippet.query-backlink-to-many-relationship.dart
+      :language: dart
+
+- **Inverse relationship:** In this example, we have a ``Task`` object model with an inverse relationship with a ``User`` object. 
+
+  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
 
 .. _flutter-query-list-realm-objects:
 

source/sdk/flutter/realm-database/model-data/relationships.txt

@@ -22,6 +22,11 @@ Embedded objects are similar to relationships, but provide additional constraint
 For more information about these constraints and how to create embedded objects,
 refer to the :ref:`Embedded Objects data type documentation <flutter-embedded-objects>`.
 
+.. tip:: Querying Related Objects
+
+   In Flutter v1.9.0 and later, you can use the :flutter-sdk:`getBacklinks() <realm/RealmObjectBase/getBacklinks.html>` method to find objects that link to another object through a relationship.
+   For more information, refer to :ref:`flutter-get-backlinks`.
+
 .. _flutter-many-to-one-relationship:
 
 To-One Relationship