Skip to content

quick-start.mdx

Latest commit

 

History

History
233 lines (149 loc) · 10.2 KB

quick-start.mdx

File metadata and controls

233 lines (149 loc) · 10.2 KB
Raw
title Quick Start

Create, deploy, and query a Subgraph on The Graph Network.

By the end, you'll have:

  • Initialized a Subgraph from a smart contract
  • Deployed it to Subgraph Studio for testing
  • Published to The Graph Network for decentralized indexing using Studio or CLI

Prerequisites

  • A crypto wallet
  • A deployed smart contract on a supported network
  • Node.js & a package manager of your choice (npm, yarn or pnpm)

How to Build a Subgraph

1. Create a Subgraph in Subgraph Studio

  1. Go to Subgraph Studio
  2. Connect your wallet
  3. Click "Create a Subgraph"
  4. Name it in Title Case: "Subgraph Name Chain Name"

2. Install the Graph CLI

On your local machine, run one of the following commands:

Using npm:

npm install -g @graphprotocol/graph-cli@latest

Using yarn:

yarn global add @graphprotocol/graph-cli

Verify install:

graph --version

3. Initialize your Subgraph

You can find commands for your specific Subgraph in Subgraph Studio.

Initialize your Subgraph from an existing contract:

graph init

When you initialize your Subgraph, the CLI will ask you for the following information:

  • Protocol: Choose the protocol your Subgraph will be indexing data from.
  • Subgraph slug: Create a name for your Subgraph. Your Subgraph slug is an identifier for your Subgraph.
  • Directory: Choose a directory to create your Subgraph in.
  • Ethereum network (optional): You may need to specify which EVM-compatible network your Subgraph will be indexing data from.
  • Contract address: Locate the smart contract address you'd like to query data from.
  • ABI: If the ABI is not auto-populated, you will need to input it manually as a JSON file.
  • Start Block: Set this to the block your contract was deployed in. Indexing earlier wastes time; indexing later misses events emitted before the start block.
  • Contract Name: Input the name of your contract.
  • Index contract events as entities: It is suggested that you set this to true, as it will automatically add mappings to your Subgraph for every emitted event.
  • Add another contract (optional): You can add another contract.

See the following screenshot for an example of what to expect when initializing your Subgraph:

Subgraph command

[!NOTE] How to find your Start Block

On a block explorer, open your contract and find the contract creation transaction. The block number of that transaction is your Start Block.

  • Etherscan and most EVM explorers: look for "Contract Creator" on the contract page, then click the creation transaction hash to see its block number.
  • If you set the Start Block too low, the initial sync takes longer than necessary. If you set it too high, events emitted before that block are never indexed and you will need to redeploy.

4. Edit your Subgraph

When making changes to the Subgraph, you will primarily work with three files:

  • Manifest (subgraph.yaml): Defines what data sources your Subgraph will index.
  • Schema (schema.graphql): Defines what data you wish to retrieve from the Subgraph.
  • AssemblyScript Mappings (mapping.ts): Translates data from your data sources to the entities defined in the schema.

For a detailed breakdown on how to write your Subgraph, refer to Creating a Subgraph.

Path 1: Studio Approach

5. Build your Subgraph

Run the following:

graph codegen && graph build

6. Deploy your Subgraph to Subgraph Studio

When you deploy a Subgraph, you push it to Subgraph Studio, where you can test, stage and review it. A deployed Subgraph's indexing is performed by the Upgrade Indexer, which is a single Indexer owned and operated by Edge & Node. A deployed Subgraph is free to use, rate-limited, not visible to the public, and meant to be used for development, staging, and testing purposes.

[!IMPORTANT] You do not need to use Subgraph Studio to publish your Subgraph to The Graph Network. Studio is only required for testing and staging your Subgraph prior to publishing.

  1. Get your deploy key from the Subgraph page in Studio

Deploy key

  1. Authenticate:
graph auth <DEPLOY_KEY>
  1. Deploy:
graph deploy <SUBGRAPH_SLUG>

7. Review in Studio

Use the Studio to:

  • Run a sample query.

  • Analyze your Subgraph in the dashboard to check information.

  • Check the logs on the dashboard to see if there are any errors with your Subgraph. The logs of an operational Subgraph will look like this:

    Subgraph logs

8. Publish to The Graph Network

