docs: general improvements and fixes (#13515)
This commit is contained in:
Shahed Nasser
GitHub
@@ -13,7 +13,7 @@ To create an API route that accepts a path parameter, create a directory within
|
||||
For example, to create an API Route at the path `/hello-world/:id`, where `:id` is a path parameter, create the file `src/api/hello-world/[id]/route.ts` with the following content:
|
||||
|
||||
export const singlePathHighlights = [
|
||||
["11", "req.params.id", "Access the path parameter `id`"]
|
||||
["11", "req.params.id", "Access the path parameter `id`."]
|
||||
]
|
||||
|
||||
```ts title="src/api/hello-world/[id]/route.ts" highlights={singlePathHighlights}
|
||||
@@ -41,8 +41,8 @@ To create an API route that accepts multiple path parameters, create within the
|
||||
For example, to create an API route at `/hello-world/:id/name/:name`, create the file `src/api/hello-world/[id]/name/[name]/route.ts` with the following content:
|
||||
|
||||
export const multiplePathHighlights = [
|
||||
["12", "req.params.id", "Access the path parameter `id`"],
|
||||
["13", "req.params.name", "Access the path parameter `name`"]
|
||||
["12", "req.params.id", "Access the path parameter `id`."],
|
||||
["13", "req.params.name", "Access the path parameter `name`."]
|
||||
]
|
||||
|
||||
```ts title="src/api/hello-world/[id]/name/[name]/route.ts" highlights={multiplePathHighlights}
|
||||
@@ -74,7 +74,7 @@ You can access all query parameters in the `query` property of the `MedusaReques
|
||||
For example:
|
||||
|
||||
export const queryHighlights = [
|
||||
["11", "req.query.name", "Access the query parameter `name`"],
|
||||
["11", "req.query.name", "Access the query parameter `name`."],
|
||||
]
|
||||
|
||||
```ts title="src/api/hello-world/route.ts" highlights={queryHighlights}
|
||||
@@ -99,17 +99,17 @@ The value of `req.query.name` is the value passed in `?name=John`, for example.
|
||||
|
||||
You can apply validation rules on received query parameters to ensure they match specified rules and types.
|
||||
|
||||
Learn more in [this documentation](../validation/page.mdx#how-to-validate-request-query-paramters).
|
||||
Learn more in the [API Route Validation](../validation/page.mdx#how-to-validate-request-query-parameters) chapter.
|
||||
|
||||
---
|
||||
|
||||
## Request Body Parameters
|
||||
|
||||
The Medusa application parses the body of any request having a JSON, URL-encoded, or text request content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
|
||||
The Medusa application parses the body of any request with JSON, URL-encoded, or text content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Learn more about configuring body parsing in [this guide](../parse-body/page.mdx).
|
||||
Learn more about configuring body parsing in the [Body Parsing](../parse-body/page.mdx) chapter.
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -117,7 +117,7 @@ For example:
|
||||
|
||||
export const bodyHighlights = [
|
||||
["11", "HelloWorldReq", "Specify the type of the request body parameters."],
|
||||
["15", "req.body.name", "Access the request body parameter `name`"],
|
||||
["15", "req.body.name", "Access the request body parameter `name`."],
|
||||
]
|
||||
|
||||
```ts title="src/api/hello-world/route.ts" highlights={bodyHighlights}
|
||||
@@ -170,4 +170,4 @@ This returns the following JSON object:
|
||||
|
||||
You can apply validation rules on received body parameters to ensure they match specified rules and types.
|
||||
|
||||
Learn more in [this documentation](../validation/page.mdx#how-to-validate-request-body).
|
||||
Learn more in the [Body Validation](../validation/page.mdx#how-to-validate-request-body) chapter.
|
||||
|
||||
@@ -4,7 +4,7 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you'll learn how to seed data using a custom CLI script.
|
||||
In this chapter, you'll learn how to seed data using a [custom CLI script](../page.mdx).
|
||||
|
||||
## How to Seed Data
|
||||
|
||||
@@ -12,7 +12,9 @@ To seed dummy data for development or demo purposes, use a custom CLI script.
|
||||
|
||||
In the CLI script, use your custom workflows or Medusa's existing workflows, which you can browse in [this reference](!resources!/medusa-workflows-reference), to seed data.
|
||||
|
||||
### Example: Seed Dummy Products
|
||||
---
|
||||
|
||||
## Example: Seed Dummy Products
|
||||
|
||||
In this section, you'll follow an example of creating a custom CLI script that seeds fifty dummy products.
|
||||
|
||||
@@ -25,7 +27,7 @@ npm install --save-dev @faker-js/faker
|
||||
Then, create the file `src/scripts/demo-products.ts` with the following content:
|
||||
|
||||
export const highlights = [
|
||||
["16", "salesChannelModuleService", "Resolve the Sales Chanel Module's main service"],
|
||||
["16", "salesChannelModuleService", "Resolve the Sales Channel Module's service."],
|
||||
["19", "logger", "Resolve the logger to log messages in the terminal."],
|
||||
["22", "query", "Resolve Query to retrieve data later."],
|
||||
["26", "defaultSalesChannel", "Retrieve the default sales channel to associate products with."],
|
||||
@@ -77,8 +79,8 @@ export default async function seedDummyProducts({
|
||||
|
||||
So far, in the script, you:
|
||||
|
||||
- Resolve the Sales Channel Module's main service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
|
||||
- Resolve the Logger to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
|
||||
- Resolve the [Sales Channel Module](!resources!/commerce-modules/sales-channel)'s service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
|
||||
- Resolve the [Logger](../../../debugging-and-testing/logging/page.mdx) to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
|
||||
- Initialize some default data to use when seeding the products next.
|
||||
|
||||
Next, replace the `TODO` with the following:
|
||||
@@ -88,7 +90,7 @@ const productsData = new Array(productsNum).fill(0).map((_, index) => {
|
||||
const title = faker.commerce.product() + "_" + index
|
||||
return {
|
||||
title,
|
||||
is_giftcard: true,
|
||||
is_giftcard: false,
|
||||
description: faker.commerce.productDescription(),
|
||||
status: ProductStatus.PUBLISHED,
|
||||
options: [
|
||||
@@ -154,7 +156,7 @@ logger.info(`Seeded ${products.length} products.`)
|
||||
|
||||
You create the generated products using the `createProductsWorkflow` imported previously from `@medusajs/medusa/core-flows`. It accepts the product data as input, and returns the created products.
|
||||
|
||||
Only thing left is to create inventory levels for the products. So, replace the last `TODO` with the following:
|
||||
The only thing left is to create [inventory levels](!resources!/commerce-modules/inventory/concepts#inventorylevel) for the product variants. So, replace the last `TODO` with the following:
|
||||
|
||||
```ts title="src/scripts/demo-products.ts"
|
||||
logger.info("Seeding inventory levels.")
|
||||
@@ -184,7 +186,7 @@ await createInventoryLevelsWorkflow(container).run({
|
||||
logger.info("Finished seeding inventory levels data.")
|
||||
```
|
||||
|
||||
You use Query to retrieve the stock location, to use the first location in the application, and the inventory items.
|
||||
You use [Query](../../module-links/query/page.mdx) to retrieve the first stock location in the application and the inventory items.
|
||||
|
||||
Then, you generate inventory levels for each inventory item, associating it with the first stock location.
|
||||
|
||||
|
||||
@@ -4,30 +4,36 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you'll learn how to pass contexts when retrieving data with [Query](../query/page.mdx).
|
||||
In this chapter, you'll learn how to pass context when retrieving data with [Query](../query/page.mdx).
|
||||
|
||||
## What is Query Context?
|
||||
|
||||
Query context is a way to pass additional information when retrieving data with Query. This data can be useful when applying custom transformations to the retrieved data based on the current context.
|
||||
Query context is additional information you pass to Query when retrieving data. You can use it to apply custom transformations to the returned data based on the current context.
|
||||
|
||||
For example, consider you have a Blog Module with posts and authors. You can accept the user's language as a context and return the posts in the user's language. Another example is how Medusa uses Query Context to [retrieve product variants' prices based on the customer's currency](!resources!/commerce-modules/product/guides/price).
|
||||
For example, consider a Blog Module with posts and authors. You can send the user's language as context to Query to retrieve posts in the user's language.
|
||||
|
||||
Medusa also uses Query Context to [retrieve product variants' prices based on the customer's currency](!resources!/commerce-modules/product/guides/price).
|
||||
|
||||
---
|
||||
|
||||
## How to Use Query Context
|
||||
## How to Pass Query Context
|
||||
|
||||
The `query.graph` method accepts an optional `context` parameter that can be used to pass additional context either to the data model you're retrieving (for example, `post`), or its related and linked models (for example, `author`).
|
||||
The `query.graph` method accepts an optional `context` parameter. You can use this to pass additional context to the data model you're retrieving (for example, `post`) or its related and linked models (for example, `author`).
|
||||
|
||||
You initialize a context using `QueryContext` from the Modules SDK. It accepts an object of contexts as an argument.
|
||||
You can initialize a context using `QueryContext` from the Modules SDK. It accepts an object of contexts as an argument.
|
||||
|
||||
For example, to retrieve posts using Query while passing the user's language as a context:
|
||||
For example, to retrieve posts using Query while passing the user's language as context:
|
||||
|
||||
export const highlights1 = [
|
||||
["4", "context", "Pass additional context to the query."],
|
||||
["4", "QueryContext", "Create a query context."]
|
||||
["8", "context", "Pass additional context to the query."],
|
||||
["8", "QueryContext", "Create a query context."]
|
||||
]
|
||||
|
||||
```ts
|
||||
```ts highlights={highlights1}
|
||||
import { QueryContext } from "@medusajs/framework/utils"
|
||||
|
||||
// ...
|
||||
|
||||
const { data } = await query.graph({
|
||||
entity: "post",
|
||||
fields: ["*"],
|
||||
@@ -37,11 +43,13 @@ const { data } = await query.graph({
|
||||
})
|
||||
```
|
||||
|
||||
In this example, you pass in the context a `lang` property whose value is `es`.
|
||||
In this example, you pass a `lang` property with the value `es` in the context. You create the context using `QueryContext`.
|
||||
|
||||
Then, to handle the context while retrieving records of the data model, in the associated module's service you override the generated `list` method of the data model.
|
||||
### How to Handle Query Context
|
||||
|
||||
For example, continuing the example above, you can override the `listPosts` method of the Blog Module's service to handle the context:
|
||||
To handle the Query context passed while retrieving records of your data models, override the [generated list method](!resources!/service-factory-reference/methods/list) of the associated module's service.
|
||||
|
||||
For example, continuing the example above, you can override the `listPosts` method of the Blog Module's service to handle the Query context:
|
||||
|
||||
export const highlights2 = [
|
||||
["11", "listPosts", "Override the generated listPosts method."],
|
||||
@@ -87,23 +95,17 @@ class BlogModuleService extends MedusaService({
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
In the above example, you override the generated `listPosts` method. This method receives as a first parameter the filters passed to the query, but it also includes a `context` property that holds the context passed to the query.
|
||||
In the above example, you override the generated `listPosts` method. This method receives the filters passed to `query.graph` as its first parameter. The first parameter includes a `context` property that holds the Query context alsopassed to `query.graph`.
|
||||
|
||||
You extract the context from `filters`, then retrieve the posts using the parent's `listPosts` method. After that, if the language is set in the context, you transform the titles of the posts.
|
||||
You extract the context from `filters`, then retrieve the posts using the parent's `listPosts` method. If the language is set in the context, you transform the post titles.
|
||||
|
||||
All posts returned will now have their titles appended with "en español".
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Learn more about the generated `list` method in [this reference](!resources!/service-factory-reference/methods/list).
|
||||
|
||||
</Note>
|
||||
|
||||
### Using Pagination with Query
|
||||
|
||||
If you pass pagination fields to `query.graph`, you must also override the `listAndCount` method in the service.
|
||||
If you pass pagination fields to `query.graph`, you must also override the [generated listAndCount method](!resources!/service-factory-reference/methods/listAndCount) in the service.
|
||||
|
||||
For example, following along with the previous example, you must override the `listAndCountPosts` method of the Blog Module's service:
|
||||
For example, following the previous example, you must override the `listAndCountPosts` method of the Blog Module's service:
|
||||
|
||||
```ts
|
||||
import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
|
||||
@@ -131,7 +133,7 @@ class BlogModuleService extends MedusaService({
|
||||
)
|
||||
|
||||
if (context.lang === "es") {
|
||||
result.posts = posts.map((post) => {
|
||||
result[0] = result[0].map((post) => {
|
||||
return {
|
||||
...post,
|
||||
title: post.title + " en español",
|
||||
@@ -146,17 +148,17 @@ class BlogModuleService extends MedusaService({
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
Now, the `listAndCountPosts` method will handle the context passed to `query.graph` when you pass pagination fields. You can also move the logic to transform the posts' titles to a separate method and call it from both `listPosts` and `listAndCountPosts`.
|
||||
Now, the `listAndCountPosts` method will handle the context passed to `query.graph` when you pass pagination fields. You can also move the logic to transform the post titles to a separate method and call it from both `listPosts` and `listAndCountPosts`.
|
||||
|
||||
---
|
||||
|
||||
## Passing Query Context to Related Data Models
|
||||
|
||||
If you're retrieving a data model and you want to pass context to its associated model in the same module, you can pass them as part of `QueryContext`'s parameter, then handle them in the same `list` method.
|
||||
If you're retrieving a data model and want to pass Query context to its associated model in the same module, pass them as part of `QueryContext`'s parameter. Then, you can handle them in the same `list` method.
|
||||
|
||||
<Note>
|
||||
|
||||
For linked data models, check out the [next section](#passing-query-context-to-linked-data-models).
|
||||
To pass Query context to linked data models, check out the [next section](#passing-query-context-to-linked-data-models).
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -229,15 +231,15 @@ class BlogModuleService extends MedusaService({
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
The context in `filters` will also have the context for `author`, which you can use to make transformations to the post's authors.
|
||||
The context in `filters` will also include the context for `author`, which you can use to transform the post's authors.
|
||||
|
||||
---
|
||||
|
||||
## Passing Query Context to Linked Data Models
|
||||
|
||||
If you're retrieving a data model and you want to pass context to a linked model in a different module, pass to the `context` property an object instead, where its keys are the linked model's name and the values are the context for that linked model.
|
||||
If you're retrieving a data model and want to pass Query context to a linked model in a different module, pass an object to the `context` property instead. The object's keys should be the linked model's name, and the values should be the Query context for that linked model.
|
||||
|
||||
For example, consider the Product Module's `Product` data model is linked to the Blog Module's `Post` data model. You can pass context to the `Post` data model while retrieving products like so:
|
||||
For example, consider the Product Module's `Product` data model is linked to the Blog Module's `Post` data model. You can pass context to the `Post` data model while retrieving products:
|
||||
|
||||
export const highlights5 = [
|
||||
["5", "post", "Pass a context for posts."]
|
||||
@@ -255,6 +257,6 @@ const { data } = await query.graph({
|
||||
})
|
||||
```
|
||||
|
||||
In this example, you retrieve products and their associated posts. You also pass a context for `post`, indicating the customer's language.
|
||||
In this example, you retrieve products and their associated posts. You also pass Query context for `post`, indicating the customer's language.
|
||||
|
||||
To handle the context, you override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-use-query-context).
|
||||
To handle the context, override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-handle-query-context).
|
||||
|
||||
@@ -41,7 +41,7 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/modules/service-factory/page.mdx": "2025-07-31T13:27:53.791Z",
|
||||
"app/learn/fundamentals/modules/module-links/page.mdx": "2024-09-30T08:43:53.126Z",
|
||||
"app/learn/fundamentals/scheduled-jobs/execution-number/page.mdx": "2025-07-25T15:54:56.135Z",
|
||||
"app/learn/fundamentals/api-routes/parameters/page.mdx": "2025-02-14T08:34:03.184Z",
|
||||
"app/learn/fundamentals/api-routes/parameters/page.mdx": "2025-09-15T15:47:08.409Z",
|
||||
"app/learn/fundamentals/api-routes/http-methods/page.mdx": "2025-07-25T15:12:29.347Z",
|
||||
"app/learn/fundamentals/admin/tips/page.mdx": "2025-08-20T11:37:12.855Z",
|
||||
"app/learn/fundamentals/api-routes/cors/page.mdx": "2025-03-11T08:54:26.281Z",
|
||||
@@ -91,7 +91,7 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/modules/infrastructure-modules/page.mdx": "2025-05-21T14:31:51.644Z",
|
||||
"app/learn/introduction/architecture/page.mdx": "2025-07-18T15:52:35.513Z",
|
||||
"app/learn/fundamentals/data-models/infer-type/page.mdx": "2025-03-18T07:41:01.936Z",
|
||||
"app/learn/fundamentals/custom-cli-scripts/seed-data/page.mdx": "2024-12-09T14:38:06.385Z",
|
||||
"app/learn/fundamentals/custom-cli-scripts/seed-data/page.mdx": "2025-09-15T16:02:51.362Z",
|
||||
"app/learn/fundamentals/environment-variables/page.mdx": "2025-05-26T15:06:07.800Z",
|
||||
"app/learn/build/page.mdx": "2025-04-25T12:34:33.914Z",
|
||||
"app/learn/deployment/general/page.mdx": "2025-09-01T06:21:43.760Z",
|
||||
@@ -104,7 +104,7 @@ export const generatedEditDates = {
|
||||
"app/learn/fundamentals/plugins/page.mdx": "2025-01-22T10:14:10.433Z",
|
||||
"app/learn/customization/reuse-customizations/page.mdx": "2025-09-04T15:45:52.047Z",
|
||||
"app/learn/update/page.mdx": "2025-01-27T08:45:19.030Z",
|
||||
"app/learn/fundamentals/module-links/query-context/page.mdx": "2025-02-12T16:59:20.963Z",
|
||||
"app/learn/fundamentals/module-links/query-context/page.mdx": "2025-09-15T16:09:58.104Z",
|
||||
"app/learn/fundamentals/admin/environment-variables/page.mdx": "2025-08-01T13:16:25.172Z",
|
||||
"app/learn/fundamentals/api-routes/parse-body/page.mdx": "2025-08-20T09:58:37.704Z",
|
||||
"app/learn/fundamentals/admin/routing/page.mdx": "2025-07-25T07:35:18.038Z",
|
||||
|
||||
@@ -8591,15 +8591,15 @@ The value of `req.query.name` is the value passed in `?name=John`, for example.
|
||||
|
||||
You can apply validation rules on received query parameters to ensure they match specified rules and types.
|
||||
|
||||
Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-query-paramters/index.html.md).
|
||||
Learn more in the [API Route Validation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-query-parameters/index.html.md) chapter.
|
||||
|
||||
***
|
||||
|
||||
## Request Body Parameters
|
||||
|
||||
The Medusa application parses the body of any request having a JSON, URL-encoded, or text request content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
|
||||
The Medusa application parses the body of any request with JSON, URL-encoded, or text content types. The request body parameters are set in the `MedusaRequest`'s `body` property.
|
||||
|
||||
Learn more about configuring body parsing in [this guide](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md).
|
||||
Learn more about configuring body parsing in the [Body Parsing](https://docs.medusajs.com/learn/fundamentals/api-routes/parse-body/index.html.md) chapter.
|
||||
|
||||
For example:
|
||||
|
||||
@@ -8649,7 +8649,7 @@ This returns the following JSON object:
|
||||
|
||||
You can apply validation rules on received body parameters to ensure they match specified rules and types.
|
||||
|
||||
Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-body/index.html.md).
|
||||
Learn more in the [Body Validation](https://docs.medusajs.com/learn/fundamentals/api-routes/validation#how-to-validate-request-body/index.html.md) chapter.
|
||||
|
||||
|
||||
# Configure Request Body Parser
|
||||
@@ -9695,7 +9695,7 @@ The `startup` script will run every time you run the Medusa application.
|
||||
|
||||
# Seed Data with Custom CLI Script
|
||||
|
||||
In this chapter, you'll learn how to seed data using a custom CLI script.
|
||||
In this chapter, you'll learn how to seed data using a [custom CLI script](https://docs.medusajs.com/learn/fundamentals/custom-cli-scripts/index.html.md).
|
||||
|
||||
## How to Seed Data
|
||||
|
||||
@@ -9703,7 +9703,9 @@ To seed dummy data for development or demo purposes, use a custom CLI script.
|
||||
|
||||
In the CLI script, use your custom workflows or Medusa's existing workflows, which you can browse in [this reference](https://docs.medusajs.com/resources/medusa-workflows-reference/index.html.md), to seed data.
|
||||
|
||||
### Example: Seed Dummy Products
|
||||
***
|
||||
|
||||
## Example: Seed Dummy Products
|
||||
|
||||
In this section, you'll follow an example of creating a custom CLI script that seeds fifty dummy products.
|
||||
|
||||
@@ -9757,8 +9759,8 @@ export default async function seedDummyProducts({
|
||||
|
||||
So far, in the script, you:
|
||||
|
||||
- Resolve the Sales Channel Module's main service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
|
||||
- Resolve the Logger to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
|
||||
- Resolve the [Sales Channel Module](https://docs.medusajs.com/resources/commerce-modules/sales-channel/index.html.md)'s service to retrieve the application's default sales channel. This is the sales channel the dummy products will be available in.
|
||||
- Resolve the [Logger](https://docs.medusajs.com/learn/debugging-and-testing/logging/index.html.md) to log messages in the terminal, and Query to later retrieve data useful for the seeded products.
|
||||
- Initialize some default data to use when seeding the products next.
|
||||
|
||||
Next, replace the `TODO` with the following:
|
||||
@@ -9768,7 +9770,7 @@ const productsData = new Array(productsNum).fill(0).map((_, index) => {
|
||||
const title = faker.commerce.product() + "_" + index
|
||||
return {
|
||||
title,
|
||||
is_giftcard: true,
|
||||
is_giftcard: false,
|
||||
description: faker.commerce.productDescription(),
|
||||
status: ProductStatus.PUBLISHED,
|
||||
options: [
|
||||
@@ -9834,7 +9836,7 @@ logger.info(`Seeded ${products.length} products.`)
|
||||
|
||||
You create the generated products using the `createProductsWorkflow` imported previously from `@medusajs/medusa/core-flows`. It accepts the product data as input, and returns the created products.
|
||||
|
||||
Only thing left is to create inventory levels for the products. So, replace the last `TODO` with the following:
|
||||
The only thing left is to create [inventory levels](https://docs.medusajs.com/resources/commerce-modules/inventory/concepts#inventorylevel/index.html.md) for the product variants. So, replace the last `TODO` with the following:
|
||||
|
||||
```ts title="src/scripts/demo-products.ts"
|
||||
logger.info("Seeding inventory levels.")
|
||||
@@ -9864,7 +9866,7 @@ await createInventoryLevelsWorkflow(container).run({
|
||||
logger.info("Finished seeding inventory levels data.")
|
||||
```
|
||||
|
||||
You use Query to retrieve the stock location, to use the first location in the application, and the inventory items.
|
||||
You use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md) to retrieve the first stock location in the application and the inventory items.
|
||||
|
||||
Then, you generate inventory levels for each inventory item, associating it with the first stock location.
|
||||
|
||||
@@ -14095,25 +14097,31 @@ npx medusa db:migrate
|
||||
|
||||
# Query Context
|
||||
|
||||
In this chapter, you'll learn how to pass contexts when retrieving data with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
|
||||
In this chapter, you'll learn how to pass context when retrieving data with [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query/index.html.md).
|
||||
|
||||
## What is Query Context?
|
||||
|
||||
Query context is a way to pass additional information when retrieving data with Query. This data can be useful when applying custom transformations to the retrieved data based on the current context.
|
||||
Query context is additional information you pass to Query when retrieving data. You can use it to apply custom transformations to the returned data based on the current context.
|
||||
|
||||
For example, consider you have a Blog Module with posts and authors. You can accept the user's language as a context and return the posts in the user's language. Another example is how Medusa uses Query Context to [retrieve product variants' prices based on the customer's currency](https://docs.medusajs.com/resources/commerce-modules/product/guides/price/index.html.md).
|
||||
For example, consider a Blog Module with posts and authors. You can send the user's language as context to Query to retrieve posts in the user's language.
|
||||
|
||||
Medusa also uses Query Context to [retrieve product variants' prices based on the customer's currency](https://docs.medusajs.com/resources/commerce-modules/product/guides/price/index.html.md).
|
||||
|
||||
***
|
||||
|
||||
## How to Use Query Context
|
||||
## How to Pass Query Context
|
||||
|
||||
The `query.graph` method accepts an optional `context` parameter that can be used to pass additional context either to the data model you're retrieving (for example, `post`), or its related and linked models (for example, `author`).
|
||||
The `query.graph` method accepts an optional `context` parameter. You can use this to pass additional context to the data model you're retrieving (for example, `post`) or its related and linked models (for example, `author`).
|
||||
|
||||
You initialize a context using `QueryContext` from the Modules SDK. It accepts an object of contexts as an argument.
|
||||
You can initialize a context using `QueryContext` from the Modules SDK. It accepts an object of contexts as an argument.
|
||||
|
||||
For example, to retrieve posts using Query while passing the user's language as a context:
|
||||
For example, to retrieve posts using Query while passing the user's language as context:
|
||||
|
||||
```ts highlights={highlights1}
|
||||
import { QueryContext } from "@medusajs/framework/utils"
|
||||
|
||||
// ...
|
||||
|
||||
```ts
|
||||
const { data } = await query.graph({
|
||||
entity: "post",
|
||||
fields: ["*"],
|
||||
@@ -14123,11 +14131,13 @@ const { data } = await query.graph({
|
||||
})
|
||||
```
|
||||
|
||||
In this example, you pass in the context a `lang` property whose value is `es`.
|
||||
In this example, you pass a `lang` property with the value `es` in the context. You create the context using `QueryContext`.
|
||||
|
||||
Then, to handle the context while retrieving records of the data model, in the associated module's service you override the generated `list` method of the data model.
|
||||
### How to Handle Query Context
|
||||
|
||||
For example, continuing the example above, you can override the `listPosts` method of the Blog Module's service to handle the context:
|
||||
To handle the Query context passed while retrieving records of your data models, override the [generated list method](https://docs.medusajs.com/resources/service-factory-reference/methods/list/index.html.md) of the associated module's service.
|
||||
|
||||
For example, continuing the example above, you can override the `listPosts` method of the Blog Module's service to handle the Query context:
|
||||
|
||||
```ts highlights={highlights2}
|
||||
import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
|
||||
@@ -14166,19 +14176,17 @@ class BlogModuleService extends MedusaService({
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
In the above example, you override the generated `listPosts` method. This method receives as a first parameter the filters passed to the query, but it also includes a `context` property that holds the context passed to the query.
|
||||
In the above example, you override the generated `listPosts` method. This method receives the filters passed to `query.graph` as its first parameter. The first parameter includes a `context` property that holds the Query context alsopassed to `query.graph`.
|
||||
|
||||
You extract the context from `filters`, then retrieve the posts using the parent's `listPosts` method. After that, if the language is set in the context, you transform the titles of the posts.
|
||||
You extract the context from `filters`, then retrieve the posts using the parent's `listPosts` method. If the language is set in the context, you transform the post titles.
|
||||
|
||||
All posts returned will now have their titles appended with "en español".
|
||||
|
||||
Learn more about the generated `list` method in [this reference](https://docs.medusajs.com/resources/service-factory-reference/methods/list/index.html.md).
|
||||
|
||||
### Using Pagination with Query
|
||||
|
||||
If you pass pagination fields to `query.graph`, you must also override the `listAndCount` method in the service.
|
||||
If you pass pagination fields to `query.graph`, you must also override the [generated listAndCount method](https://docs.medusajs.com/resources/service-factory-reference/methods/listAndCount/index.html.md) in the service.
|
||||
|
||||
For example, following along with the previous example, you must override the `listAndCountPosts` method of the Blog Module's service:
|
||||
For example, following the previous example, you must override the `listAndCountPosts` method of the Blog Module's service:
|
||||
|
||||
```ts
|
||||
import { MedusaContext, MedusaService } from "@medusajs/framework/utils"
|
||||
@@ -14206,7 +14214,7 @@ class BlogModuleService extends MedusaService({
|
||||
)
|
||||
|
||||
if (context.lang === "es") {
|
||||
result.posts = posts.map((post) => {
|
||||
result[0] = result[0].map((post) => {
|
||||
return {
|
||||
...post,
|
||||
title: post.title + " en español",
|
||||
@@ -14221,15 +14229,15 @@ class BlogModuleService extends MedusaService({
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
Now, the `listAndCountPosts` method will handle the context passed to `query.graph` when you pass pagination fields. You can also move the logic to transform the posts' titles to a separate method and call it from both `listPosts` and `listAndCountPosts`.
|
||||
Now, the `listAndCountPosts` method will handle the context passed to `query.graph` when you pass pagination fields. You can also move the logic to transform the post titles to a separate method and call it from both `listPosts` and `listAndCountPosts`.
|
||||
|
||||
***
|
||||
|
||||
## Passing Query Context to Related Data Models
|
||||
|
||||
If you're retrieving a data model and you want to pass context to its associated model in the same module, you can pass them as part of `QueryContext`'s parameter, then handle them in the same `list` method.
|
||||
If you're retrieving a data model and want to pass Query context to its associated model in the same module, pass them as part of `QueryContext`'s parameter. Then, you can handle them in the same `list` method.
|
||||
|
||||
For linked data models, check out the [next section](#passing-query-context-to-linked-data-models).
|
||||
To pass Query context to linked data models, check out the [next section](#passing-query-context-to-linked-data-models).
|
||||
|
||||
For example, to pass a context for the post's authors:
|
||||
|
||||
@@ -14292,15 +14300,15 @@ class BlogModuleService extends MedusaService({
|
||||
export default BlogModuleService
|
||||
```
|
||||
|
||||
The context in `filters` will also have the context for `author`, which you can use to make transformations to the post's authors.
|
||||
The context in `filters` will also include the context for `author`, which you can use to transform the post's authors.
|
||||
|
||||
***
|
||||
|
||||
## Passing Query Context to Linked Data Models
|
||||
|
||||
If you're retrieving a data model and you want to pass context to a linked model in a different module, pass to the `context` property an object instead, where its keys are the linked model's name and the values are the context for that linked model.
|
||||
If you're retrieving a data model and want to pass Query context to a linked model in a different module, pass an object to the `context` property instead. The object's keys should be the linked model's name, and the values should be the Query context for that linked model.
|
||||
|
||||
For example, consider the Product Module's `Product` data model is linked to the Blog Module's `Post` data model. You can pass context to the `Post` data model while retrieving products like so:
|
||||
For example, consider the Product Module's `Product` data model is linked to the Blog Module's `Post` data model. You can pass context to the `Post` data model while retrieving products:
|
||||
|
||||
```ts highlights={highlights5}
|
||||
const { data } = await query.graph({
|
||||
@@ -14314,9 +14322,9 @@ const { data } = await query.graph({
|
||||
})
|
||||
```
|
||||
|
||||
In this example, you retrieve products and their associated posts. You also pass a context for `post`, indicating the customer's language.
|
||||
In this example, you retrieve products and their associated posts. You also pass Query context for `post`, indicating the customer's language.
|
||||
|
||||
To handle the context, you override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-use-query-context).
|
||||
To handle the context, override the generated `listPosts` method of the Blog Module as explained [previously](#how-to-handle-query-context).
|
||||
|
||||
|
||||
# Query
|
||||
|
||||
Reference in New Issue
Block a user