Every blockchain app eventually runs into the same wall: raw chain data is a mess, and turning it into something usable is harder than it looks. The Graph offers two ways through that wall, Subgraphs and Substreams, and a recent post on the topic lays out how to choose between them. Here’s my take on what actually separates the two, and when it’s worth switching.
Subgraphs: built for user-facing applications
If you’re shipping a dapp with a UI, you probably want a Subgraph. It indexes onchain events, structures them, and exposes the result through GraphQL, so a frontend can ask for exactly the data it needs instead of crawling the chain itself.
Under the hood, a Subgraph pulls data from JSON-RPC nodes one block at a time, transforms it using AssemblyScript compiled to WebAssembly, and lands it in a PostgreSQL database. That sequential pull is the tradeoff: reliable, well-trodden, and slower than it needs to be once your data grows past a certain point.
What makes Subgraphs genuinely useful is the ecosystem around them. There are over 15,000 already published, which means a lot of common DeFi data is one query away instead of a build project. Relational questions, who owns this token, what’s in this liquidity pool, are exactly what Subgraphs are good at. For most small and medium projects, that’s the whole job done.
Substreams: built for volume
Substreams solve a different problem. Instead of asking “how do I show a user their balance,” Substreams answer “how do I process the entire history of Aave on Ethereum without waiting three days.” They pull from Firehose, a stream of flat block files, and process history in parallel rather than block by block. Transformations are written in Rust, compiled to WASM, and the output can go anywhere: Postgres, ClickHouse, Kafka, plain files. Substreams themselves don’t provide a query layer. They’re pure ETL, and querying is whatever you bolt on afterward.
That flexibility is the whole point. Subgraphs expose data through GraphQL and use PostgreSQL under the hood. A Substreams pipeline doesn’t commit you to anything, which is exactly what you want if you’re feeding a trading engine, a data warehouse, or a model that needs raw throughput more than a friendly API.
The real question: when do you actually need to switch
It’s tempting to think of Substreams as “Subgraphs but better,” but that’s not quite right; they’re differently shaped tools, not tiers of the same one. The honest signal to watch for is sync time. If your Subgraph needs more than a day or two to catch up on history, sequential indexing has become the bottleneck, not your logic.
A few other tells worth naming: you’re indexing a chain like Solana or a busy L2 where events arrive faster than a linear indexer can keep pace, your roadmap points toward a data warehouse or ML pipeline instead of a single GraphQL endpoint, or you need heavy aggregation math done server-side instead of reconstructed on every client query. None of these mean the original Subgraph choice was wrong. It usually means the project outgrew its first tool, which is a good problem to have.
Migration used to be the tax. Now it’s a skill.
Here’s the part that’s changed recently, and it’s worth calling out. Migration previously required translating GraphQL schemas and AssemblyScript mappings into protobuf definitions and Rust modules.
StreamingFast built an open-source agent skill called substreams-convert that closes most of it. Point an AI coding assistant, Claude Code, Cursor, whatever you use, at an existing Subgraph, and the skill maps schema.graphql entities to protobuf types, translates AssemblyScript handlers into Substreams modules, and wires the result into substreams.yaml, carrying over details like your original start block. It even chains in related skills for build setup and SQL sink deployment automatically.
The practical effect: what used to be weeks of manual porting is now hours of assisted work. Your original Subgraph isn’t wasted effort you throw away when you outgrow it. It’s the starting point for the next version.
So which one do you pick?
Start with Subgraphs if you’re shipping something with a frontend, need relational queries, or want to lean on the existing library of 15,000+ indexed protocols instead of building from zero. Reach for Substreams when the job is volume: high-throughput chains, sub-second block times, heavy transformations, or output that needs to land somewhere other than a GraphQL endpoint.
The more useful framing, honestly, isn’t “which one do I pick forever.” It’s a data stack with two stages: start with a Subgraph because it’s fast and cheap to ship, and scale into Substreams when the project’s growth demands it. With the conversion path now measured in hours instead of weeks, that’s less of a leap than it used to be, and more of a natural next step.