docs: add section on querying records from a link's table (#10165)
This commit is contained in:
Shahed Nasser
GitHub
@@ -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."],
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user