アプリケーションからのクエリ
Reading time: 5 minutes
Learn how to query The Graph from your application.
Getting GraphQL Endpoints
During the development process, you will receive a GraphQL API endpoint at two different stages: one for testing in Subgraph Studio, and another for making queries to The Graph Network in production.
Subgraph Studio Endpoint
After deploying your subgraph to Subgraph Studio, you will receive an endpoint that looks like this:
https://api.studio.thegraph.com/query/<ID>/<SUBGRAPH_NAME>/<VERSION>
This endpoint is intended for testing purposes only and is rate-limited.
The Graph Network Endpoint
After publishing your subgraph to the network, you will receive an endpoint that looks like this: :
https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>
This endpoint is intended for active use on the network. It allows you to use various GraphQL client libraries to query the subgraph and populate your application with indexed data.
Using Popular GraphQL Clients
Graph Client
The Graph is providing its own GraphQL client, graph-client
that supports unique features such as:
- クロスチェーンのサブグラフ処理:1回のクエリで複数のサブグラフからクエリを実行可能
- Automatic Block Tracking
- Automatic Pagination
- 完全なタイプ付け結果
Note: graph-client
is integrated with other popular GraphQL clients such as Apollo and URQL, which are compatible with environments such as React, Angular, Node.js, and React Native. As a result, using graph-client
will provide you with an enhanced experience for working with The Graph.
Fetch Data with Graph Client
Let’s look at how to fetch data from a subgraph with graph-client
:
ステップ1
Install The Graph Client CLI in your project:
yarn add -D @graphprotocol/client-cli# or, with NPM:npm install --save-dev @graphprotocol/client-cli
ステップ2
Define your 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 } }}
ステップ 3
Create a configuration file (called .graphclientrc.yml
) and point to your GraphQL endpoints provided by The Graph, for example:
# .graphclientrc.ymlsources: - name: uniswapv2 handler: graphql: endpoint: https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID> - name: compoundv2 handler: graphql: endpoint: https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>documents: - ./src/example-query.graphql
Step 4
Run the following The Graph Client CLI command to generate typed and ready to use JavaScript code:
graphclient build
Step 5
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 [data, setData] = React.useState<ExampleQueryQuery>() useEffect(() => { execute(ExampleQueryDocument, {}).then((result) => { setData(result?.data) }) }, [setData]) 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 Note: graph-client
is perfectly integrated with other GraphQL clients such as Apollo client, URQL, or React Query; you can 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 use Cross-chain Subgraph Handling or Automatic Pagination, which are core features for querying The Graph.
Apollo Client
Apollo client is a common GraphQL client on front-end ecosystems. It’s available for React, Angular, Vue, Ember, iOS, and Android.
Although it’s the heaviest client, it has many features to build advanced UI on top of GraphQL:
- Advanced error handling
- ページネーション
- Data prefetching
- Optimistic UI
- Local state management
Fetch Data with Apollo Client
Let’s look at how to fetch data from a subgraph with Apollo client:
ステップ1
Install @apollo/client
and graphql
:
npm install @apollo/client graphql
ステップ2
Query the API with the following code:
import { ApolloClient, InMemoryCache, gql } from '@apollo/client'const APIURL = 'https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>'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) })
ステップ 3
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) })
URQL Overview
URQL is available within Node.js, React/Preact, Vue, and Svelte environments, with some more advanced features:
- 柔軟なキャッシュ システム
- Extensible design(新しい機能の追加を容易にする)
- Lightweight bundle(Apollo Clientの約5倍の軽さ)
- ファイルアップロードとオフラインモードに対応
Fetch data with URQL
Let’s look at how to fetch data from a subgraph with URQL:
ステップ1
Install urql
and graphql
:
npm install urql graphql
ステップ2
Query the API with the following code:
import { createClient } from 'urql'const APIURL = 'https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>'const tokensQuery = ` query { tokens { id tokenID contentURI metadataURI } }`const client = createClient({ url: APIURL,})const data = await client.query(tokensQuery).toPromise()