Skip to main content

How to Use the Subgraph Studio

Welcome to your new launchpad 👩🏽‍🚀

The Subgraph Studio is your place to build and create subgraphs, add metadata, and publish them to the new decentralized Explorer (more on that here).

What you can do in the Subgraph Studio:

  • Create a subgraph through the Studio UI
  • Deploy a subgraph using the CLI
  • Publish a subgraph with the Studio UI
  • Test it in the playground
  • Integrate it in staging using the query URL
  • Create and manage your API keys for specific subgraphs

Here in the Subgraph Studio, you have full control over your subgraphs. Not only can you test your subgraphs before you publish them, but you can also restrict your API keys to specific domains and only allow certain indexers to query from their API keys.

Querying subgraphs generates query fees, used to reward indexers on the Graph network. If you’re a dApp developer or subgraph developer, the Studio will empower you to build better subgraphs to power your or your community’s queries. The Studio is comprised of 5 main parts:

  • Your user account controls
  • A list of subgraphs that you’ve created
  • A section to manage, view details, and visualize the status of a specific subgraph
  • A section to manage your API keys that you will need to query a subgraph
  • A section to manage your billing

How to Create Your Account#

  1. Sign in with your wallet - you can do this via MetaMask or WalletConnect
  2. Once you sign in, you will see your unique deploy key in your account home page. This will allow you to either publish your subgraphs or manage your API keys + billing. You will have a unique deploy key that can be re-generated if you think it has been compromised.

How to Create your Subgraph in Subgraph Studio#

The best part! When you first create a subgraph, you’ll be directed to fill out:

  • Your Subgraph Name
  • Image
  • Description
  • Categories
  • Website

Subgraph Compatibility with The Graph Network#

The Graph Network is not yet able to support all of the data-sources & features available on the Hosted Service. In order to be supported by indexers on the network, subgraphs must:

  • Index mainnet Ethereum
  • Must not use any of the following features:
    • ipfs.cat & ipfs.map
    • Non-fatal errors
    • Grafting

More features & networks will be added to The Graph Network incrementally.

Subgraph lifecycle flow#

Subgraph Lifecycle

After you have created your subgraph, you will be able to deploy it using the CLI, or command line interface. Deploying a subgraph with the CLI will push the subgraph to the Studio where you’ll be able to test subgraphs using the playground. This will eventually allow you to publish to the Graph Network. For more information on CLI setup, check this out (pst, make sure you have your deploy key on hand). Remember, deploying is not the same as publishing. When you deploy a subgraph, you just push it to the Studio where you’re able to test it. Versus, when you publish a subgraph, you are publishing it on-chain.

Testing your Subgraph in Subgraph Studio#

If you’d like to test your subgraph before publishing it to the network, you can do this in the Subgraph Playground or look at your logs. The Subgraph logs will tell you where your subgraph fails in the case that it does.

Publish your Subgraph in Subgraph Studio#

You’ve made it this far - congrats! Publishing your subgraph means that an IPFS hash was generated when you deployed the subgraph within the CLI and is stored in the network’s Ethereum smart contracts. In order to publish your subgraph successfully, you’ll need to go through the following steps outlined in this blog. Check out the video overview below as well:

Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements.

You’ll only be able to index data from mainnet (even if your subgraph was published to a testnet) because only subgraphs that are indexing mainnet data can be published to the network. This is because indexers need to submit mandatory Proof of Indexing records as of a specific block hash. Because publishing a subgraph is an action taken on-chain, remember that the transaction can take up to a few minutes to go through. Any address you use to publish the contract will be the only one able to publish future versions. Choose wisely!

Subgraphs with curation signal are shown to Indexers so that they can be indexed on the decentralized network. You can publish subgraphs and signal in one transaction, which allows you to mint the first curation signal on the subgraph and saves on gas costs. By adding your signal to the signal later provided by Curators, your subgraph will also have a higher chance of ultimately serving queries.

Now that you’ve published your subgraph, let’s get into how you’ll manage them on a regular basis. Note that you cannot publish your subgraph to the network if it has failed syncing. This is usually because the subgraph has bugs - the logs will tell you where those issues exist!

Versioning your Subgraph with the CLI#

Developers might want to update their subgraph, for a variety of reasons. When this is the case, you can deploy a new version of your subgraph to the Studio using the CLI (it will only be private at this point) and if you are happy with it, you can publish this new deployment to The Graph Explorer. This will create a new version of your subgraph that curators can start signaling on and indexers will be able to index this new version.

Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs without having to publish a new version. Developers can update their subgraph details in the Studio (under profile picture, name, description, etc) by checking an option called Update Details in The Graph Explorer. If this is checked, an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment.

Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more here.

Automatic Archiving of Subgraph Versions#

Whenever you deploy a new subgraph version in the Subgraph Studio, the previous version will be archived. Archived versions won't be indexed/synced and therefore cannot be queried. You can unarchive an archived version of your subgraph in the Studio UI. Please note that previous versions of non-published subgraphs deployed to the Studio will be automatically archived.

Subgraph Studio - Unarchive

Managing your API Keys#

Regardless of whether you’re a dApp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application.

The Studio will list out existing API keys, which will give you the ability to manage or delete them.

  1. The Overview section will allow you to:
    • Edit your key name
    • Regenerate API keys
    • View the current usage of the API key with stats:
      • Number of queries
      • Amount of GRT spent
  2. Under Manage Security Settings, you’ll be able to opt into security settings depending on the level of control you’d like to have over your API keys. In this section, you can:
    • View and manage the domain names authorized to use your API key
    • You can assign subgraphs that can be queried with your API key

How to Manage your Subgraph#

API keys aside, you’ll have many tools at your disposal to manage your subgraphs. You can organize your subgraphs by their status and category.

  • The Status tag allows you to pick between a variety of tags including <created>, <deployed>, <published>, <archived>, etc.
  • Meanwhile, Category allows you to designate what category your subgraph falls into. Options include <DeFi>, <NFTs>, <Governance>, etc.