📃
Graph Codex
  • Welcome to The Graph Codex
  • Getting Started
    • Websites
    • Resources
  • Meetings and Events
    • Core Developers Calls
    • Community Talks
    • Indexer Office Hours
    • NFT Community Calls
  • Workshops
    • Subgraph Development
      • Resources
        • Hackathon Workshops
          • Blockchain Development - Querying with Open APIs Course
          • Building a Custom NFT API with Filtering, Sorting, Full Text Search, and Relationships
          • Building a custom NFT API with The Graph
          • Building a Subgraph on Celo @ The Cross Chain Salon
          • Building a Subgraph with Subgraph Studio
          • Building an NFT API and Subgraph on NEAR with The Graph
          • Building an NFT API with the Graph - Nader Dabit
          • Building an NFT Subgraph - Kuneco April 2021
          • Building and Deploying Subgraphs on TheGraphProtocol
          • Building API's on Ethereum, with Nader Dabit
          • Building Apps on the Decentralized Web with Nader Dabit
          • Building Decentralised GraphQL APIs with The Graph
          • Building on Ethereum with GraphQL, The Graph, and Next.js
          • Building Rich APIs on top of Ethereum with The Graph
          • Building Subgraphs on The Graph - MarketMake
          • Building Subgraphs on The Graph
          • Building Subgraphs with The Graph
          • Defining the Web3 Stack - Nader Dabit - (Next.js Conf 2021)
          • How to build a dApp – Nader Dabit
          • How to Build a Full Stack NFT Marketplace on Ethereum with Polygon and Next.js
          • How to Build an NFT API with The Graph
          • Indexing Smart Contracts with OpenZeppelin Subgraphs & The Graph
          • NFT Dev Talk, GenerativeMasks, and Building NFT APIs with OpenZeppelin, GraphQL, and The Graph
          • Query Ethereum with GraphQL with The Graph
          • The Complete Guide to Full Stack Web3 Development
          • Web3 with Nader Dabit
          • Workshop on How to Build Subgraphs
        • Repositories
      • Developer Highlights
      • Developer Guides
      • Subgraph Testing (Matchstick)
    • Protocol Workshops
  • Ecosystem Updates
    • This Month in Indexing
    • This Month in Curation
    • Council Meeting Notes
    • Governance
      • Governance Resources
      • Graph Improvement Proposals (GIPs)
        • 0000-template
        • 0001-gip-process
        • 0002-gip-withdraw-indexer-rewards
        • 0003-gip-rewards-no-signal
        • 0004-gip-withdraw-indexer-rewards-thawing
        • 0005-gas-costing
        • 0006-gip-withdraw-helper
        • 0007-separate-slashing-percentages
        • 0008-subgraph-api-versioning-and-feature-support
        • 0009-arbitration-charter
        • 0010-rewards-snapshot-empty-poi-fix
        • 0011-stake-to-init-fix
        • 0012-cache-contract-addresses
        • 0013-reduce-curation-tax
        • 0014-batch-gns-transactions
        • 0015-allow-unstake-passing-larger-amount-available
        • 0016-revert-precision-assign-delegation-share
        • 0017-allow-batching-calls-staking-contract
        • 0018-subgraph-ownership-transfer
        • 0019-save-gas-initializing-subgraph-deployment
        • 0020-unattestable-indexer-responses
        • 0023-subgraph-ownership-transfer-nft
        • 0024-query-versioning
        • 0025-principal-protected-bonding-curves
        • 0026-decaying-curation-tax
      • Graph Request for Comments (GRCs)
        • 0001-data-edge
  • Repositories and Documentation
    • Official Repositories
    • Official Documentation
      • About
        • Introduction
        • Network Overview
      • Developer
        • Quick Start
        • Define a Subgraph
        • Create a Subgraph
        • Publish a Subgraph to the Decentralized Network
        • Query The Graph
        • Querying from an Application
        • Querying Best Practices
        • Distributed Systems
        • AssemblyScript API
        • AssemblyScript Migration Guide
        • GraphQL API
        • Unit Testing Framework
        • Deprecating a Subgraph
        • Developer FAQs
      • Indexer
      • Delegator
      • Curator
      • The Graph Explorer
      • Subgraph Studio
        • How to use the Subgraph Studio
        • Deploy a Subgraph to the Subgraph Studio
        • Billing on the Subgraph Studio
        • Managing your API Keys
        • Subgraph Studio FAQs
        • Multisig Users
      • Hosted Service
        • What is Hosted Service?
        • Deploy a Subgraph to the Hosted Service
        • Migrating an Existing Subgraph to The Graph Network
      • Supported Networks
        • NEAR
Powered by GitBook
On this page
  • Subgraph Studio
  • Hosted Service

Was this helpful?

Edit on GitHub
  1. Repositories and Documentation
  2. Official Documentation
  3. Developer

Quick Start

PreviousDeveloperNextDefine a Subgraph

Last updated 2 years ago

Was this helpful?

