Eseguire una query da un'applicazione

Reading time: 4 min

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

Subgraph Studio (endpoint di test)

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>

Utilizzando il GraphQL endpoint, si possono usare varie librerie GraphQL Client per interrogare il subgraph e popolare l'applicazione con i dati indicizzati dal subgraph.

Ecco un paio dei GraphQL client più diffusi nell'ecosistema e come utilizzarli:

The Graph fornisce il proprio client GraphQL, graph-client, che supporta caratteristiche uniche come:

• Gestione dei subgraph a cross-chain: effettuare query di più subgraph in un'unica query
• Tracciamento automatico dei blocchi
• Paginazione automatica
• Risultato completamente tipizzato

Integrato anche con i client GraphQL più diffusi, come Apollo e URQL, e compatibile con tutti gli ambienti (React, Angular, Node.js, React Native), l'uso di graph-client vi darà la migliore esperienza di interazione con The Graph.

Vediamo come recuperare i dati da un subgraph con graphql-client.

Per iniziare, assicuratevi di installare il Graph Client CLI nel vostro progetto:

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

Definire la query in un file .graphql (o in un file .js o .ts):

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
    }
  }
}

Quindi, creare un file di configurazione (chiamato .graphclientrc.yml) e puntare agli endpoint GraphQL forniti da The Graph, ad esempio:

# .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

L'esecuzione del seguente comando The Graph Client CLI genererà codice JavaScript digitato e pronto all'uso:

graphclient build

Infine, aggiornare il file .ts per utilizzare i documenti GraphQL digitati generati:

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

⚠️ Avviso importante

graph-client è perfettamente integrato con altri client GraphQL come Apollo client, URQL o React Query; troverete degli esempi nel repository ufficiale.

Tuttavia, se scegliete un altro client, tenete presente che non sarete in grado di utilizzare la gestione dei Subgraph Cross-chain o la Paginazione Automatica, che sono caratteristiche fondamentali per effettuare query di The Graph.

Client Apollo è il client GraphQL onnipresente nell'ecosistema front-end.

Disponibile per React, Angular, Vue, Ember, iOS e Android, Apollo Client, sebbene sia il client più pesante, offre molte funzionalità per costruire UI avanzate in cima a GraphQL:

• gestione avanzata degli errori
• paginazione
• prefetching dei dati
• UI ottimistica
• gestione statale locale

Vediamo come recuperare i dati da un subgraph con il Apollo client in un progetto web.

Per prima cosa, installare @apollo/client e graphql:

npm install @apollo/client graphql

Quindi è possibile effettuare query del'API con il seguente codice:

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)
  })

Per usare le variabili, si può passare un argomento variables alla 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)
  })

Un'altra opzione è URQL, disponibile negli ambienti Node.js, React/Preact, Vue e Svelte, con caratteristiche più avanzate:

• Sistema di cache flessibile
• Design estensibile (facilita l'aggiunta di nuove funzionalità)
• Bundle leggero (~5 volte più leggero del Apollo Сlient)
• Supporto per il caricamento di file e la modalità offline

Vediamo come recuperare i dati da un subgraph con il URQL in un progetto web.

Per prima cosa, installare urql e graphql:

npm install urql graphql

Quindi è possibile effettuare query del'API con il seguente codice:

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()