Back to Resources
Guides

What is a subgraph?

What is a subgraph?

A subgraph is an open API that reads data from a blockchain, turns it into structured records and serves those records through GraphQL. The Graph, the protocol that introduced the term, defines it as "a custom, open API that extracts data from a blockchain, processes it, and stores it so it can be easily queried via GraphQL" (The Graph docs). Developers use subgraphs to power the dashboards, token pages and portfolio views of onchain apps.

In math, a subgraph is a graph whose vertices and edges are a subset of a larger graph (Wolfram MathWorld). This guide covers the blockchain meaning: the parts of a subgraph, how it indexes data step by step, how apps query it, where it runs and where its limits are.

Why do blockchains need subgraphs?

A blockchain is built to write and verify transactions. Reading it back in a useful shape is harder. The Graph's own documentation lists the main problems (The Graph docs):

  • No tables. Data sits in an append-only chain of blocks, so a question like "all transfers for this wallet" means scanning block by block.
  • No query language. Nodes expose low-level RPC methods such as eth_getLogs and eth_call, with no built-in way to filter, sort, aggregate or join.
  • History needs archive nodes. Most nodes prune old state, so reading the past takes an archive node.
  • Data is scattered. One app spreads its data across many contracts and events.

A subgraph solves this for one app at a time. It watches the contracts the app cares about, stores what happened in a database and answers questions about it through a single endpoint.

What are the parts of a subgraph?

Every subgraph is defined by three files (The Graph docs):

FileWhat it holdsWritten in
subgraph.yaml (the manifest)The network, the contract addresses, the start block, the events to watch and the handler for each eventYAML
schema.graphql (the schema)The entities the subgraph stores, such as Token, Pool or Swap, and their fieldsGraphQL schema language
mapping.ts (the mappings)The code that turns each event into entities and saves themAssemblyScript

The manifest is the subgraph's map. It names the network, each data source contract and its ABI, an optional startBlock and the event handlers. The Graph suggests starting from the block in which the contract was created. Handlers can also react to function calls or to every new block.

The schema describes the data the app will read. Each type marked @entity becomes a table, and Graph Node generates query fields for single records and for collections of that type (The Graph docs). The Graph recommends designing entities around the objects an app needs, such as an account or a position, and marking records that never change as immutable, since they are faster to write and query.

The mappings do the work. For every event handler named in the manifest, the developer writes a function that reads the event's parameters, creates or updates an entity and saves it to the store. Mappings are written in AssemblyScript, a stricter subset of TypeScript that compiles to WebAssembly (The Graph docs).

How does a subgraph work, step by step?

Once the three files are written and deployed, an indexer runs them through Graph Node, the open-source software that indexes subgraphs and serves the results over GraphQL (GitHub).


A subgraph turns contract events into entities that an app can query with GraphQL.

  1. A contract emits an event. A swap, a deposit or a transfer writes an event log to the chain.
  2. The indexer matches it. Graph Node scans blocks from the start block onward and checks each event against the manifest.
  3. A mapping runs. The matching handler reads the event, loads or creates an entity and saves it.
  4. The store keeps the result. Entities are written to a database and kept in step with each new block.
  5. An app queries it. The frontend sends a GraphQL query and gets back exactly the fields it asked for.

The first run is a sync: the subgraph processes every relevant block from its start block to the current head. After that it follows the chain block by block.

How do you query a subgraph?

You query a subgraph with GraphQL, "a query language for APIs and a runtime for executing those queries with existing data" (The Graph docs). Each entity type in the schema gets two root fields: one for a single record and one for a list.

A query for the first ten tokens in a subgraph looks like this:

The GraphQL API supports filters with where, sorting with orderBy and orderDirection, pagination with first and skip, and time-travel queries that read the data as it stood at a given block number. The API is read-only: apps read data from a subgraph and write to the chain through their contracts.

On The Graph Network, each subgraph has its own query URL in Graph Explorer, and every request needs an API key created in Subgraph Studio. The Free Plan covers 100,000 queries per month. Beyond that, the Growth Plan charges per query, paid by credit card or in GRT on Arbitrum (The Graph docs).

Where do subgraphs run?

There are three common ways to run a subgraph.

The Graph Network. Developers build with the Graph CLI, test in Subgraph Studio and then publish onchain, which registers the subgraph and makes it visible to Indexers. Indexers are node operators who stake GRT, index subgraphs and earn query fees and indexing rewards (The Graph docs). A published subgraph needs curation signal, which is GRT locked on that subgraph, to attract Indexers (The Graph docs). The Graph reports more than 1.27 trillion queries served to over 75,000 projects as of early 2026 (The Graph docs).