This guide will quickly take you through how to initialize, create, and deploy your subgraph on:

  • Subgraph Studio - used only for subgraphs that index Ethereum mainnet

  • Hosted Service - used for subgraphs that index other networks outside of Ethereum mainnnet (e.g. Binance, Matic, etc)

Subgraph Studio

1. Install the Graph CLI

The Graph CLI is written in JavaScript and you will need to have either npm or yarn installed to use it.

# NPM
$ npm install -g @graphprotocol/graph-cli

# Yarn
$ yarn global add @graphprotocol/graph-cli

2. Initialize your Subgraph

  • Initialize your subgraph from an existing contract.

graph init --studio <SUBGRAPH_SLUG>
  • Your subgraph slug is an identifier for your subgraph. The CLI tool will walk you through the steps for creating a subgraph, such as contract address, network, etc as you can see in the screenshot below.

3. Write your Subgraph

The previous commands create a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files:

  • Manifest (subgraph.yaml) - The manifest defines what datasources your subgraphs will index.

  • Schema (schema.graphql) - The GraphQL schema defines what data you wish to retreive from the subgraph.

  • AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema.

For more information on how to write your subgraph, see Create a Subgraph.

4. Deploy to the Subgraph Studio

  • Go to the Subgraph Studio https://thegraph.com/studio/ and connect your wallet.

  • Click "Create" and enter the subgraph slug you used in step 2.

  • Run these commands in the subgraph folder

$ graph codegen
$ graph build
  • Authenticate and deploy your subgraph. The deploy key can be found on the Subgraph page in Subgraph Studio.

$ graph auth --studio <DEPLOY_KEY>
$ graph deploy --studio <SUBGRAPH_SLUG>
  • You will be asked for a version label. It's strongly recommended to use the following conventions for naming your versions. Example: 0.0.1, v1, version1

5. Check your logs

The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the GraphiQL Playground. Use this endpoint. Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, Qm... is the deployment ID (which can be located on the Subgraph page under Details). The query below will tell you when a subgraph fails so you can debug accordingly:

{
  indexingStatuses(subgraphs: ["Qm..."]) {
    node
    synced
    health
    fatalError {
      message
      block {
        number
        hash
      }
      handler
    }
    nonFatalErrors {
      message
      block {
        number
        hash
      }
      handler
    }
    chains {
      network
      chainHeadBlock {
        number
      }
      earliestBlock {
        number
      }
      latestBlock {
        number
      }
      lastHealthyBlock {
        number
      }
    }
    entityCount
  }
}

6. Query your Subgraph

You can now query your subgraph by following these instructions. You can query from your dApp if you don't have your API key via the free, rate-limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application here.

Hosted Service

1. Install the Graph CLI

"The Graph CLI is an npm package and you will need npm or yarn installed to use it.

# NPM
$ npm install -g @graphprotocol/graph-cli

# Yarn
$ yarn global add @graphprotocol/graph-cli

2. Initialize your Subgraph

  • Initialize your subgraph from an existing contract.

$ graph init --product hosted-service --from-contract <Address>
  • You will be asked for a subgraph name. The format is <Github>/<Subgraph Name>. Ex: graphprotocol/examplesubgraph

  • If you'd like to initialize from an example, run the command below:

$ graph init --product hosted-service --from-example
  • In the case of the example, the subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits NewGravatar or UpdateGravatar events whenever avatars are created or updated.

3. Write your Subgraph

The previous command will have created a scaffold from where you can build your subgraph. When making changes to the subgraph, you will mainly work with three files:

  • Manifest (subgraph.yaml) - The manifest defines what datasources your subgraph will index

  • Schema (schema.graphql) - The GraphQL schema define what data you wish to retrieve from the subgraph

  • AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema

For more information on how to write your subgraph, see Create a Subgraph.

4. Deploy your Subgraph

  • Sign into the Hosted Service using your GitHub account

  • Click Add Subgraph and fill out the required information. Use the same subgraph name as in step 2.

  • Run codegen in the subgraph folder

 # NPM
$ npm run codegen

# Yarn
$ yarn codegen
  • Add your Access token and deploy your subgraph. The access token is found on your dashboard in the Hosted Service.

$ graph auth --product hosted-service <ACCESS_TOKEN>
$ graph deploy --product hosted-service <GITHUB_USER>/<SUBGRAPH NAME>

5. Check your logs

The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the GraphiQL Playground. Use this endpoint. Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, Qm... is the deployment ID (which can be located on the Subgraph page under Details). The query below will tell you when a subgraph fails so you can debug accordingly:

{
  indexingStatuses(subgraphs: ["Qm..."]) {
    node
    synced
    health
    fatalError {
      message
      block {
        number
        hash
      }
      handler
    }
    nonFatalErrors {
      message
      block {
        number
        hash
      }
      handler
    }
    chains {
      network
      chainHeadBlock {
        number
      }
      earliestBlock {
        number
      }
      latestBlock {
        number
      }
      lastHealthyBlock {
        number
      }
    }
    entityCount
  }
}

6. Query your Subgraph

Follow these instructions to query your subgraph on the Hosted Service.

Subgraph command