Building Production Subgraphs: Schema Design and Event Mapping

Frequently Asked Questions

01.What is a subgraph manifest and what does it contain?

A subgraph manifest is a YAML file named subgraph.yaml that defines three components: the data sources (smart contract addresses and ABIs), the GraphQL schema file path, and the mapping file path. The manifest specifies which contract events to listen for and which AssemblyScript handler function processes each event. Without a correctly structured manifest, The Graph's indexer node cannot begin syncing chain data.

02.How do you handle schema upgrades without losing indexed data?

Schema upgrades in The Graph require deploying a new subgraph version, which triggers a full re-sync from the start block. To minimise downtime, deploy the new version alongside the existing one, wait for full sync, then migrate frontend queries to the new endpoint. For additive changes such as new entity fields, use nullable types so existing indexed data remains valid. Removing or renaming fields always requires a full re-sync.

03.What causes subgraph indexing failures and how do you debug them?

Subgraph indexing failures most commonly occur from ABI mismatches between the manifest and deployed contract, integer overflow in AssemblyScript mapping logic, and missing null checks on optional event parameters. Debug by checking the subgraph logs in Subgraph Studio, which surfaces the failing block number and handler name. Reproduce locally with graph-node running against a forked RPC, then fix the mapping and redeploy with an updated start block to avoid full re-sync.