Querying

Querying from an Application

Once a subgraph is deployed to the Subgraph Studio or to The Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this:

Subgraph Studio (testing endpoint)

Queries (HTTP)
https://api.studio.thegraph.com/query/<ID>/<SUBGRAPH_NAME>/<VERSION>

Graph Explorer

Queries (HTTP)
https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>

Using the GraphQL endpoint, you can use various GraphQL Client libraries to query the subgraph and populate your app with the data indexed by the subgraph.

Here are a couple of the more popular GraphQL clients in the ecosystem and how to use them:

GraphQL clientsLink to this section

Graph clientLink to this section

The Graph is providing it own GraphQL client, graph-client that supports unique features such as:


Also integrated with popular GraphQL clients such as Apollo and URQL and compatible with all environments (React, Angular, Node.js, React Native), using graph-client will give you the best experience for interacting with The Graph.


Let's look at how to fetch data from a subgraph with graphql-client.

To get started, make sure to install The Graph Client CLI in your project:

yarn add -D @graphprotocol/client-cli
# or, with NPM:
npm install --save-dev @graphprotocol/client-cli

Define you query in a .graphql file (or inlined in your .js or .ts file):

query ExampleQuery {
# this one is coming from compound-v2
markets(first: 7) {
borrowRate
cash
collateralFactor
}
# this one is coming from uniswap-v2
pair(id: "0x00004ee988665cdda9a1080d5792cecd16dc1220") {
id
token0 {
id
symbol
name
}
token1 {
id
symbol
name
}
}
}

Then, create a configuration file (called .graphclientrc.yml) and point to your GraphQL endpoints provided by The Graph, for example:

# .graphclientrc.yml
sources:
- name: uniswapv2
handler:
graphql:
endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2
- name: compoundv2
handler:
graphql:
endpoint: https://api.thegraph.com/subgraphs/name/graphprotocol/compound-v2
documents:
- ./src/example-query.graphql

Running the following The Graph Client CLI command will generate typed and ready to use JavaScript code:

graphclient build

Finally, update your .ts file to use the generated typed GraphQL documents:

import React, { useEffect } from 'react'
// ...
// we import types and typed-graphql document from the generated code (`..graphclient/`)
import { ExampleQueryDocument, ExampleQueryQuery, execute } from '../.graphclient'
function App() {
const [result, setResult] = React.useState<ExampleQueryQuery>()
useEffect(() => {
execute(ExampleQueryDocument, {}).then((result) => {
setData(result?.data)
})
}, [setResult])
return (
<div className="App">
<header className="App-header">
<img src={logo} className="App-logo" alt="logo" />
<p>Graph Client Example</p>
<fieldset>
{data && (
<form>
<label>Data</label>
<br />
<textarea value={JSON.stringify(data, null, 2)} readOnly rows={25} />
</form>
)}
</fieldset>
</header>
</div>
)
}
export default App

⚠️ Important notice

graph-client is perfectly integrated with other GraphQL clients such as Apollo client, URQL, or React Query; you will find examples in the official repository.

However, if you choose to go with another client, keep in mind that you won't be able to get to use Cross-chain Subgraph Handling or Automatic Pagination, which are core features for querying The Graph.


Apollo clientLink to this section

Apollo client is the ubiquitous GraphQL client on the front-end ecosystem.

Available for React, Angular, Vue, Ember, iOS, and Android, Apollo Client, although the heaviest client, brings many features to build advanced UI on top of GraphQL:

  • advanced error handling
  • pagination
  • data prefetching
  • optimistic UI
  • local state management

Let's look at how to fetch data from a subgraph with Apollo client in a web project.

First, install @apollo/client and graphql:

npm install @apollo/client graphql

Then you can query the API with the following code:

import { ApolloClient, InMemoryCache, gql } from '@apollo/client'
const APIURL = 'https://api.studio.thegraph.com/query//<SUBGRAPH_NAME>/'
const tokensQuery = `
query {
tokens {
id
tokenID
contentURI
metadataURI
}
}
`
const client = new ApolloClient({
uri: APIURL,
cache: new InMemoryCache(),
})
client
.query({
query: gql(tokensQuery),
})
.then((data) => console.log('Subgraph data: ', data))
.catch((err) => {
console.log('Error fetching data: ', err)
})

To use variables, you can pass in a variables argument to the query:

const tokensQuery = `
query($first: Int, $orderBy: BigInt, $orderDirection: String) {
tokens(
first: $first, orderBy: $orderBy, orderDirection: $orderDirection
) {
id
tokenID
contentURI
metadataURI
}
}
`
client
.query({
query: gql(tokensQuery),
variables: {
first: 10,
orderBy: 'createdAtTimestamp',
orderDirection: 'desc',
},
})
.then((data) => console.log('Subgraph data: ', data))
.catch((err) => {
console.log('Error fetching data: ', err)
})

URQLLink to this section

Another option is URQL which is available within Node.js, React/Preact, Vue, and Svelte environments, with more advanced features:

  • Flexible cache system
  • Extensible design (easing adding new capabilities on top of it)
  • Lightweight bundle (~5x lighter than Apollo Client)
  • Support for file uploads and offline mode

Let's look at how to fetch data from a subgraph with URQL in a web project.

First, install urql and graphql:

npm install urql graphql

Then you can query the API with the following code:

import { createClient } from 'urql'
const APIURL = 'https://api.thegraph.com/subgraphs/name/username/subgraphname'
const tokensQuery = `
query {
tokens {
id
tokenID
contentURI
metadataURI
}
}
`
const client = createClient({
url: APIURL,
})
const data = await client.query(tokensQuery).toPromise()
Edit page

Previous
Querying Best Practices
Next
Distributed Systems