From 198d7c9927eb2721cd0c898389a97b664e6b155f Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Thu, 15 Aug 2024 16:30:00 +0300
Subject: [PATCH] docs: add a section in the book on how to retrieve a
 relationship (#8594)

---
 .../data-models/manage-relationships/page.mdx | 27 ++++++++++++++++++-
 .../data-models/relationships/page.mdx        |  2 +-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx b/www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx
index bb6fb6b90c..37ca9dc6bf 100644
--- a/www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx
+++ b/www/apps/book/app/advanced-development/data-models/manage-relationships/page.mdx
@@ -4,7 +4,7 @@ export const metadata = {
 
 # {metadata.title}
 
-In this chapter, you'll learn how to manage relationships between data models when creating or updating their records using the module's main service.
+In this chapter, you'll learn how to manage relationships between data models when creating, updating, or retrieving records using the module's main service.
 
 <Note type="soon" title="Important">
 
@@ -69,3 +69,28 @@ const order = await helloModuleService.updateOrder({
 ```
 
 In the example above, you pass the `order_ids` property when you create (or update) a product, and you pass the `product_ids` property when you update (or create) an order.
+
+---
+
+## Retrieve Records of Relation
+
+The `list`, `listAndCount`, and `retrieve` methods of a module's main service accept as a second parameter an object of options.
+
+To retrieve the records associated with a data model's records through a relationship, pass in the second parameter object a `relations` property whose value is an array of relationship names.
+
+For example, assuming you have the [Order and Product data models from the previous chapter](../relationships/page.mdx#many-to-many-relationship):
+
+export const retrieveHighlights = [
+  ["4", `"orders"`, "Retrieve the records associated with the product\nthrough the `orders` relationship."]
+]
+
+```ts highlights={retrieveHighlights}
+const product = await helloModuleService.retrieveProduct(
+  "123",
+  {
+    relations: ["orders"]
+  }
+)
+```
+
+In the example above, the retrieved product has an `orders` property, whose value is an array of orders associated with the product.
diff --git a/www/apps/book/app/advanced-development/data-models/relationships/page.mdx b/www/apps/book/app/advanced-development/data-models/relationships/page.mdx
index ddf61e4d8c..57e9103307 100644
--- a/www/apps/book/app/advanced-development/data-models/relationships/page.mdx
+++ b/www/apps/book/app/advanced-development/data-models/relationships/page.mdx
@@ -125,7 +125,7 @@ const Order = model.define("order", {
 
 const Product = model.define("product", {
   id: model.id().primaryKey(),
-  order: model.manyToMany(() => Order),
+  orders: model.manyToMany(() => Order),
 })
 ```