5.3.8. Query

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

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
Show Imports
7} from "@medusajs/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})

Retrieve List Link Records#

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.

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})

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: