5.4.3. Query

In this chapter, you’ll learn about the Query utility and how to use it to fetch data from modules.

In DevelopmentQuery is in development and is subject to change in future releases.

What is Query?#

Query fetches data across modules. It’s a set of methods registered in the Medusa container under the query key.

In your resources, such as API routes or workflows, you can resolve Query to fetch data across custom modules and Medusa’s commerce modules.


Query Example#

For example, create the route src/api/query/route.ts with the following content:

src/api/query/route.ts
7} from "@medusajs/framework/utils"8
9export const GET = async (10  req: MedusaRequest,11  res: MedusaResponse12) => {13  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)14
15  const { data: myCustoms } = await query.graph({16    entity: "my_custom",17    fields: ["id", "name"],18  })19
20  res.json({ my_customs: myCustoms })21}

In the above example, you resolve Query from the Medusa container using the ContainerRegistrationKeys.QUERY (query) key.

Then, you run a query using its graph method. This method accepts as a parameter an object with the following required properties:

  • entity: The data model's name, as specified in the first parameter of the model.define method used for the data model's definition.
  • fields: An array of the data model’s properties to retrieve in the result.

The method returns an object that has a data property, which holds an array of the retrieved data. For example:

Returned Data
1{2  "data": [3    {4      "id": "123",5      "name": "test"6    }7  ]8}

Querying the Graph#

When you use the query.graph method, you're running a query through an internal graph that the Medusa application creates.

This graph collects data models of all modules in your application, including commerce and custom modules, and identifies relations and links between them.


Retrieve Linked Records#

Retrieve the records of a linked data model by passing in fields the data model's name suffixed with .*.

For example:

Code
1const { data: myCustoms } = await query.graph({2  entity: "my_custom",3  fields: [4    "id", 5    "name",6    "product.*",7  ],8})
Tip.* means that all of data model's properties should be retrieved. To retrieve a specific property, replace the * with the property's name. For example, product.title .

If the linked data model has isList enabled in the link definition, pass in fields the data model's plural name suffixed with .*.

For example:

Code
1const { data: myCustoms } = await query.graph({2  entity: "my_custom",3  fields: [4    "id", 5    "name",6    "products.*",7  ],8})

Apply Filters#

Code
1const { data: myCustoms } = await query.graph({2  entity: "my_custom",3  fields: ["id", "name"],4  filters: {5    id: [6      "mc_01HWSVWR4D2XVPQ06DQ8X9K7AX",7      "mc_01HWSVWK3KYHKQEE6QGS2JC3FX",8    ],9  },10})

The query.graph function accepts a filters property. You can use this property to filter retrieved records.

In the example above, you filter the my_custom records by multiple IDs.

NoteFilters don't apply on fields of linked data models from other modules.

Sort Records#

Code
1const { data: myCustoms } = await query.graph({2  entity: "my_custom",3  fields: ["id", "name"],4  pagination: {5    order: {6      name: "DESC",7    },8  },9})
NoteSorting 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#

Code
1const { 2  data: myCustoms,3  metadata: { count, take, skip },4} = await query.graph({5  entity: "my_custom",6  fields: ["id", "name"],7  pagination: {8    skip: 0,9    take: 10,10  },11})

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.
  • take: The number of records to fetch.

When you provide the pagination fields, the query.graph method's returned object has a metadata property. Its value is an object having the following properties:

skipnumber
The number of records skipped.
takenumber
The number of records requested to fetch.
countnumber
The total number of records.
Was this chapter helpful?
Edit this page