Skip to content

Commit 98a0bbf

Browse files
alinobrasilalinobrasil
committed
added section for the graph: quick start full guide
1 parent d4da0f3 commit 98a0bbf

File tree

2 files changed

+197
-0
lines changed

2 files changed

+197
-0
lines changed

‎docs/tools/data/thegraph.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
2+
!!! note "Content disclaimer"
3+
4+
Please view the third-party content disclaimer [here](https://github.com/0xPolygon/polygon-docs/blob/main/CONTENT_DISCLAIMER.md).
5+
6+
# The Graph
7+
8+
Getting historical data on a smart contract can be frustrating when building a dapp. [The Graph](https://thegraph.com/) provides an easy way to query smart contract data through APIs known as subgraphs. The Graph’s infrastructure relies on a decentralized network of indexers, enabling your dapp to become truly decentralized.
9+
10+
## Quick Start
11+
12+
These subgraphs only take a few minutes to set up. To get started, follow these three steps:
13+
14+
1. Initialize your subgraph project
15+
2. Deploy & Publish
16+
3. Query from your dapp
17+
18+
Here’s a step by step walk through:
19+
20+
## 1. Initialize your subgraph project
21+
22+
### Create a subgraph on Subgraph Studio⁠
23+
24+
Go to the [Subgraph Studio](https://thegraph.com/studio/) and connect your wallet. Once your wallet is connected, you can begin by clicking “Create a Subgraph”. When choosing a name, it is recommended to use Title Case: “Subgraph Name Chain Name.”
25+
26+
![Create a Subgraph](https://lh7-us.googleusercontent.com/docsz/AD_4nXf8OTdwMxlKQGKzIF_kYR7NPKeh9TmWnZBYxb7ft_YbdOdx_VVtbp6PslN7N1KGUzNpIDCmaXppdrllM1cw_J4L8Na03BXOWzJTK1POCve0nkRjQYgWJ60QHAdtQ4Niy83SMM8m0F0f-N-AJj4PDqDPlA5M?key=fnI6SyFgXU9SZRNX5C5vPQ)
27+
28+
29+
You will then land on your subgraph’s page. All the CLI commands you need will be visible on the right side of the page:
30+
31+
![CLI commands](https://lh7-us.googleusercontent.com/docsz/AD_4nXe3YvCxiOH_LupSWe8zh9AmP-VrV4PlOq3f7Ix6hNlBUYcANUFuLuVIWR74OGiBs0nrugTyT0v3o6RPmTsgHONdv_ZJNWtcDWEkRntXPHlQGFcqmEBa-D6j4aoIPzUKYdOJMVUPu8O3fwjdZ4IaXXZoTzY?key=fnI6SyFgXU9SZRNX5C5vPQ)
32+
33+
34+
### Install the Graph CLI⁠
35+
36+
On your local machine run the following:
37+
```
38+
npm install -g @graphprotocol/graph-cli
39+
```
40+
41+
### Initialize your Subgraph⁠
42+
43+
You can copy this directly from your subgraph page to include your specific subgraph slug:
44+
```
45+
graph init --studio <SUBGRAPH_SLUG>
46+
```
47+
You’ll be prompted to provide some info on your subgraph like this:
48+
49+
![cli sample](https://lh7-us.googleusercontent.com/docsz/AD_4nXdTAUsUb5vbs3GtCrhKhuXM1xYoqqooYTxw6lfJfYtLJNP8GKVOhTPmjxlM1b6Qpx-pXNVOzRuc8BL12wZXqy4MIj8ja0tp15znfuJD_Mg84SSNj3JpQ4d31lNTxPYnpba4UOzZx8pmgOIsbI7vCz70v9gC?key=fnI6SyFgXU9SZRNX5C5vPQ)
50+
51+
52+
Simply have your contract verified on the block explorer and the CLI will automatically obtain the ABI and set up your subgraph. The default settings will generate an entity for each event.
53+
54+
## 2. Deploy & Publish
55+
56+
### Deploy to Subgraph Studio⁠
57+
58+
First run these commands:
59+
60+
```bash
61+
$ graph codegen
62+
$ graph build
63+
```
64+
65+
Then run these to authenticate and deploy your subgraph. You can copy these commands directly from your subgraph’s page in Studio to include your specific deploy key and subgraph slug:
66+
67+
```bash
68+
$ graph auth --studio <DEPLOY_KEY>
69+
$ graph deploy --studio <SUBGRAPH_SLUG>
70+
```
71+
72+
You will be asked for a version label. You can enter something like v0.0.1, but you’re free to choose the format.
73+
74+
### Test your subgraph⁠
75+
76+
You can test your subgraph by making a sample query in the playground section. The Details tab will show you an API endpoint. You can use that endpoint to test from your dapp.
77+
78+
![Playground](https://lh7-us.googleusercontent.com/docsz/AD_4nXf3afwSins8_eO7BceGPN79VvwolDxmFNUnkPk0zAJCaUA-3-UAAjVvrMzwr7q9vNYWdrEUNgm2De2VfQpWauiT87RkFc-cVfoPSsQbYSgsmwhyY1-tpPdv2J1H4JAMq70nfWBhb8PszZBFjsbDAaJ5eto?key=fnI6SyFgXU9SZRNX5C5vPQ)
79+
80+
81+
### Publish Your Subgraph to The Graph’s Decentralized Network
82+
83+
Once your subgraph is ready to be put into production, you can publish it to the decentralized network. On your subgraph’s page in Subgraph Studio, click on the Publish button:
84+
85+
![publish button](https://edgeandnode.notion.site/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Fa7d6afae-8784-4b15-a90e-ee8f6ee007ba%2F2f9c4526-123d-4164-8ea8-39959c8babbf%2FUntitled.png?table=block&id=37005371-76b4-4780-b044-040a570e3af6&spaceId=a7d6afae-8784-4b15-a90e-ee8f6ee007ba&width=1420&userId=&cache=v2)
86+
87+
88+
Before you can query your subgraph, Indexers need to begin serving queries on it. In order to streamline this process, you can curate your own subgraph using GRT.
89+
90+
When publishing, you’ll see the option to curate your subgraph. As of May 2024, it is recommended that you curate your own subgraph with at least 3,000 GRT to ensure that it is indexed and available for querying as soon as possible.
91+
92+
![Publish screen](https://lh7-us.googleusercontent.com/docsz/AD_4nXerUr-IgWjwBZvp9Idvz5hTq8AFB0n_VlXCzyDtUxKaCTANT4gkk-2O77oW-a0ZWOh3hnqQsY7zcSaLeCQin9XU1NTX1RVYOLFX9MuVxBEqcMryqgnGQKx-MbDnOWKuMoLBhgyVWQereg3cdWtCPcTQKFU?key=fnI6SyFgXU9SZRNX5C5vPQ)
93+
94+
> **Note:** The Graph's smart contracts are all on Arbitrum One, even though your subgraph is indexing data from Ethereum, BSC or any other [supported chain](https://thegraph.com/docs/en/developing/supported-networks/).
95+
96+
## 3. Query your Subgraph
97+
98+
Congratulations! You can now query your subgraph on the decentralized network!
99+
100+
For any subgraph on the decentralized network, you can start querying it by passing a GraphQL query into the subgraph’s query URL which can be found at the top of its Explorer page.
101+
102+
Here’s an example from the [CryptoPunks Ethereum subgraph](https://thegraph.com/explorer/subgraphs/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK) by Messari:
103+
104+
![Query URL](https://lh7-us.googleusercontent.com/docsz/AD_4nXebivsPOUjPHAa3UVtvxoYTFXaGBao9pQOAJvFK0S7Uv0scfL6TcTVjmNCzT4DgsIloAQyrPTCqHjFPtmjyrzoKkfSeV28FjS32F9-aJJm0ILAHey2gqMr7Seu4IqPz2d__QotsWG3OKv2dEghiD74eypzs?key=fnI6SyFgXU9SZRNX5C5vPQ)
105+
106+
107+
The query URL for this subgraph is:
108+
109+
`https://gateway-arbitrum.network.thegraph.com/api/`**[api-key]**`/subgraphs/id/HdVdERFUe8h61vm2fDyycgxjsde5PbB832NHgJfZNqK`
110+
111+
Now, you simply need to  fill in your own API Key to start sending GraphQL queries to this endpoint.
112+
113+
### Getting your own API Key
114+
115+
![API keys](https://lh7-us.googleusercontent.com/docsz/AD_4nXdz7H8hSRf2XqrU0jN3p3KbmuptHvQJbhRHOJh67nBfwh8RVnhTsCFDGA_JQUFizyMn7psQO0Vgk6Vy7cKYH47OyTq5PqycB0xxLyF4kSPsT7hYdMv2MEzAo433sJT6VlQbUAzgPnSxKI9a5Tn3ShSzaxI?key=fnI6SyFgXU9SZRNX5C5vPQ)
116+
117+
118+
In Subgraph Studio, you’ll see the “API Keys” menu at the top of the page. Here you can create API Keys.
119+
120+
## Appendix
121+
122+
### Sample Query
123+
124+
This query shows the most expensive CryptoPunks sold.
125+
126+
```graphql
127+
{
128+
trades(orderBy: priceETH, orderDirection: desc) {
129+
priceETH
130+
tokenId
131+
}
132+
}
133+
134+
```
135+
136+
Passing this into the query URL returns this result:
137+
138+
```
139+
{
140+
"data": {
141+
"trades": [
142+
{
143+
"priceETH": "124457.067524886018255505",
144+
"tokenId": "9998"
145+
},
146+
{
147+
"priceETH": "8000",
148+
"tokenId": "5822"
149+
},
150+
// ...
151+
```
152+
153+
<aside>
154+
💡 Trivia: Looking at the top sales on [CryptoPunks website](https://cryptopunks.app/cryptopunks/topsales) it looks like the top sale is Punk #5822, not #9998. Why? Because they censor the flash-loan sale that happened.
155+
156+
</aside>
157+
158+
### Sample code
159+
160+
```jsx
161+
const axios = require('axios');
162+
163+
const graphqlQuery = `{
164+
trades(orderBy: priceETH, orderDirection: desc) {
165+
priceETH
166+
tokenId
167+
}
168+
}`;
169+
const queryUrl = 'https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK'
170+
171+
const graphQLRequest = {
172+
method: 'post',
173+
url: queryUrl,
174+
data: {
175+
query: graphqlQuery,
176+
},
177+
};
178+
179+
// Send the GraphQL query
180+
axios(graphQLRequest)
181+
.then((response) => {
182+
// Handle the response here
183+
const data = response.data.data
184+
console.log(data)
185+
186+
})
187+
.catch((error) => {
188+
// Handle any errors
189+
console.error(error);
190+
});
191+
```
192+
193+
### Additional resources:
194+
195+
- To explore all the ways you can optimize & customize your subgraph for a better performance, read more about [creating a subgraph here](https://thegraph.com/docs/en/developing/creating-a-subgraph/).
196+
- For more information about querying data from your subgraph, read more [here](https://thegraph.com/docs/en/querying/querying-the-graph/).

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,7 @@ nav:
520520
- PARSIQ: tools/data/parsiq.md
521521
- SQD (Subsquid): tools/data/sqd.md
522522
- SubQuery: tools/data/subquery.md
523+
- The Graph: tools/data/thegraph.md
523524
- Storage:
524525
- IPFS: tools/storage/ipfs.md
525526
- Filecoin: tools/storage/filecoinhelpers.md

0 commit comments

Comments
 (0)