What’s Subgraph and The Components of a Subgraph

What’s Subgraph

A subgraph defines which data The Graph will index from Ethereum, and how it will store it. Once deployed, it will form a part of a global graph of blockchain data. The subgraph definition consists of a few files:

The Subgraph Manifest(Subgraph.yaml)

The subgraph manifest subgraph.yaml defines the smart contracts your subgraph indexes, which events from these contracts to pay attention to, and how to map event data to entities that Graph Node stores and allows to query. An example of subgraph.yaml:


The GraphQL Schema

A GraphQL schema that defines what data is stored for your subgraph, and how to query it via GraphQL. The schema for your subgraph is in the file schema.graphql.

Defining Entities(What data to store for subgraph?)

All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dApp. It may be useful to imagine entities as “objects containing data”, rather than as events or functions.With The Graph, you simply define entity types in schema.graphql.

Entities Defining

Defining Fulltext Search Fields(How to query data stored?)

Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing to the indexed text data.

Fulltext Query


The mappings transform the Ethereum data your mappings are sourcing into entities defined in your schema. Mappings are written in a subset of TypeScript called AssemblyScript.

Event Handlers

For each event handler that is defined in subgraph.yaml under mapping.eventHandlers, create an exported function of the same name. Each handler must accept a single parameter called event with a type corresponding to the name of the event which is being handled.

Event Handlers
Event Handler Mapping Code

Call Handlers

While events provide an effective way to collect relevant changes to the state of a contract, many contracts avoid generating logs to optimize gas costs. In these cases, a subgraph can subscribe to calls made to the data source contract. This is achieved by defining call handlers referencing the function signature and the mapping handler that will process calls to this function. To process these calls, the mapping handler will receive an ethereum.Call as an argument with the typed inputs to and outputs from the call. Calls made at any depth in a transaction’s call chain will trigger the mapping, allowing activity with the data source contract through proxy contracts to be captured.

Call Handler
Call Handler Mapping Code

Block Handlers

In addition to subscribing to contract events or function calls, a subgraph may want to update its data as new blocks are appended to the chain. To achieve this a subgraph can run a function after every block or after blocks that match a predefined filter.

Block Handler
Block Handler Mapping Code


This document has simplified the papers supplied by TheGraph official team, which in my opinion, are a little bit complex for new beginner. It gave an introduction of subgraph. With this document, I hope sincerely it would help those who are struggling and TheGraph would be better~



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store