Indexing blockchain data with The Graph
Reading data from a blockchain sounds simple until you try to do it at scale. You can query a node for a specific transaction or block, but if you want to answer questions like "what are all the transfers to this address in the last month sorted by value," you're in trouble. That's what The Graph solves.
The problem with direct node queries
Ethereum nodes expose a JSON-RPC API. It's designed for writing transactions and reading current state, not for analytical queries. If you want historical event data, you'd need to index every block yourself, store the relevant events, and build query infrastructure around it.
Most teams don't want to do that. The Graph is an indexing protocol that does this work for you via subgraphs.
What a subgraph is
A subgraph is a configuration that tells The Graph how to index a specific contract's events and state. You define:
- Which contract(s) to watch
- Which events to process
- How to transform event data into a schema
- GraphQL entities to expose
The Graph's indexer nodes watch the blockchain, process events as they're emitted, and make the indexed data queryable via GraphQL.
Setting up a subgraph
The Graph has a hosted service and a decentralized network. For development, the hosted service is easier to start with. The Graph Studio dashboard is where you create and deploy subgraphs.
Install the CLI:
npm install -g @graphprotocol/graph-cli
graph init --product hosted-service
This generates the boilerplate. The key file is subgraph.yaml:
specVersion: 0.0.5
schema:
file: ./schema.graphql
dataSources:
- kind: ethereum
name: MyToken
network: mainnet
source:
address: "0xabc..."
abi: ERC20
startBlock: 18000000
mapping:
kind: ethereum/events
apiVersion: 0.0.7
language: wasm/assemblyscript
entities:
- Transfer
abis:
- name: ERC20
file: ./abis/ERC20.json
eventHandlers:
- event: Transfer(indexed address,indexed address,uint256)
handler: handleTransfer
file: ./src/mapping.ts
Writing mapping handlers
Mappings are written in AssemblyScript (a TypeScript-like language that compiles to WebAssembly). Each event handler receives the event and updates entities:
import { Transfer } from "../generated/MyToken/ERC20";
import { TransferEvent } from "../generated/schema";
export function handleTransfer(event: Transfer): void {
let transfer = new TransferEvent(event.transaction.hash.toHex());
transfer.from = event.params.from;
transfer.to = event.params.to;
transfer.amount = event.params.value;
transfer.blockNumber = event.block.number;
transfer.save();
}
The generated/ directory is created by graph codegen from your ABI and schema. Always run codegen after changing either.
Querying the subgraph
Once deployed, your subgraph exposes a GraphQL endpoint. You can query it from any client:
{
transferEvents(
first: 100
orderBy: blockNumber
orderDirection: desc
where: { to: "0xabc..." }
) {
from
to
amount
blockNumber
}
}
The Graph Explorer has a built-in query interface for published subgraphs where you can experiment before integrating.
Pagination and performance
The default limit per query is 100 entities, max 1000. For large datasets you need to paginate using skip and first, or use cursor-based pagination with id_gt.
Be careful with deeply nested queries. GraphQL makes it easy to write queries that fan out exponentially. Test with realistic data volumes before shipping.
Subgraph Studio dashboard
The Subgraph Studio dashboard shows indexing status, query counts, and error logs for your subgraphs. If an entity isn't appearing in queries, the indexing logs in Studio are the first place to look. Errors in your mapping handlers surface there.
The Graph is one of those tools that feels like significant overhead to set up but pays for itself quickly once you have more than a few data requirements. The alternative (maintaining your own event indexer) is significantly more work.
