docs: add section on querying records from a link's table (#10165)

www/apps/book/app/learn/advanced-development/module-links/custom-columns/page.mdx

@@ -111,16 +111,10 @@ await remoteLink.create({
 
 ## Retrieve Custom Column with Link
 
-To retrieve linked records with their custom columns, use Query and pass the link definition as the `entity` property's value.
+To retrieve linked records with their custom columns, use [Query](../query/page.mdx). A module link's definition, exported by a file under `src/links`, has a special `entryPoint` property. Use this property when specifying the `entity` property in Query's `graph` method.
 
 For example:
 
-<Note>
-
-Learn more about Query and how to resolve use it [this chapter](../remote-link/page.mdx).
-
-</Note>
-
 export const retrieveHighlights = [
   ["1", "productHelloLink", "Import the exported link definition."],
   ["6", "entity", "Pass the link definition to retrieve its data."],

www/apps/book/app/learn/advanced-development/module-links/query/page.mdx

@@ -121,6 +121,68 @@ const { data: myCustoms } = await query.graph({
 })
 ```
 
+### Apply Filters and Pagination on Linked Records
+
+Consider you want to apply filters or pagination configurations on the product(s) linked to `my_custom`. To do that, you must query the module link's table instead.
+
+As mentioned in the [Module Link](../page.mdx) documentation, Medusa creates a table for your module link. So, not only can you retrieve linked records, but you can also retrieve the records in a module link's table.
+
+A module link's definition, exported by a file under `src/links`, has a special `entryPoint` property. Use this property when specifying the `entity` property in Query's `graph` method.
+
+For example:
+
+export const queryLinkTableHighlights = [
+  ["1", "", "Import the module link."],
+  ["6", "productBrandLink.entryPoint", "Pass the `entryPoint` property of the link to Query"],
+  ["7", `"product.*"`, "Retrieve the fields of a product record linked to a `MyCustom` record."],
+  ["7", `"brand.*"`, "Retrieve the fields of a `MyCustom` record linked to a product record."]
+]
+
+```ts highlights={queryLinkTableHighlights}
+import productCustomLink from "../../../links/product-custom"
+
+// ...
+
+const { data: productCustoms } = await query.graph({
+  entity: productCustomLink.entryPoint,
+  fields: ["*", "product.*", "my_custom.*"],
+  pagination: {
+    take: 5,
+    skip: 0,
+  },
+});
+```
+
+In the object passed to the `graph` method:
+
+- You pass the `entryPoint` property of the link definition as the value for `entity`. So, Query will retrieve records from the module link's table.
+- You pass three items to the `field` property:
+    - `*` to retrieve the link table's fields. This is useful if the link table has [custom columns](../custom-columns/page.mdx).
+    - `product.*` to retrieve the fields of a product record linked to a `MyCustom` record.
+    - `my_custom.*` to retrieve the fields of a `MyCustom` record linked to a product record.
+
+You can then apply any [filters](#apply-filters) or [pagination configurations](#apply-pagination).
+
+The returned `data` is similar to the following:
+
+```json title="Example Result"
+[{
+  "id": "123",
+  "product_id": "prod_123",
+  "my_custom_id": "123",
+  "product": {
+    "id": "prod_123",
+    // other product fields...
+  },
+  "my_custom": {
+    "id": "123",
+    // other my_custom fields...
+  }
+}]
+```
+
+
+
 ---
 
 ## Apply Filters
@@ -150,37 +212,6 @@ Filters don't apply on fields of linked data models from other modules.
 
 ---
 
-## Sort Records
-
-```ts highlights={[["5"], ["6"], ["7"]]}
-const { data: myCustoms } = await query.graph({
-  entity: "my_custom",
-  fields: ["id", "name"],
-  pagination: {
-    order: {
-      name: "DESC",
-    },
-  },
-})
-```
-
-<Note>
-
-Sorting doesn't work on fields of linked data models from other modules.
-
-</Note>
-
-The `graph` method's object parameter accepts a `pagination` property to configure the pagination of retrieved records.
-
-To sort returned records, pass an `order` property to `pagination`.
-
-The `order` property is an object whose keys are property names, and values are either:
-
-- `ASC` to sort records by that property in ascending order.
-- `DESC` to sort records by that property in descending order.
-
----
-
 ## Apply Pagination
 
 ```ts highlights={[["8", "skip", "The number of records to skip before fetching the results."], ["9", "take", "The number of records to fetch."]]}
@@ -197,6 +228,8 @@ const {
 })
 ```
 
+The `graph` method's object parameter accepts a `pagination` property to configure the pagination of retrieved records.
+
 To paginate the returned records, pass the following properties to `pagination`:
 
 - `skip`: (required to apply pagination) The number of records to skip before fetching the results.
@@ -222,6 +255,33 @@ When you provide the pagination fields, the `query.graph` method's returned obje
   }
 ]} sectionTitle="Apply Pagination" />
 
+### Sort Records
+
+```ts highlights={[["5"], ["6"], ["7"]]}
+const { data: myCustoms } = await query.graph({
+  entity: "my_custom",
+  fields: ["id", "name"],
+  pagination: {
+    order: {
+      name: "DESC",
+    },
+  },
+})
+```
+
+<Note>
+
+Sorting doesn't work on fields of linked data models from other modules.
+
+</Note>
+
+To sort returned records, pass an `order` property to `pagination`.
+
+The `order` property is an object whose keys are property names, and values are either:
+
+- `ASC` to sort records by that property in ascending order.
+- `DESC` to sort records by that property in descending order.
+
 ---
 
 ## Request Query Configurations

www/apps/book/generated/edit-dates.mjs

@@ -77,10 +77,10 @@ export const generatedEditDates = {
   "app/learn/advanced-development/admin/constraints/page.mdx": "2024-09-10T11:39:51.165Z",
   "app/learn/debugging-and-testing/testing-tools/modules-tests/module-example/page.mdx": "2024-10-16T08:50:03.061Z",
   "app/learn/debugging-and-testing/testing-tools/modules-tests/page.mdx": "2024-10-16T08:50:23.232Z",
-  "app/learn/advanced-development/module-links/custom-columns/page.mdx": "2024-09-16T15:51:33.570Z",
+  "app/learn/advanced-development/module-links/custom-columns/page.mdx": "2024-11-19T15:05:59.471Z",
   "app/learn/advanced-development/module-links/directions/page.mdx": "2024-09-16T15:37:51.441Z",
   "app/learn/advanced-development/module-links/page.mdx": "2024-09-16T15:36:48.190Z",
-  "app/learn/advanced-development/module-links/query/page.mdx": "2024-11-12T15:40:24.411Z",
+  "app/learn/advanced-development/module-links/query/page.mdx": "2024-11-19T15:25:01.149Z",
   "app/learn/advanced-development/module-links/remote-link/page.mdx": "2024-09-16T12:42:27.581Z",
   "app/learn/advanced-development/modules/db-operations/page.mdx": "2024-09-16T14:38:29.150Z",
   "app/learn/advanced-development/modules/multiple-services/page.mdx": "2024-09-16T14:41:32.975Z",