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
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.
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.
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:""}) {
id
liquidityPositions {
id
}
}
bundles(first: 5) {
id
ethPrice
}
}You can also sort your queries using parameters like “orderBy” and “orderDirection”
{
tokens(first: 20 orderBy: volumeUSD orderDirection: asc) {
id
totalSupply
liquidity
factory{
pairCount
userCount
tokenCount
}
}
}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.
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.
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.
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
- Explorer page
- Querying from an application with Graph Client
- Querying from a front-end web app using the Apollo Client and URQL
- Billing and API keys
- Managing your API keys
