Subgraphs are the core data indexing primitive of The Graph Protocol — open APIs that index specific smart contract events and state from blockchains and organize them into a structured GraphQL database that developers can query efficiently. Querying blockchain data directly from a node is computationally expensive and structurally awkward: you’d have to scan every block for relevant events, join data across multiple contracts, and aggregate state changes manually. Subgraphs solve this by defining (in a manifest file) which contracts to watch, which events to index, and how to transform raw event data into application-ready entities — then continuously updating as new blocks arrive. A DeFi protocol like Uniswap has a subgraph indexing every pool creation, swap, liquidity add/remove, and fee collection. Analytics platforms like Dune or apps like Uniswap’s own frontend query this subgraph to power real-time data displays. As of 2024, thousands of subgraphs exist for most major EVM protocols across Ethereum, Polygon, Arbitrum, Optimism, and other chains — forming the data layer that nearly every serious DeFi application relies on.
Subgraph Architecture
Three components:
- Manifest (
subgraph.yaml): Defines which contracts and events to index - Schema (
schema.graphql): Defines data entities (like database tables) - Mappings (
src/mapping.ts): AssemblyScript code that transforms events into schema entities
Example manifest fragment:
“`yaml
dataSources:
- name: UniswapV3Factory
network: mainnet
source:
address: “0x1F98431c8aD98523631AE4a59f267346ea31F984”
abi: UniswapV3Factory
startBlock: 12369621
mapping:
eventHandlers:
- event: PoolCreated(indexed address,indexed address,indexed uint24,int24,address)
handler: handlePoolCreated
“`
Example GraphQL query:
“`graphql
{
pools(where: { volumeUSD_gt: “1000000” }, orderBy: volumeUSD, orderDirection: desc) {
id
token0 { symbol }
token1 { symbol }
volumeUSD
feeTier
}
}
“`
Hosted vs. Decentralized Service
Hosted Service (being deprecated): Free, centralized; run by Graph Protocol team
Decentralized Network: Indexers stake GRT to serve queries; curators signal which subgraphs to index; developers pay GRT per query
Key Subgraphs
- Uniswap v3: Pools, swaps, positions, fees
- Compound: Markets, borrowing, liquidations
- ENS: Names, registrations, transfers
- MakerDAO: Vaults, stability fees, liquidations
- Aave: Reserves, user positions, interest accrual
Related Terms
Sources
- “The Graph Protocol: Decentralized Indexing for Web3” — The Graph Foundation (2020-2023). Technical whitepaper and protocol documentation for The Graph — explaining the subgraph indexing mechanism, GRT token economics, the role of indexers/curators/delegators, and the migration path from hosted service to the decentralized network.
- “Building and Deploying Subgraphs: Developer Experience” — Graph Protocol Documentation / Various (2023). Developer guide covering the full subgraph development lifecycle — from defining schema and mappings through local testing, deployment, and optimization for production query performance.
- “Subgraph Economics: GRT Curation and Indexer Incentives” — The Graph / TokenTerminal (2022). Economic analysis of The Graph’s incentive design — examining curator bonding curves, indexer competition, query fee pricing, and whether the GRT token economics produce efficient allocation of indexing resources to high-demand subgraphs.
- “Subgraphs vs. Direct Node Access: Performance and Cost Comparison” — Alchemy (2023). Technical comparison of querying blockchain data via subgraphs vs. direct RPC node calls — measuring query latency, API rate limits, costs, and the types of queries that are better suited to each approach.
- “Subgraph Reliability and the Data Infrastructure Layer” — DeFi Safety / Messari (2023). Risk analysis of the DeFi ecosystem’s dependency on subgraph infrastructure — examining what happens when key subgraphs have errors, go down, or produce incorrect data, and assessing the centralization risk of concentration in The Graph’s hosted service.