Subgraph Manifest Specification

Complete specification for the subgraph manifest file

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

file: ./schema.graphql

IPLD Link

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

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

With Templates

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

With Grafting

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

Next Steps

Data Sources

Learn about configuring data sources

Mappings

Configure handlers and mapping logic