diff --git a/www/apps/api-reference/app/_mdx/admin.mdx b/www/apps/api-reference/app/_mdx/admin.mdx index f2b8b0ba0d..f1cafbd04e 100644 --- a/www/apps/api-reference/app/_mdx/admin.mdx +++ b/www/apps/api-reference/app/_mdx/admin.mdx @@ -322,21 +322,24 @@ const App = () => { -## Expanding Fields +## Expanding Relations -In many API Routes you'll find an `expand` query parameter that can be passed -to the API Route. You can use the `expand` query parameter to unpack an +Many API Routes accept an `expand` that unpacks an entity's relations and return them in the response. -Please note that the relations you pass to `expand` replace any relations + + +The relations you pass to `expand` replace any relations that are expanded by default in the request. + + ### 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`: @@ -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`: +### 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`: + + + + + ```bash + curl "http://localhost:9000/admin/products?expand=variants.options" \ + -H 'x-medusa-access-token: {api_token}' + ``` + + + + + ```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); + }); + ``` + + + + + ```tsx + import { useAdminProducts } from "medusa-react" + + const Products = () => { + const { products, isLoading } = useAdminProducts({ + expand: "variants.options" + }) + + return ( +
+ {/** ... **/} +
+ ) + } + + export default Products + ``` + + + + ### Prevent Expanding Relations diff --git a/www/apps/api-reference/app/_mdx/store.mdx b/www/apps/api-reference/app/_mdx/store.mdx index 225d78ada8..862f45dd83 100644 --- a/www/apps/api-reference/app/_mdx/store.mdx +++ b/www/apps/api-reference/app/_mdx/store.mdx @@ -293,22 +293,25 @@ const App = () => { -## Expanding Fields +## Expanding Relations -In many API Routes you'll find an `expand` query parameter that can be passed -to the API Route. You can use the `expand` query parameter to unpack an +Many API Routes accept an `expand` that unpacks an entity's relations and return them in the response. -Please note that the relations you pass to `expand` replace any relations + + +The relations you pass to `expand` replace any relations that are expanded by default in the request. + + ### 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`: @@ -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`: +### 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`: + + + + + ```bash + curl "http://localhost:9000/store/products?expand=variants.options" + ``` + + + + + ```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); + }); + ``` + + + + + ```tsx + import { useProducts } from "medusa-react" + + const Products = () => { + const { products, isLoading } = useProducts({ + expand: "variants.options" + }) + + return ( +
+ {/* ... */} +
+ ) + } + + export default Products + ``` + + + + ### Prevent Expanding Relations diff --git a/www/apps/api-reference/components/Tags/Operation/Parameters/Name/index.tsx b/www/apps/api-reference/components/Tags/Operation/Parameters/Name/index.tsx index e43b384adc..465b5e8c31 100644 --- a/www/apps/api-reference/components/Tags/Operation/Parameters/Name/index.tsx +++ b/www/apps/api-reference/components/Tags/Operation/Parameters/Name/index.tsx @@ -23,7 +23,7 @@ const TagOperationParametersName = ({ {schema["x-expandable"] && ( <>
- + )} {schema["x-featureFlag"] && ( diff --git a/www/apps/docs/content/development/entities/repositories.md b/www/apps/docs/content/development/entities/repositories.md index c1bdba762d..5ef335c1d9 100644 --- a/www/apps/docs/content/development/entities/repositories.md +++ b/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.