docs: add note about expanding nested relations (#7008)

www/apps/api-reference/app/_mdx/admin.mdx

@@ -322,21 +322,24 @@ const App = () => {
 
 <SectionContainer noTopPadding={true}>
 
-## Expanding Fields
+## Expanding Relations
 
-In many API Routes you'll find an `expand` query parameter that can be passed
+Many API Routes accept an `expand` that unpacks an
-to the API Route. You can use the `expand` query parameter to unpack an
 entity's relations and return them in the response.
 
 
-Please note that the relations you pass to `expand` replace any relations
+<Note type="warning">
+
+The relations you pass to `expand` replace any relations
 that are expanded by default in the request.
 
+</Note>
+
 
 ### Expanding One Relation
 
 
-For example, when you retrieve products, you can retrieve their collection
+For example, when you retrieve products, retrieve their collection
 by passing to the `expand` query parameter the value `collection`:
 
 <CodeTabs group="clients">
@@ -390,7 +393,7 @@ by passing to the `expand` query parameter the value `collection`:
 ### Expanding Multiple Relations
 
 
-You can expand more than one relation by separating the relations in the
+Expand more than one relation by separating the relations in the
 `expand` query parameter with a comma.
 
 
@@ -444,6 +447,62 @@ pass to the `expand` query parameter the value `variants,collection`:
   </CodeTab>
 </CodeTabs>
 
+### Expanding Nested Relations
+
+
+Expand nested relations (the relations of a relation) using dot notation.
+
+
+For example, to retrieve the variants of a product along with its option values,
+pass to the `expand` query parameter `variants.options`:
+
+<CodeTabs group="clients">
+  <CodeTab label="cURL" value="curl">
+    
+    ```bash
+    curl "http://localhost:9000/admin/products?expand=variants.options" \
+        -H 'x-medusa-access-token: {api_token}'
+    ```
+
+  </CodeTab>
+  <CodeTab label="Medusa JS Client" value="js-client">
+    
+    ```ts
+    import Medusa from "@medusajs/medusa-js"
+    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+    // must be previously logged in or use api token
+    medusa.admin.products.list({
+      expand: "variants.options"
+    })
+    .then(({ products, limit, offset, count }) => {
+      console.log(products.length);
+    });
+    ```
+
+  </CodeTab>
+  <CodeTab label="Medusa React" value="medusa-react">
+    
+    ```tsx
+    import { useAdminProducts } from "medusa-react"
+
+    const Products = () => {
+      const { products, isLoading } = useAdminProducts({
+        expand: "variants.options"
+      })
+
+      return (
+        <div>
+          {/** ... **/}
+        </div>
+      )
+    }
+
+    export default Products
+    ```
+
+  </CodeTab>
+</CodeTabs>
+
 
 ### Prevent Expanding Relations
 

www/apps/api-reference/app/_mdx/store.mdx

@@ -293,22 +293,25 @@ const App = () => {
 
 <SectionContainer noTopPadding={true}>
 
-## Expanding Fields
+## Expanding Relations
 
 
-In many API Routes you'll find an `expand` query parameter that can be passed
+Many API Routes accept an `expand` that unpacks an
-to the API Route. You can use the `expand` query parameter to unpack an
 entity's relations and return them in the response.
 
 
-Please note that the relations you pass to `expand` replace any relations
+<Note type="warning">
+
+The relations you pass to `expand` replace any relations
 that are expanded by default in the request.
 
+</Note>
+
 
 ### Expanding One Relation
 
 
-For example, when you retrieve a list of products, you can retrieve their collections by
+For example, when you retrieve a list of products, retrieve their collections by
 passing to the `expand` query parameter the value `collection`:
 
 <CodeTabs group="clients">
@@ -358,7 +361,7 @@ passing to the `expand` query parameter the value `collection`:
 
 ### Expanding Multiple Relations
 
-You can expand more than one relation by separating the relations in the
+Expand more than one relation by separating the relations in the
 `expand` query parameter with a comma.
 
 
@@ -410,6 +413,60 @@ pass to the `expand` query parameter the value `variants,collection`:
   </CodeTab>
 </CodeTabs>
 
+### Expanding Nested Relations
+
+
+Expand nested relations (the relations of a relation) using dot notation.
+
+
+For example, to retrieve the variants of a product along with its option values,
+pass to the `expand` query parameter `variants.options`:
+
+<CodeTabs group="clients">
+  <CodeTab label="cURL" value="curl">
+    
+    ```bash
+    curl "http://localhost:9000/store/products?expand=variants.options"
+    ```
+
+  </CodeTab>
+  <CodeTab label="Medusa JS Client" value="js-client">
+    
+    ```ts
+    import Medusa from "@medusajs/medusa-js"
+    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+    medusa.products.list({
+      expand: "variants.options"
+    })
+    .then(({ products, limit, offset, count }) => {
+      console.log(products.length);
+    });
+    ```
+
+  </CodeTab>
+  <CodeTab label="Medusa React" value="medusa-react">
+    
+    ```tsx
+    import { useProducts } from "medusa-react"
+
+    const Products = () => {
+      const { products, isLoading } = useProducts({
+        expand: "variants.options"
+      })
+
+      return (
+        <div>
+          {/* ... */}
+        </div>
+      )
+    }
+
+    export default Products
+    ```
+
+  </CodeTab>
+</CodeTabs>
+
 
 ### Prevent Expanding Relations
 

www/apps/api-reference/components/Tags/Operation/Parameters/Name/index.tsx

@@ -23,7 +23,7 @@ const TagOperationParametersName = ({
       {schema["x-expandable"] && (
         <>
           <br />
-          <ExpandableNotice type="request" link="#expanding-fields" />
+          <ExpandableNotice type="request" link="#expanding-relations" />
         </>
       )}
       {schema["x-featureFlag"] && (

www/apps/docs/content/development/entities/repositories.md

@@ -211,6 +211,8 @@ To retrieve a list of records of an entity, use the `find` method:
 const posts = await postRepository.find()
 ```
 
+#### Pass Filters
+
 You can also filter the retrieved items by passing an object of type [FindOption](https://typeorm.io/find-options) as a first parameter:
 
 ```ts
@@ -221,6 +223,8 @@ const posts = await postRepository.find({
 })
 ```
 
+#### Configure Pagination
+
 In addition, you can pass `skip` and `take` properties to the object for pagination purposes. `skip`'s value is a number that indicates how many items to skip before retrieving the results, and `take` indicates how many items to return:
 
 ```ts
@@ -230,6 +234,8 @@ const posts = await postRepository.find({
 })
 ```
 
+#### Expand Relations
+
 To expand relations and retrieve them as part of each item in the result, you can pass the `relations` property to the parameter object:
 
 ```ts
@@ -238,6 +244,16 @@ const posts = await postRepository.find({
 })
 ```
 
+To expand nested relations (a relation of another relation), use dot notation:
+
+```ts
+const posts = await postRepository.find({
+  relations: ["authors.posts"],
+})
+```
+
+#### buildQuery Utility Method
+
 Medusa provides a utility method `buildQuery` that allows you to easily format the object to pass to the `find` method. `buildQuery` accepts two parameters:
 
 1. The first parameter is an object whose keys are the attributes of the entity, and their values are the value to filter by.