GraphQL: Retrieving data from Masterdata

GraphQL: Retrieving data from Master Data


Now that we have updated the product count, we need to retrieve the top n most viewed products. We can, then, use Master Data to retrieve the product page view data and sort by the count field. We can also limit the length of retrieved products, creating a customized size rank of most-visited products.


To get these product page views, we will use GraphQL, the technology used by VTEX IO for data fetching, to implement a query to Master Data. GraphQL allows us to implement queries in a simple and easy way, specifying the data you want to retrieve. This makes your API reliable since GraphQL controls the data fetched instead of the server itself.

It's also the only possible way to create an interface between services and front end applications.

Therefore, GraphQL uses types and a query schema to specify the data retrieved and resolvers to get the exact data needed.

Retrieving data from Master Data

  1. Inside the /graphql directory, create a folder called /types. In this folder, create the productView.graphql file and declare the type of the product list we want to retrieve:

    # /graphql/types/productView.graphql
    type ProductView {
        slug: String
        count: Int
  2. Still in the /graphql directory, define the schema in the schema.graphql file:

    type Query {
        productList(topN: Int): [ProductView]

    Keep in mind that the schema will define the structure of our query and the retrieved data.

    Also, in this declaration you can include directives. In some cases, it is required, for example, if you need to get the user token or use cookies (e.g.: OrderForm). To read more about it, check out this link.

  3. With the schema, types, and the query defined, we need to create the query's resolver. The resolver is what happens when a query is executed. In our case, we want to perform a scroll on Master Data, ordering by the count (as we want to get a topmost viewed products) and limiting the page size (the top n). To define this resolver, in the /node/resolvers directory, create the file products.ts and do the following:

    // node/resolvers/products.ts
    import { COURSE_ENTITY } from '../utils/constants'
    export const productList = async (
      _: any,
      { topN }: { topN: number },
      { clients: { masterdata } }: Context
    ) =>
          dataEntity: COURSE_ENTITY,
          fields: ['count', 'slug'],
          schema: 'v1',
          size: topN,
          sort: `count DESC`,
        .then(({ data }) => data)

    Note: you can check the Master Data scroll documentation in this link.

  4. Import the resolver on the index.ts file:

import { productList } from './resolvers/products'
  1. At last, we need to update the index.ts file to set up the resolver and the query. Complete the service declaration as below:

            graphql: {
                resolvers: {
                    Query: {

    And, also, remember to add the graphql builder on the manifest.json:

    "builders": {
    +   "graphql": "1.x",
        "docs": "0.x",
        "node": "6.x"

    Finally, link the app and you should get a GraphQL route. The result should be like this:


Any questions?

See the answersheet for this step or check our [office hours] on the VTEX Developers channel(

Help us make this content better!

VTEX IO courses are open source. If you see something wrong, you can open a pull request!

Make a contribution

or open an issue