From 9ae86ffa23ed1b23203e6a0d6695f5758d2b2df6 Mon Sep 17 00:00:00 2001 From: Idalith Bustos Date: Mon, 28 Oct 2024 17:52:02 -0700 Subject: [PATCH 1/4] updating --- website/next-env.d.ts | 2 +- .../querying/querying-from-an-application.mdx | 84 ++++++++++++------- 2 files changed, 57 insertions(+), 29 deletions(-) diff --git a/website/next-env.d.ts b/website/next-env.d.ts index a4a7b3f5cfa2..4f11a03dc6cc 100644 --- a/website/next-env.d.ts +++ b/website/next-env.d.ts @@ -2,4 +2,4 @@ /// // NOTE: This file should not be edited -// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information. +// see https://nextjs.org/docs/basic-features/typescript for more information. diff --git a/website/pages/en/querying/querying-from-an-application.mdx b/website/pages/en/querying/querying-from-an-application.mdx index 84c489360087..342489e9d70d 100644 --- a/website/pages/en/querying/querying-from-an-application.mdx +++ b/website/pages/en/querying/querying-from-an-application.mdx @@ -2,42 +2,52 @@ 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 + +Once a subgraph is deployed to [Subgraph Studio](https://thegraph.com/studio/) or to [Graph Explorer](https://thegraph.com/explorer), you will be given the endpoint for your GraphQL API. + +### Subgraph Studio + +Your GraphQL API In Studio should look something like this: ```sh Queries (HTTP) https://api.studio.thegraph.com/query/// ``` -**Graph Explorer** +### Graph Explorer + +Your GraphQL API In Studio should look something like this: ```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 Overview -### Graph client +The Graph is provides its own `graph-client` which supports unique features such as: -The Graph is providing it own GraphQL client, `graph-client` that supports unique features such as: +- **Cross-chain Subgraph Handling**: Querying from multiple subgraphs in a single query +- **[Automatic Block Tracking](https://github.com/graphprotocol/graph-client/blob/main/packages/block-tracking/README.md)** +- **[Automatic Pagination](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md)** +- **Fully Typed Result** -- Cross-chain Subgraph Handling: Querying from multiple subgraphs in a single query -- [Automatic Block Tracking](https://github.com/graphprotocol/graph-client/blob/main/packages/block-tracking/README.md) -- [Automatic Pagination](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md) -- Fully typed result +Popular Graph QL clients such as Apollo and URQL are compatible with environments such as React, Angular, Node.js, and React Native. As a result, using `graph-client` will provide an optimal experience for working with The Graph. -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. +### Fetch Data with Graph Client 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: +#### Step 1 + +Install The Graph Client CLI in your project: ```sh yarn add -D @graphprotocol/client-cli @@ -45,6 +55,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 +84,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 +104,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,13 +152,9 @@ 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 will [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). - -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 +### Apollo Client Overview [Apollo client](https://www.apollographql.com/docs/) is the ubiquitous GraphQL client on the front-end ecosystem. @@ -152,15 +166,21 @@ Available for React, Angular, Vue, Ember, iOS, and Android, Apollo Client, altho - optimistic UI - local state management +### Fetch Data with Apollo Client + Let's look at how to fetch data from a subgraph with Apollo client in a web project. -First, install `@apollo/client` and `graphql`: +#### Step 1 + +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 +213,8 @@ client }) ``` +#### Step 3 + To use variables, you can pass in a `variables` argument to the query: ```javascript @@ -224,7 +246,7 @@ 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: @@ -233,15 +255,21 @@ Another option is [URQL](https://formidable.com/open-source/urql/) which is avai - Lightweight bundle (~5x lighter than Apollo Client) - Support for file uploads and offline mode +### Fetch data with URQL + Let's look at how to fetch data from a subgraph with URQL in a web project. -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' From 8e09c48de9181f6eeb8e81b29cf97addb4829a2a Mon Sep 17 00:00:00 2001 From: Idalith Bustos Date: Tue, 29 Oct 2024 13:23:48 -0700 Subject: [PATCH 2/4] additional edits --- .../querying/querying-from-an-application.mdx | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/website/pages/en/querying/querying-from-an-application.mdx b/website/pages/en/querying/querying-from-an-application.mdx index 342489e9d70d..c1cc34796b79 100644 --- a/website/pages/en/querying/querying-from-an-application.mdx +++ b/website/pages/en/querying/querying-from-an-application.mdx @@ -6,11 +6,11 @@ Learn how to query The Graph from your application. ## Getting GraphQL Endpoint -Once a subgraph is deployed to [Subgraph Studio](https://thegraph.com/studio/) or to [Graph Explorer](https://thegraph.com/explorer), you will be given the endpoint for your GraphQL API. +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. ### Subgraph Studio -Your GraphQL API In Studio should look something like this: +Your GraphQL API in Studio should look something like this: ```sh Queries (HTTP) @@ -19,7 +19,7 @@ https://api.studio.thegraph.com/query/// ### Graph Explorer -Your GraphQL API In Studio should look something like this: +Your GraphQL API in Studio should look something like this: ```sh Queries (HTTP) @@ -30,20 +30,20 @@ With your GraphQL endpoint, you can use various GraphQL Client libraries to quer ## Using Popular GraphQL Clients -### Graph Client Overview +### Graph Client -The Graph is provides its own `graph-client` which supports unique features such as: +The Graph provides its own `graph-client` which supports optimimal features such as: -- **Cross-chain Subgraph Handling**: Querying from multiple subgraphs in a single query -- **[Automatic Block Tracking](https://github.com/graphprotocol/graph-client/blob/main/packages/block-tracking/README.md)** -- **[Automatic Pagination](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md)** -- **Fully Typed Result** +- Cross-chain Subgraph Handling: Querying from multiple subgraphs in a single query +- [Automatic Block Tracking](https://github.com/graphprotocol/graph-client/blob/main/packages/block-tracking/README.md) +- [Automatic Pagination](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md) +- Fully typed result -Popular Graph QL clients such as Apollo and URQL are compatible with environments such as React, Angular, Node.js, and React Native. As a result, using `graph-client` will provide an optimal experience for working with The Graph. +> Note: `graph-client` is integrated with other popular Graph QL 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 `graphql-client`: #### Step 1 @@ -152,23 +152,23 @@ function App() { export default App ``` -> Important Note: `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). 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**. +> **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**. -### Apollo Client Overview +### Apollo Client -[Apollo client](https://www.apollographql.com/docs/) is the ubiquitous GraphQL client on the front-end ecosystem. +[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. -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: +Although it's the heaviest client, it has many features to build advanced UI on top of GraphQL: -- advanced error handling -- pagination -- data prefetching -- optimistic UI -- local state management +- Advanced error handling +- Pagination +- 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 in a web project. +Let's look at how to fetch data from a subgraph with Apollo client: #### Step 1 @@ -248,7 +248,7 @@ client ### 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) @@ -257,7 +257,7 @@ Another option is [URQL](https://formidable.com/open-source/urql/) which is avai ### Fetch data with URQL -Let's look at how to fetch data from a subgraph with URQL in a web project. +Let's look at how to fetch data from a subgraph with URQL: #### Step 1 From f6ac9a3c30001f1d1a9165ec05443438b66eca66 Mon Sep 17 00:00:00 2001 From: Idalith Bustos Date: Wed, 30 Oct 2024 16:22:12 -0700 Subject: [PATCH 3/4] updates --- website/next-env.d.ts | 2 +- .../en/querying/querying-from-an-application.mdx | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/website/next-env.d.ts b/website/next-env.d.ts index 4f11a03dc6cc..a4a7b3f5cfa2 100644 --- a/website/next-env.d.ts +++ b/website/next-env.d.ts @@ -2,4 +2,4 @@ /// // NOTE: This file should not be edited -// see https://nextjs.org/docs/basic-features/typescript for more information. +// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information. diff --git a/website/pages/en/querying/querying-from-an-application.mdx b/website/pages/en/querying/querying-from-an-application.mdx index c1cc34796b79..a41493abcad8 100644 --- a/website/pages/en/querying/querying-from-an-application.mdx +++ b/website/pages/en/querying/querying-from-an-application.mdx @@ -12,17 +12,17 @@ Once a subgraph is deployed to [Subgraph Studio](https://thegraph.com/studio/) o Your GraphQL API in Studio should look something like this: -```sh -Queries (HTTP) +``` https://api.studio.thegraph.com/query/// ``` +> Note: Remember that Subgraph Studio is a testing playground for subgraphs. + ### Graph Explorer -Your GraphQL API in Studio should look something like this: +Your GraphQL API in Explorer should look something like this: -```sh -Queries (HTTP) +``` https://gateway.thegraph.com/api//subgraphs/id/ ``` @@ -39,11 +39,11 @@ The Graph provides its own `graph-client` which supports optimimal features such - [Automatic Pagination](https://github.com/graphprotocol/graph-client/blob/main/packages/auto-pagination/README.md) - Fully typed result -> Note: `graph-client` is integrated with other popular Graph QL 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. +> 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`: #### Step 1 From dd19b64053723b414c8b4895c9b362da106cc490 Mon Sep 17 00:00:00 2001 From: Idalith Bustos Date: Fri, 1 Nov 2024 13:51:57 -0700 Subject: [PATCH 4/4] edits --- .../pages/en/querying/querying-from-an-application.mdx | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/website/pages/en/querying/querying-from-an-application.mdx b/website/pages/en/querying/querying-from-an-application.mdx index a41493abcad8..0692733cef89 100644 --- a/website/pages/en/querying/querying-from-an-application.mdx +++ b/website/pages/en/querying/querying-from-an-application.mdx @@ -6,22 +6,16 @@ Learn how to query The Graph from your application. ## Getting GraphQL Endpoint -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. +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 -Your GraphQL API in Studio should look something like this: - ``` https://api.studio.thegraph.com/query/// ``` -> Note: Remember that Subgraph Studio is a testing playground for subgraphs. - ### Graph Explorer -Your GraphQL API in Explorer should look something like this: - ``` https://gateway.thegraph.com/api//subgraphs/id/ ```