Subgraph Manifest Specification

Overview

The subgraph manifest specifies all the information required to index and query a specific subgraph. This is the entry point to your subgraph. The subgraph manifest, and all the files linked from it, is what is deployed to IPFS and hashed to produce a subgraph ID that can be referenced and used to retrieve your subgraph in The Graph.

Spec Version: v.0.0.4

Format

Any data format that has a well-defined 1:1 mapping with the IPLD Canonical Format may be used to define a subgraph manifest. This includes YAML and JSON. Examples in this document are in YAML.

Top-Level Fields

specVersion

String

required

A Semver version indicating which version of this API is being used.

Show Example

specVersion: 0.0.4

schema

Schema

required

The GraphQL schema of this subgraph. See Schema for details.

Show Example

schema:
  file: ./schema.graphql

description

String

An optional description of the subgraph’s purpose.

Show Example

description: "Uniswap V2 subgraph for tracking liquidity pools"

repository

String

An optional link to where the subgraph lives.

Show Example

repository: "https://github.com/example/my-subgraph"

graft

Graft Base

An optional base to graft onto. See Graft Base for details.

Show Example

graft:
  base: QmQwXy...
  block: 12345678

dataSources

Array<Data Source Spec>

required

Each data source spec defines the data that will be ingested as well as the transformation logic to derive the state of the subgraph’s entities based on the source data.See Data Sources for complete documentation.

templates

Array<Data Source Template Spec>

Each data source template defines a data source that can be created dynamically from the mappings.See Data Source Templates for complete documentation.

features

Array<String>

A list of feature names used by the subgraph. Required for specVersion >= 0.0.4.See Features for available feature names.

Show Example

features:
  - nonFatalErrors
  - fullTextSearch

Schema

The schema defines the GraphQL types that will be generated for your subgraph.

file

Path

required

The path of the GraphQL IDL file, either local or on IPFS.See Path for format details.

Example

schema:
  file: ./schema.graphql

Path

A path has one field path, which either refers to a path of a file on the local dev machine or an IPLD link. When using the Graph-CLI, local paths may be used during development, and then, the tool will take care of deploying linked files to IPFS and replacing the local paths with IPLD links at deploy time.

path

String | IPLD Link

required

A path to a local file or IPLD link.

Local Path
IPLD Link

file: ./schema.graphql

file: /ipfs/QmTXzATwNfgGVukV1fX2T6xw9f6LAYRVWpsdXyRWzUR2H9

Graft Base

A subgraph can be grafted on top of another subgraph, meaning that, rather than starting to index the subgraph from the genesis block, the subgraph is initialized with a copy of the given base subgraph, and indexing resumes from the given block.

Grafting requires the grafting feature to be declared in the features list for specVersion >= 0.0.4.

base

String

required

The subgraph ID of the base subgraph.This is the IPFS hash of the deployed subgraph.

block

BigInt

required

The block number up to which to use data from the base subgraph.Indexing will resume from this block number.

Example

graft:
  base: QmQwXy8dhDzFfJHT4KJVXcGqTSQhvVuqN2G9rMpWLZ8VWP
  block: 12345678

Features

Starting from specVersion 0.0.4, a subgraph must declare all feature names it uses to be considered valid.

A Graph Node instance will reject a subgraph deployment if:

the specVersion is equal to or higher than 0.0.4 AND
it hasn’t explicitly declared a feature it uses.

No validation errors will happen if a feature is declared but not used.

Available Features

nonFatalErrors

Feature

Enables non-fatal error handling in mappings. When enabled, errors in handlers won’t stop the subgraph from syncing.

fullTextSearch

Feature

Enables full-text search capabilities on entities. Requires special field annotations in the schema.

grafting

Feature

Enables grafting functionality. Required when using the graft field in the manifest.

ipfsOnEthereumContracts

Feature

Enables IPFS data fetching from Ethereum contract events and calls.

Example

specVersion: 0.0.4
features:
  - nonFatalErrors
  - fullTextSearch
  - ipfsOnEthereumContracts

Complete Manifest Example

Basic Subgraph
With Templates
With Grafting

specVersion: 0.0.4
description: My Ethereum Subgraph
repository: https://github.com/example/my-subgraph
schema:
  file: ./schema.graphql
features:
  - nonFatalErrors
dataSources:
  - kind: ethereum/contract
    name: MyContract
    network: mainnet
    source:
      address: "0x1234567890123456789012345678901234567890"
      abi: MyContract
      startBlock: 10000000
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - User
        - Transaction
      abis:
        - name: MyContract
          file: ./abis/MyContract.json
      eventHandlers:
        - event: Transfer(address,address,uint256)
          handler: handleTransfer
      file: ./src/mapping.ts

specVersion: 0.0.4
description: DEX Subgraph with Dynamic Pairs
schema:
  file: ./schema.graphql
features:
  - nonFatalErrors
dataSources:
  - kind: ethereum/contract
    name: Factory
    network: mainnet
    source:
      address: "0xFactory..."
      abi: Factory
      startBlock: 10000000
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Factory
        - Pair
      abis:
        - name: Factory
          file: ./abis/Factory.json
        - name: Pair
          file: ./abis/Pair.json
      eventHandlers:
        - event: PairCreated(address,address,address,uint256)
          handler: handlePairCreated
      file: ./src/factory.ts
templates:
  - kind: ethereum/contract
    name: Pair
    network: mainnet
    source:
      abi: Pair
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Pair
        - Token
        - Swap
      abis:
        - name: Pair
          file: ./abis/Pair.json
      eventHandlers:
        - event: Swap(address,uint256,uint256,uint256,uint256,address)
          handler: handleSwap
      file: ./src/pair.ts

specVersion: 0.0.4
description: Grafted Subgraph
schema:
  file: ./schema.graphql
features:
  - grafting
graft:
  base: QmQwXy8dhDzFfJHT4KJVXcGqTSQhvVuqN2G9rMpWLZ8VWP
  block: 15000000
dataSources:
  - kind: ethereum/contract
    name: MyContract
    network: mainnet
    source:
      address: "0x1234567890123456789012345678901234567890"
      abi: MyContract
      startBlock: 15000000
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Entity
      abis:
        - name: MyContract
          file: ./abis/MyContract.json
      eventHandlers:
        - event: Event(address,uint256)
          handler: handleEvent
      file: ./src/mapping.ts

GraphQL API

Graphman CLI

Subgraph Manifest

Subgraph Manifest Specification

Overview

Format

Top-Level Fields

Schema

Example

Path

Graft Base

Example

Features

Available Features

Example

Complete Manifest Example

Next Steps

Data Sources

Mappings

Build docs developers (and LLMs) love

GraphQL API

Graphman CLI

Subgraph Manifest

​Overview

​Format

​Top-Level Fields

​Schema

​Example

​Path

​Graft Base

​Example

​Features

​Available Features

​Example

​Complete Manifest Example

​Next Steps

Data Sources

Mappings

Build docs developers (and LLMs) love

Overview

Format

Top-Level Fields

Schema

Example

Path

Graft Base

Example

Features

Available Features

Example

Complete Manifest Example

Next Steps