diff --git a/website/pages/en/querying/querying-from-an-application.mdx b/website/pages/en/querying/querying-from-an-application.mdx index c9000cf2e5d8..82d0661b73cd 100644 --- a/website/pages/en/querying/querying-from-an-application.mdx +++ b/website/pages/en/querying/querying-from-an-application.mdx @@ -2,29 +2,30 @@ title: Querying from an Application --- -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: +Learn how to query The Graph from your application. -**Subgraph Studio (testing endpoint)** +## Getting GraphQL Endpoint -```sh -Queries (HTTP) +Once a subgraph is deployed to [Subgraph Studio](https://thegraph.com/studio/) or [Graph Explorer](https://thegraph.com/explorer), you will be given the endpoint for your GraphQL API that should look something like this: + +### Subgraph Studio + +``` https://api.studio.thegraph.com/query/// ``` -**Graph Explorer** +### Graph Explorer -```sh -Queries (HTTP) +``` https://gateway.thegraph.com/api//subgraphs/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. +With your GraphQL endpoint, you can use various GraphQL Client libraries to query the subgraph and populate your app with data indexed by the subgraph. -Here are a couple of the more popular GraphQL clients in the ecosystem and how to use them: +## Using Popular GraphQL Clients -## GraphQL clients +### Graph Client -### Graph client The Graph is providing its own GraphQL client, `graph-client` that supports unique features such as: @@ -33,11 +34,15 @@ The Graph is providing its own GraphQL client, `graph-client` that supports uniq - [Automatic Pagination](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md) - Fully typed result -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. +> 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 `graphql-client`. +Let's look at how to fetch data from a subgraph with `graph-client`: -To get started, make sure to install The Graph Client CLI in your project: +#### Step 1 + +Install The Graph Client CLI in your project: ```sh yarn add -D @graphprotocol/client-cli @@ -45,6 +50,8 @@ yarn add -D @graphprotocol/client-cli npm install --save-dev @graphprotocol/client-cli ``` +#### Step 2 + Define your query in a `.graphql` file (or inlined in your `.js` or `.ts` file): ```graphql @@ -72,7 +79,9 @@ query ExampleQuery { } ``` -Then, create a configuration file (called `.graphclientrc.yml`) and point to your GraphQL endpoints provided by The Graph, for example: +#### Step 3 + +Create a configuration file (called `.graphclientrc.yml`) and point to your GraphQL endpoints provided by The Graph, for example: ```yaml # .graphclientrc.yml @@ -90,13 +99,17 @@ documents: - ./src/example-query.graphql ``` -Running the following The Graph Client CLI command will generate typed and ready to use JavaScript code: +#### Step 4 + +Run the following The Graph Client CLI command to generate typed and ready to use JavaScript code: ```sh graphclient build ``` -Finally, update your `.ts` file to use the generated typed GraphQL documents: +#### Step 5 + +Update your `.ts` file to use the generated typed GraphQL documents: ```tsx import React, { useEffect } from 'react' @@ -134,33 +147,35 @@ function App() { export default App ``` -**⚠️ Important notice** +> **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](https://github.com/graphprotocol/graph-client/tree/main/examples). 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**. -`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](https://github.com/graphprotocol/graph-client/tree/main/examples). +### Apollo Client -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 client](https://www.apollographql.com/docs/) is a common GraphQL client on front-end ecosystems. It's available for React, Angular, Vue, Ember, iOS, and Android. -### Apollo client +Although it's the heaviest client, it has many features to build advanced UI on top of GraphQL: -[Apollo client](https://www.apollographql.com/docs/) is the ubiquitous GraphQL client on the front-end ecosystem. +- Advanced error handling +- Pagination +- Data prefetching +- Optimistic UI +- Local state management -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: +### Fetch Data with Apollo Client -- 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: -Let's look at how to fetch data from a subgraph with Apollo client in a web project. +#### Step 1 -First, install `@apollo/client` and `graphql`: +Install `@apollo/client` and `graphql`: ```sh npm install @apollo/client graphql ``` -Then you can query the API with the following code: +#### Step 2 + +Query the API with the following code: ```javascript import { ApolloClient, InMemoryCache, gql } from '@apollo/client' @@ -193,6 +208,8 @@ client }) ``` +#### Step 3 + To use variables, you can pass in a `variables` argument to the query: ```javascript @@ -224,24 +241,30 @@ client }) ``` -### URQL +### URQL Overview -Another option is [URQL](https://formidable.com/open-source/urql/) which is available within Node.js, React/Preact, Vue, and Svelte environments, with more advanced features: +[URQL](https://formidable.com/open-source/urql/) is available within Node.js, React/Preact, Vue, and Svelte environments, with some 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. +### Fetch data with URQL + +Let's look at how to fetch data from a subgraph with URQL: -First, install `urql` and `graphql`: +#### Step 1 + +Install `urql` and `graphql`: ```sh npm install urql graphql ``` -Then you can query the API with the following code: +#### Step 2 + +Query the API with the following code: ```javascript import { createClient } from 'urql'