Como Fazer Queries de um Aplicativo

Reading time: 4 min

Quando um subgraph for lançado ao Subgraph Studio ou ao Graph Explorer, receberá o endpoint para a sua API GraphQL, que deve parecer com isto:

Subgraph Studio (endpoint de teste)

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>

O endpoint GraphQL permite usar várias bibliotecas do Cliente GraphQL, para consultar o subgraph e popular o seu aplicativo com os dados indexados pelo subgraph.

Aqui estão alguns dos clientes GraphQL mais populares no ecossistema, e como usá-los:

O The Graph fornece um cliente GraphQL próprio, graph-client, que apoia recursos únicos como:

• Gestão de Subgraph Cross-chain: Queries de múltiplos subgraphs numa única consulta
• Rastreamento Automático de Blocos
• Paginação Automática
• Resultado totalmente digitado

Também é integrado com clientes GraphQL populares como Apollo e URQL, e compatível com todos os ambientes, (React, Angular, Node.js, React Native); usar o graph-client proverá a melhor experiência para interagir com o The Graph.

Vamos ver como retirar dados de um subgraph com o graphql-client.

Para começar, instale a Graph Client CLI no seu projeto:

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

Defina o seu query num arquivo .graphql (ou alinhado no seu arquivo .js ou .ts):

query ExampleQuery {
  # este vem do compound-v2
  markets(first: 7) {
    borrowRate
    cash
    collateralFactor
  }
  # este vem do uniswap-v2
  pair(id: "0x00004ee988665cdda9a1080d5792cecd16dc1220") {
    id
    token0 {
      id
      symbol
      name
    }
    token1 {
      id
      symbol
      name
    }
  }
}

Depois, crie um arquivo de configuração (chamado .graphclientrc.yml) e aponte aos seus endpoints GraphQL oferecidos pelo The Graph, por exemplo:

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

Executar o seguinte comando na Graph Client CLI gerará códigos JavaScript digitados e prontos para uso:

graphclient build

Finalmente, atualize o seu arquivo .ts para usar os documentos digitados em GraphQL já gerados:

import React, { useEffect } from 'react'
// ...
// nós importamos tipos e documentos em graphql do código gerado
;`..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

⚠️ Aviso importante

O graph-client é perfeitamente integrado com outros clientes GraphQL como Apollo, URQL, ou React Query; veja exemplos no repositório oficial.

Porém, se escolher usar outro cliente, lembre que não haverá como usar a Gestão de Subgraph Cross-Chain ou a Paginação Automática, estes recursos importantes para queries no The Graph.

O cliente Apollo é o cliente GraphQL mais ubíquo no ecossistema do front-end.

Disponível para React, Angular, Vue, Ember, iOS e Android, o cliente Apollo, apesar de ser o mais pesado, traz muitos recursos para construir interfaces de utilizador avançadas em cima do GraphQL:

• tratamento de erros avançado
• paginação
• prefetching de dados
• UI otimista
• gestão de estado local

Vamos ver como retirar dados de um subgraph com o cliente Apollo num projeto de web.

Primeiro, instale o @apollo/client e o graphql:

npm install @apollo/client graphql

Depois, faça um query na API com o seguinte código:

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

Para usar variáveis, dá para passar um argumento variables ao 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)
  })

Há também o URQL, que está disponível nos ambientes Node.js, React/Preact, Vue e Svelte, com ferramentas mais avançadas:

• Sistema de cache flexível
• Design extensível (mais fácil adicionar novas capacidades em cima dele)
• Pacote leve (cerca de 5x mais leve que o Apollo)
• Apoio para envios de arquivo e modo offline

Vamos ver como retirar dados de um subgraph com o URQL num projeto de web.

Primeiro, instale o urql e o graphql:

npm install urql graphql

Depois, faça um query na API com o seguinte código:

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