Your own Graph Node. Graph Node is open source, so a team can run it on its own infrastructure and serve its subgraphs privately (GitHub).

A hosted provider. Some data companies run subgraphs as a managed service. Goldsky, for example, describes its subgraph indexing as fully backwards compatible, using the same WebAssembly processing layer (Goldsky docs).

You may still see older guides that point to The Graph's hosted service. The Graph retired it in 2024. Hosted subgraphs had to move to the network during an upgrade window that closed in June 2024, and the hosted endpoints were shut down when the window ended (The Graph blog, The Graph blog).

What are subgraphs used for?

Subgraphs fit apps that need their own structured data about specific contracts. The Graph names DeFi dashboards, NFT marketplaces, governance interfaces and most dapp frontends as typical uses (The Graph docs). In practice that covers:

  • DeFi frontends: pool lists, positions, swap history and TVL charts.
  • NFT apps: ownership, sales and collection stats.
  • Governance: proposals, votes and delegate power.
  • Analytics: daily volumes and user counts built as aggregate entities inside the mappings.

What are the limits of a subgraph?

Subgraphs work best for a defined, app-specific dataset. A few limits come with that design:

  • One network per subgraph. A subgraph can index many contracts, but all on one network (The Graph docs). A multichain app runs one subgraph per chain and merges the results.
  • Only what you defined. A subgraph stores the entities its mappings save. A new question about data you did not map means changing the code and deploying a new version, which Indexers then index again (The Graph docs).
  • Sync time. The first sync processes every block from the start block, so a subgraph with an early start block on a busy chain takes longer to be ready.
  • Custom code to maintain. Mappings are code, so they need testing, upgrades and fixes as contracts change.
  • Query shape. GraphQL answers entity lookups, filters and sorting. Totals such as daily volume are usually built ahead of time as aggregate entities in the mappings (The Graph docs).

For these cases, The Graph offers Substreams, a parallel indexing technology for high-throughput streams (The Graph docs). Other teams query indexed raw chain data with SQL. Turtle will cover the wider topic in upcoming guides on blockchain indexing and onchain data.

How does Bedrock by Turtle fit in?

Bedrock is Turtle's onchain data product. It indexes the full history of 40 EVM chains and lets teams query it with standard SQL (Bedrock). According to Bedrock's site:

  • History from genesis. Every block, log and trace is already loaded into ClickHouse, ordered and deduplicated, back to 2015, and new blocks land beside the history.
  • SQL on raw tables. Teams write standard SQL with joins, aggregations and window functions over the raw blocks, logs and traces.
  • Enriched datasets. Decoded tokens, transfers and contracts tables sit next to the raw data.
  • Pipes. Any slice of the data can be delivered to webhooks, a ClickHouse cluster or Postgres, starting with a backfill and then staying at the chain head.
  • RPC from the index. An RPC endpoint per chain answers eth_getLogs from the same index, with typical reads in about 100 ms.

A team that wants to ask new questions of chain history without writing and syncing a mapping for each one can start at bedrock.turtle.xyz.

FAQ

What is a subgraph in simple terms?

A subgraph is a small, open API for a blockchain app. It watches specific smart contracts, saves what they do as structured records and lets an app read those records with GraphQL.

Is a subgraph the same as The Graph?

The Graph is the protocol and network of Indexers, Curators and Delegators that serves subgraphs. A subgraph is one API on that network, usually built for one app or dataset. The two names are often used together because The Graph introduced subgraphs.

What language are subgraphs written in?

The manifest is YAML, the schema uses the GraphQL schema language and the mappings are written in AssemblyScript, a subset of TypeScript that compiles to WebAssembly.

Do you need GRT to query a subgraph?

Not at first. Subgraph Studio's Free Plan includes 100,000 queries per month. After that, the Growth Plan charges per query, payable by credit card or with GRT on Arbitrum.

Can a subgraph index more than one chain?

A single subgraph indexes one network, though it can cover many contracts on that network. Apps that live on several chains deploy one subgraph per chain.

Is The Graph's hosted service still available?

No. The Graph retired the hosted service in 2024 after an upgrade window that closed in June 2024. Subgraphs now run on The Graph Network, on a self-hosted Graph Node or with a hosted provider.

This research was produced by the team at Turtle. Including DefiLlama, Dune Analytics, governance forum disclosures, and published retroactive analyses by Gauntlet, Blockworks Research, and OpenBlock Labs. Estimates are labeled as such throughout. For questions about methodology or data, contact the Turtle research team.

Published on November 20, 2026

Related Content

Building a liquidity program?

Talk to the team that has bootstrapped $5.5B+ in DeFi liquidity across 60+ protocols.

Talk to us