Basic Components of a Subgraph

Jerry Okolo
3 min readDec 8, 2020

In this post, I’m going to share with you what a subgraph is and its fundamental components. This will help you understand how it tracks, structures, and indexes on-chain data for anyone to query.

A subgraph defines which data The Graph will index from Ethereum, and how it will store it. It consists of three main components:

  • Subgraph Manifest
  • Subgraph Schema
  • AssemblyScript Mappings

Subgraph Manifest

The subgraph manifest is a file that tracks events on-chain. It hones in on specified smart contracts and listens for when events or functions are triggered. I’m going to use a subgraph I developed as an example.

As you can see in the image below, the subgraph manifest tracks a specified smart contract on-chain for certain events or function calls. An event is emitted whenever someone redeems an mETH token. So this tells the graph node to focus on that event on-chain.

Subgraph Manifest (.yaml)

Subgraph Schema

The subgraph schema defines how the data is structured and how it’s presented when queried. It is important you understand the data on-chain because knowing that will help you define the entities in your schema correctly as you write your code.

Going back to my example, if I want to present the data whenever an mETH token is redeemed, and I incorrectly define the entity as mETHTransfer, then whoever uses the subgraph for their dApp will be presenting the wrong data to their users. This is because the entity “mETHTransfer” will be presenting data for mETH tokens redeemed instead of mETH tokens transferred. Understanding the data and structuring it correctly is paramount. The image below shows how an entity in a schema is defined.

Subgraph Schema(.GraphQL)

AssemblyScript Mappings

The mappings file, written in a subset of Typescript called AssemblyScript, links the data received from the events the subgraph manifest is tracking to the subgraph schema. It’s like the pipe that links both. In the featured image in this post, I show you how it all links together. The mappings also save the data to the store, so it’s served very quickly when queried.


Querying the Data

In The Graph playground as seen in the image below, this is the effect of the three files above.

On the left-hand side is the GraphQL code to query the data. The center is the data it returns when I hit the play button, and on the right-hand side is the GraphQL schema I defined in subgraph schema above.

The Graph Playground

With these basic components, you understand now how The Graph indexes and serves on-chain data.

You can learn more by visiting The Graph docs. This article gives you a brief overview of what goes on behind the curtains.

If you have any questions, feel free to send me a message.