Developer onboarding

Deploying Subgraphs

The first step in developing a subgraph is to create the subgraph manifest and to generate code for the subgraph by installing the Graph CLI. Once you have accomplished this, you can then deploy your subgraph in the next step.

1. Creating a Graph Explorer account.

To use The Graph’s Hosted Service, you need an account in The Graph Explorer. Signing up is a seamless process as you can use your Github account.

2. Storing the Access Token.

Once you are registered with The Graph’s Explorer, move to your account’s dashboard. To store the access token of your dashboard on your computer, copy the access token that is displayed. Then, run the following command:

Copy to Clipboard

This is not a mandatory step for each new session. Just keep in mind that you have would have to repeat this process when you generate a new access token.

3. Creating the Subgraph

The last step before you are ready to deploy your subgraph is to add your subgraph to The Graph Explorer. You can do this by navigating to the dashboard and clicking “Add Subgraph.”

On others left now is to safe and create your new subgraph. You will be followed up with instructions that guides you through installing the Graph CLI and defining your subgraph. Both topics are covered in the previous guide on defining subgraphs. The other instructions listed is about deploying your subgraph, which we will have a look at the following.

4. Deploying Your Subgraph.

The process of deploying your subgraph is straightforward. Simply run the command yarn deploy to deploy your subgraph. What this does is to upload the subgraph’s files to IPFS with yarn build. It will also notify The Graph Explorer so that it starts indexing your subgraph.

The process of syncing can vary from a few minutes to several hours. This depends on the amount of data/events that would have to be extracted from historical blocks by The Graph Node. The synchronization status of your subgraph will be shown in the Graph Explorer. Once all the data has been extracted, the status switches to Synced.

New Ethereum blocks will continuously be inspected by The Graph Node as these blocks are mined.

5. Redeploying your subgraph.

Keep in mind that you will have to redeploy your subgraph whenever you make changes to its definition (i.e. its entity mappings etc.). To do so, run the command yarn deploy. This will get the updated version of subgraph redeployed. Depending on how many blocks have been added to the chain, the process of redeploying your subgraph could take some time. This is because The Graph Node with have to start reindexing the entire subgraph starting at the genesis block.

The newly deployed version of your subgraph will immediately replace a previously deployed subgraph that is still Syncing. If the synchronization process has already finished, the newly deployed version of your subgraph will be marked as Pending Version. Once syncing has finished, the new version will replace the old one. This will allow you to keep your services live while you are synchronizing the new version.

A) Deploying your subgraph to multiple Ethereum networks

Deploying one subgraph to multiple ETH networks without duplicating its code is a challenge, as contract addresses for each network are different. You can address this challenge by using a templating system, for example. This will enable you to parameterize aspects like contract addresses.

This is how you would go ahead if you wanted to deploy a subgraph to the Ethereum mainnet but also to ropsten by creating two config files that provide the addresses for each network:

Copy to Clipboard
Copy to Clipboard

Next, you will have to use the variable placeholders {{address}} and {{network}} to subsitute the substitute the network addresses and name in your subgraph’s manifest. After this, rename the manifest, for example to: subgraph.template.yaml:

Copy to Clipboard

If you want to generate a manifest to both networks, these are the two additional commands you will have to add to package.json with a dependency on mustache:

Copy to Clipboard

After this, you can deploy your subgraph to either the mainnet or to Ropsten, use one of the two commands:

Copy to Clipboard

If you want to see an example of how this all works, have a look at this.

Important: Using this approach is not limited to only two networks. You can also apply it in more complex situations. This could be for instance when you want to substitute more valuables than just network names and contract addresses like generating ABIs or mappings from templates.

6. Checking the health of your subgraph.

The best sign of a healthy subgraph is that it has successfully synchronized. Along the road, it’s possible that new triggers on the blockchain cause issues. These issues could be untested error conditions but also issues with performance or node operators.

To check the health of your subgraph, you can query a GraphQL endpoint that the Graph Node exposes. If you are using the hosted service, the endpoint is available at: To check of the status of the current version of your subgraph, you can use this sample query:

Copy to Clipboard

If you want to reference the full schema for this endpoint, you can find it here.

The sample query will provide you the chainHeadBlock. You can use this to compare it with the latestBlock to see it’s status and whether or not it’s running behind. The three outputs synced, healthy, failed and fatalError inform you about the state of the subgraph.


After you have created and defined your subgraph, you’re now able to deploy it to the Hosted Service.

Go Back

Developer Knowledge Hub