7 minutes
Subgraphs 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,yarnorpnpm)
How to Build a Subgraph
1. Create a Subgraph in Subgraph Studio
- Go to Subgraph Studio
- Connect your wallet
- Click “Create a Subgraph”
- 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:
1npm install -g @graphprotocol/graph-cli@latestUsing yarn:
1yarn global add @graphprotocol/graph-cliVerify install:
1graph --version3. Initialize your Subgraph
You can find commands for your specific Subgraph in Subgraph Studio.
Initialize your Subgraph from an existing contract:
1graph initWhen 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:

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:
1graph codegen && graph build6. 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 operated by The Graph Foundation. 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.
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.
- Get your deploy key from the Subgraph page in Studio

- Authenticate:
1graph auth <DEPLOY_KEY>- Deploy:
1graph 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.
- Click Publish in Studio
- Select network
- (Recommended) Add curation during the same transaction to save on gas costs:

Subgraph publish

Add curation signal so Indexers pick up your Subgraph. See how much signal to add.
Path 2: CLI Approach
- Open the
graph-cli. - Run the following commands to build and publish your Subgraph:
graph codegen && graph buildthengraph publish. - A browser window will prompt you to connect your wallet, add metadata, and publish your Subgraph to the network of your choice.

Custom Options
You can customize the deployment by uploading to a specific IPFS node and using additional flags:
1USAGE2 $ graph publish [SUBGRAPH-MANIFEST] [-h] [--protocol-network arbitrum-one|arbitrum-sepolia --subgraph-id <value>] [-i <value>] [--ipfs-hash <value>] [--webapp-url3 <value>]45FLAGS6 -h, --help Show CLI help.7 -i, --ipfs=<value> [default: https://ipfs.thegraph.com/api/v0] Upload build results to an IPFS node.8 --ipfs-hash=<value> IPFS hash of the subgraph manifest to deploy.9 --protocol-network=<option> [default: arbitrum-one] The network to use for the subgraph deployment.10 <options: arbitrum-one|arbitrum-sepolia>11 --subgraph-id=<value> Subgraph ID to publish to.12 --webapp-url=<value> [default: https://cli.thegraph.com/publish] URL of the web UI you want to use to deploy.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
abisblock insubgraph.yamlmatches the filenames in yourabis/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 codegenafter 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 are associated with your Studio account and can be regenerated.
- Re-copy the deploy key from the Subgraph page in Subgraph Studio and run
graph auth <DEPLOY_KEY>again. - If you recently regenerated the key in Studio, run
graph auth <DEPLOY_KEY>again with the new key 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
eventHandlersexactly 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 failederrors 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
Optionthat doesn’t exist. See Common AssemblyScript Issues. - Fix the handler locally, bump the manifest’s
specVersionor 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.