4.2.6. Remote Query

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

What is the Remote Query?#

The remote query fetches data across modules. It’s a function registered in the Medusa container under the remoteQuery key.

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


Remote Query Example#

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

src/api/store/query/route.ts
11} from "@medusajs/modules-sdk"12
13export async function GET(14  req: MedusaRequest,15  res: MedusaResponse16): Promise<void> {17  const remoteQuery: RemoteQueryFunction = req.scope.resolve(18    ContainerRegistrationKeys.REMOTE_QUERY19  )20
21  const query = remoteQueryObjectFromString({22    entryPoint: "my_custom",23    fields: ["id", "name"],24  })25
26  res.json({27    my_customs: await remoteQuery(query),28  })29}

In the above example, you resolve remoteQuery from the Medusa container.

Then, you create a query using the remoteQueryObjectFromString utility function imported from @medusajs/utils. This function accepts as a parameter an object with the following required properties:

  • entryPoint: 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.

You then pass the query to the remoteQuery function to retrieve the results.


Retrieve Linked Records#

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

For example:

1const query = remoteQueryObjectFromString({2  entryPoint: "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:

1const query = remoteQueryObjectFromString({2  entryPoint: "my_custom",3  fields: [4    "id", 5    "name",6    "products.*"7  ],8})

Apply Filters#

1const query = remoteQueryObjectFromString({2  entryPoint: "my_custom",3  fields: ["id", "name"],4  variables: {5    filters: {6      id: [7        "mc_01HWSVWR4D2XVPQ06DQ8X9K7AX",8        "mc_01HWSVWK3KYHKQEE6QGS2JC3FX",9      ],10    },11  },12})13
14const result = await remoteQuery(query)

The remoteQueryObjectFromString function accepts a variables property. You can use this property to filter retrieved records.

variablesobject
Variables to pass to the query.

Sort Records#

1const query = remoteQueryObjectFromString({2  entryPoint: "my_custom",3  fields: ["id", "name"],4  variables: {5    order: {6      name: "DESC",7    },8  },9})10
11const result = await remoteQuery(query)

To sort returned records, pass an order property to variables.

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#

1const query = remoteQueryObjectFromString({2  entryPoint: "my_custom",3  fields: ["id", "name"],4  variables: {5    skip: 0,6    take: 10,7  },8})9
10const { 11  rows, 12  metadata: { count, take, skip },13} = await remoteQuery(query)

To paginate the returned records, pass the following properties to variables:

  • skip: (required to apply pagination) The number of records to skip before fetching the results.
  • take: The number of records to fetch.

When the pagination fields are provided, the remoteQuery returns an object having two properties:

rowsarray
The returned records.
metadataobject
The pagination details

Using GraphQL#

The remote query function alternatively accepts a string with GraphQL syntax as the query.

Basic GraphQL usage#

src/api/store/query/route.ts
9
10export async function GET(11  req: MedusaRequest,12  res: MedusaResponse13): Promise<void> {14  const remoteQuery: RemoteQueryFunction = req.scope.resolve(15    ContainerRegistrationKeys.REMOTE_QUERY16  )17
18  const query = `19    query {20      my_custom {21        id22        name23      }24    }25  `26
27  const result = await remoteQuery(query)28
29  res.json({30    my_customs: result,31  })32}
Was this chapter helpful?