How to query on-chain data with The Graph

A step-by-step guide on how to query on-chain data using the explorer and graphiql playground

5 min readSep 14, 2022


What is The Graph?

The Graph is a decentralized indexing protocol that enables efficient querying of on-chain data through open-source APIs called Subgraphs. It removes the need for developers to build out complex infrastructure to get data. The Graph currently supports Ethereum and Gnosis chains but is on the roadmap to adding a wide spectrum of blockchains to this list. The hosted service (centralized) however, supports over 30 networks. As of September 13th, 2022, there are 470 active subgraphs on the decentralized mainnet and several more migrating while the hosted service has over 28,000 subgraphs.

The Graph Explorer

The explorer is a graphical user interface (GUI) tool that provides a way to explore subgraphs and interact with the protocol. For this guide, we will stick to querying using the Sushiswap subgraph.

The Graph explorer
Source: The Graph

Getting Started

The explorer playground is easy to use and doesn’t require any download or installation.

Select the subgraph you want to interact with and navigate to the playground.

Sushi Subgraph playground

The left side is where you write your queries (in graphql), while the right side displays the different schema entities of the subgraph (you can toggle between them to see what you would like to request), and the middle layer is where you can view the results of your query.

By default, query responses are limited to 1000 items per collection (but you can traverse up to 10,000 entries). You can customize it using the “first” parameter, which gives back the first entries ordered by “ID”. You can further define it using additional parameters like “skip” — which paginates by skipping the number of entries defined or “where” — this filters the entries by what is defined.

users(first: 20 skip: 10 where:{id:""}) {
liquidityPositions {
bundles(first: 5) {

You can also sort your queries using parameters like “orderBy” and “orderDirection”

tokens(first: 20 orderBy: volumeUSD orderDirection: asc) {


The Graphiql Explorer

The graphiql explorer is an easy-to-use GUI tool for building out queries for your subgraph. You'll need an endpoint URL and an API key to interact with this tool. API keys are required to query data from subgraphs. You can create/manage API keys in Subgraph Studio. You can also receive 1,000 free queries after creating your first API key. Your API keys should be private and accessible only to you, do NOT share your API keys.

Getting Started

The process for using the graphiql playground differs from using the explorer playground, but this guide will cover all the steps required to use it.

Step 1: Navigate to the Subgraph Studio

The Subgraph studio is a staging area where you can create, manage and publish subgraphs and API keys on the mainnet.

Navigating to the subgraph studio

Step 2: Connect your wallet and create your API key

Once you get to the studio, you’ll need to connect your wallet (Metamask or other) to interact with the studio. After that, you should select API keys and create your first API key.

Connect wallet and create API key

Once your API key is created, you should copy it and navigate back to the explorer playground and grab the query URL of the subgraph you intend to use.

Copy your API key

The query URL and API key will form your unique endpoint URL which is required to query your subgraph on the graphiql playground or when you want to query the subgraph from an application.

Step 3: Enter the graphiql explorer

Now that we have the API key and query URL the next step would be to head over to the graphiql explorer. Here, you would paste the query URL and enter the API key in the designated position.

Step 4: Form custom queries

Once you enter the playground, you can build out custom queries based on the data you want to request.

On the left of the graphiql playground, you can interact with the schema by selecting the entities you want to query, while the center shows your query building out as you select the entities, and the right displays your query results.

There is a difference however with writing your queries in the graphiql playground. It uses a dropdown style with checkboxes to select what you want to query. This is very useful to people unfamiliar with the Graphql query language, so I suggest using this GUI to help write your queries.

You would also notice that all entities in the schema have pairs (singular and plural). If you select the singular, you would need to provide the “ID” of the exact entry you are querying for, but if you want to request multiple entries, you should select the plural.

What’s Next?

If you’re interested in using the explorer or playground, feel free to use this guide. You can also find me on Twitter at @chidubem_w3

Helpful Resources




Building the decentralized web by creating high-quality content that helps participants navigate the Web3 ecosystem.