When your Subgraph is ready for a production environment, you can publish it to the decentralized network. Publishing is an onchain action that does the following:

  • It makes your Subgraph available to be indexed by the decentralized Indexers on The Graph Network.
  • It removes rate limits and makes your Subgraph publicly searchable and queryable in Graph Explorer.
  • It makes your Subgraph available for Curators to add curation signal.
  1. Click Publish in Studio
  2. Select network
  3. (Recommended) Add curation during the same transaction to save on gas costs: Subgraph publish

Publish a Subgraph on Subgraph Studio

Curation with 3,000+ GRT is recommended to incentivize indexing.

Path 2: CLI Approach

  1. Open the graph-cli.
  2. Run the following commands to build and publish your Subgraph: graph codegen && graph build then graph publish.
  3. A browser window will prompt you to connect your wallet, add metadata, and publish your Subgraph to the network of your choice.

cli-ui

Custom Options

You can customize the deployment by uploading to a specific IPFS node and using additional flags:

USAGE
  $ graph publish [SUBGRAPH-MANIFEST] [-h] [--protocol-network arbitrum-one|arbitrum-sepolia --subgraph-id <value>] [-i <value>] [--ipfs-hash <value>] [--webapp-url
    <value>]

FLAGS
  -h, --help                   Show CLI help.
  -i, --ipfs=<value>           [default: https://ipfs.thegraph.com/api/v0] Upload build results to an IPFS node.
  --ipfs-hash=<value>          IPFS hash of the subgraph manifest to deploy.
  --protocol-network=<option>  [default: arbitrum-one] The network to use for the subgraph deployment.
                               <options: arbitrum-one|arbitrum-sepolia>
  --subgraph-id=<value>        Subgraph ID to publish to.
  --webapp-url=<value>         [default: https://cli.thegraph.com/publish] URL of the web UI you want to use to deploy.

[!NOTE] Add GRT signal to your Subgraph to incentivize Indexers to query your Subgraph. Refer to Adding Signal for specifics.

Final Step: Query your Subgraph

After publishing, access your Subgraph's Query URL from Graph Explorer. You can query your Subgraph by sending GraphQL queries to its Query URL, which you can find by clicking the Query button.

You get access to 100,000 free queries/month with your Subgraph on The Graph Network.

Refer to Querying The Graph to structure GraphQL queries.

Troubleshooting

A few issues come up often on first deploys. If something doesn't work, check here before filing an issue.

graph codegen fails with "Cannot find ABI"

The CLI expects each ABI referenced in subgraph.yaml to exist at the path you gave under abis:.

  • Check the abis block in subgraph.yaml matches the filenames in your abis/ directory exactly (case-sensitive).
  • If you downloaded the ABI from Etherscan, make sure you saved the raw JSON array, not the page's HTML.
  • Re-run graph codegen after any ABI or schema change. Skipping codegen is the most common cause of "type not found" errors in mappings.

graph deploy fails with "Unauthorized" or "Invalid deploy key"

Deploy keys expire and are Subgraph-specific.

  • Re-copy the deploy key from the Subgraph page in Subgraph Studio and run graph auth <DEPLOY_KEY> again.
  • If you recently rotated the key in Studio, any terminal that ran graph auth with the old key still has it cached. Re-authenticate before deploying.

Subgraph deploys but indexes no data

If the Studio dashboard shows "Synced" but queries return empty, the Start Block is almost always wrong.

  • Verify the Start Block is the block the contract was deployed in, not a later block.
  • Confirm the events in your manifest's eventHandlers exactly match the events emitted by your contract's ABI, including indexed parameters.
  • Check the logs in the Studio dashboard for "event not found" or "no matching handler" warnings.

Indexing stalls partway through sync

Usually a mapping handler error causes the indexer to stop at the failing block.

  • Open the Studio dashboard logs for your Subgraph. Failed handlers surface as subgraph failed errors with the block number and a stack trace.
  • Common causes: reading from a null field, calling a contract that hasn't been deployed yet at the current block, or unwrapping an Option that doesn't exist. See Common AssemblyScript Issues.
  • Fix the handler locally, bump the manifest's specVersion or redeploy under a new version label, then publish again.

Which path should I use: Studio or CLI?

Both paths end with the same published Subgraph on The Graph Network.

  • Studio path is easier the first time. You deploy, watch indexing progress in the dashboard, then click Publish when you're happy.
  • CLI path (graph publish) skips the deploy-to-Studio step and publishes straight to the network via a browser wallet prompt. Faster once you're confident the Subgraph works.

If you're learning, use Studio. If you're shipping a Subgraph you've already tested locally, use the CLI.