From be700e31f268977dcc679971b6960e5fc60f9c7b Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 19 Nov 2024 18:28:10 +0200 Subject: [PATCH] docs: add section on querying records from a link's table (#10165) --- .../module-links/custom-columns/page.mdx | 8 +- .../module-links/query/page.mdx | 122 +++++++++++++----- www/apps/book/generated/edit-dates.mjs | 4 +- 3 files changed, 94 insertions(+), 40 deletions(-) diff --git a/www/apps/book/app/learn/advanced-development/module-links/custom-columns/page.mdx b/www/apps/book/app/learn/advanced-development/module-links/custom-columns/page.mdx index cf5b9d063f..8a4b83b6d9 100644 --- a/www/apps/book/app/learn/advanced-development/module-links/custom-columns/page.mdx +++ b/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: - - -Learn more about Query and how to resolve use it [this chapter](../remote-link/page.mdx). - - - export const retrieveHighlights = [ ["1", "productHelloLink", "Import the exported link definition."], ["6", "entity", "Pass the link definition to retrieve its data."], diff --git a/www/apps/book/app/learn/advanced-development/module-links/query/page.mdx b/www/apps/book/app/learn/advanced-development/module-links/query/page.mdx index d1b0b542ba..d56ded17dd 100644 --- a/www/apps/book/app/learn/advanced-development/module-links/query/page.mdx +++ b/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", - }, - }, -}) -``` - - - -Sorting doesn't work on fields of linked data models from other modules. - - - -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", + }, + }, +}) +``` + + + +Sorting doesn't work on fields of linked data models from other modules. + + + +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 diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 7e1bf2ba01..d608ef7d7a 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/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",