What is a subgraph? (2023 Guide)

Written by Logan Ross

Reviewed by Brady Werkheiser

Published on September 26, 20237 min read

---

Subgraphs aggregate application-specific blockchain data for quick access to full-stack developers.

Blockchains record data chronologically and without regard to specific applications. Historically, when a developer wanted to display information relevant to their smart contracts, they would be forced to search for it block by block, transaction by transaction using JSON-RPC.

Subgraphs, such as Alchemy Subgraphs, give developers an easy method for accessing onchain data in real time, and enable developers to create useful app interactions for their users.

This article explores subgraphs, including their functionality, common applications, advantages, available providers, and resources to help developers get started with using them.

What is a subgraph?

Subgraphs aggregate application-specific blockchain data for quick access to frontend developers.

Subgraph are exposed to developers via GraphQL APIs, allowing users to query the transaction data happening on their contract in real time. Subgraphs are especially beneficial for developers of complex, custom smart contracts that need to have robust frontend interfaces.

For example, to query all transactions within a single Uniswap v3 liquidity pool over the last 24 hours, Uniswap simply needs to define their schema, index the event data to create the subgraph, and then use the generated GraphQL API to query their subgraph for flexible and efficient blockchain data.

Subgraphs allow developers to filter and sort data based on their needs, letting them extract only the information important to their dapp. Subgraphs also enable more efficient data querying by precompiling and indexing data to speed up the querying process instead of requesting data directly from full nodes or archive nodes.

How does a subgraph work?

Subgraph “mappings” are scripts that direct nodes to pull relevant data from each newly discovered block according to the subgraph’s “manifest”. This new data is then added to the subgraph and made available to developers via a GraphQL call, as defined by the Subgraph’s “schema”.

To begin, we must comprehend the fundamental structure of a subgraph, its components, and how they interact with one another. 

What is the subgraph manifest?

A manifest contains information on data sources, templates, and some subgraph metadata (e.g. description, repository, etc.). The manifest defines the smart contracts indexed by a subgraph, the relevant events on the smart contracts, and how to transfer event data to entities stored and queryable by the Graph node.

What is a subgraph schema?

A schema explains how a subgraph’s data is organized and how to query it using GraphQL. The schema should define entities and the structured data for each entity.

For example, if you are creating a subgraph for real-time analytics of Uniswap v3 pools, your entity might be a pool, and the schema would define the pool's assets, name, smart contract address, fees, etc.

What is a subgraph mapping?

Mappings are AssemblyScript code that are called whenever the server finds an event specified in the manifest. Mappings define event handlers in charge of transforming the data coming from the event or call and saving it on the Graph node store.

What are popular use cases for subgraphs?

Subgraphs are frequently used for DeFi, NFT, DAOs, and various other onchain  applications.

Custom Smart Contract Indexing

Blockchain application developers that want to index data for their custom smart contracts (especially those that don't follow a standard like ERC1155 or ERC721 NFTs) are frequent creators of subgraphs. Custom indexing is also particularly important for developers building frontend user interfaces with features like search and filtering.

Decentralized Finance (DeFi)

DeFi subgraphs are commonly used in applications to index and query blockchain data such as token prices, exchange rates, liquidity, and trading volume. DeFi apps that use subgraphs can give users real-time access to up-to-date data and enable efficient trading and other financial operations.

Non-fungible Tokens (NFTs)

NFT subgraphs can be used to index and query NFT data such as ownership, provenance, and transaction history with off-chain data. This can assist NFT marketplaces and other apps in providing a smoother experience for users that are buying, selling, and trading NFTs.

Decentralized Autonomous Organizations (DAOs)

In contrast to centralized authorities, Decentralized Autonomous Organizations, or DAOs, are organizations run by distributed communities. Because the majority of DAO decision-making happens onchain, DAO subgraphs are critical for enabling members to properly vote and examine data.

Gaming​​

Real-time access to data like user account balances, game state, and in-game objects is frequently required in blockchain-based games. This data can be indexed and queried via subgraphs, allowing for more efficient and responsive gameplay and other features.

What are the benefits of building with subgraphs?

Subgraphs are a really easy paradigm for indexing blockchain data that full-stack developers can use. Write some Assemblyscript and you're good to go! For hosted solutions like Alchemy Subgraphs, it comes with a backend, so developers don't need to run a database and servers.

Here are a few other benefits of building with subgraphs: simplicity, compatibility, and resiliency.

1. Subgraph Simplicity

Subgraphs are databases of application-specific data available for querying. Using hosted subgraphs as a data backend saves developers time and overhead from having to create their own database. 

Subgraphs are defined and accessed with AssemblyScript and GraphQL respectively. These are typically familiar paradigms for full stack developers, making subgraphs accessible for new web3 developers.

2. Compatibility with Multiple Blockchains

Subgraphs have the advantage of working with the numerous EVM-compatible blockchain networks, allowing developers to get data from a number of sources. As a result, decentralized apps can be designed to run across various blockchain networks, increasing flexibility and scalability. 

While each subgraph pulls data from only one chain, developers can use similar schema and mappings to deploy subgraphs on across different supported blockchain networks with minimal engineering lift. Subgraph queries can also be cross-chain via the graph-cli or through providers that support this features.

3. Greater Security and Resiliency 

Using a decentralized indexing protocol to query subgraphs allows developers to opt into maintaining full stack decentralization for their applications. While there are performance tradeoffs between using a decentralized and a hosted version of the subgraph, having options lets developers optimize for their specific use cases.

With a decentralized indexer, an application can lessen its dependency on a single data source by executing many subgraphs from diverse providers, making it less vulnerable to attacks or downtime from a single source. Such services are provided by the Graph protocol.

Subgraphs can also be created to filter out potentially harmful data, adding an extra layer of protection to the application. An application's data infrastructure can be made more secure and resilient by operating numerous subgraphs.

What are the tradeoffs of building apps with subgraphs?

While existing subgraphs are simple to use, it can be complex to create and debug them, and they may be cost or design prohibitive

1. Subgraph Development and Debugging

To effectively use subgraphs, developers must learn a complex ecosystem and navigate subgraph debugging challenges due to lack of tooling and visibility.

To improve the subgraph developer experience, Alchemy Subgraphs powered by Satsuma, added a performance insights dashboard and other observability metrics.

Another challenge of building with subgraphs is that mappings are transpiled to web assembly, which adds difficulty to debugging subgraphs!

2. Customization Limitations

While subgraphs offer a great deal of flexibility in terms of which data is indexed and how it can be queried, customization may be limited. If a dapp has highly strict indexing or querying needs, a full-custom data indexing and transformation solution may be required.

3. Cost

Cost is an important deciding factor for application developers tasked with choosing new technology solutions. While leveraging subgraphs can make it easier and faster to query blockchain data compared to JSON-RPC, it has additive costs including paying for indexing and querying services, which can add up over time.

4. Indexing Speed

Application developers with lots of data often cite indexing speed as one of the challenges of using subgraphs. Indexing speeds will vary not only the quantity and complexity of data, but if the subgraph is self-hosted, decentralized, or hosted by a supgraph development platform like Alchemy.

Fortunately, the team building Alchemy Subgraphs have deployed optimizations to make the challenges of initial and ongoing indexing more performant compared to alternatives.

Who are the best subgraph providers?

Among the more prominent providers in the space are Alchemy Subgraphs, The Graph, Goldsky, and ChainStack.

Alchemy Subgraphs

Alchemy Subgraphs offers a turbo-charged drop-in replacement subgraph solution backed by a 99.9% uptime SLA. Web3 developers can save up to 80% of time waiting for subgraphs to sync by investing < 5 minutes to swap over their applications to Alchemy Subgraphs.

Users also benefit from improved observability into their subgraphs via advanced metrics and a Performance Insights dashboard for indexing optimization. Developers can safely and quickly rollout changes to subgraphs on Alchemy Subgraphs with its flexible multi-versioning system.

The Graph

The Graph allows developers to produce and query subsets of blockchain data in a scalable and cost-effective manner. 

Subgraph providers can utilize The Graph's tools and infrastructure to create, deploy, and maintain subgraphs, which developers can easily query using The Graph's GraphQL API. The subgraph service in The Graph is intended to be flexible and configurable, allowing developers to index and query data from any blockchain or data source.

There are three main ways to deploy subgraphs to The Graph:

1. Self-hosted

2. The Graph Hosted Service

3. Subgraph Studio

1. Self-hosted

Developers can self-host the different components that make up the subgraph ecosystem (the `graph-node` codebase) and deploy their subgraphs to this self-hosted system.

2. The Graph's Hosted Service

If developers don't want to run their own infrastructure, they can deploy their subgraphs to The Graph Hosted Service for free. This is a great option for new and small teams because it is easy, and the low reliability and slow speeds are tolerable. However, The Graph's hosted service is currently being deprecated.

3. Subgraph Studio

Developers can deploy their subgraphs to The Graph's decentralized network through the Subgraph Studio product, which involves The Graph's token. However, this deployment method does not support all the features of the hosted solution (e.g. no IPFS functionality and fewer chains are supported).

Goldsky

Goldsky lets engineers create real-time data streams for their apps while eliminating the need to manage sophisticated blockchain and data streaming infrastructure. Goldsky can index a blockchain or subgraph, convert the data to meet your requirements and stream the results in real-time to a data warehouse, webhooks, or an API.

Chainstack 

Chainstack Subgraphs is a super-fast, production-level solution for deploying your subgraphs that you can utilize without the trouble of staking, delegating, and/or rewarding subgraph indexing. You can rely on Chainstack for rapid indexing and constant data availability.

Subgraph Development Resources

The following list contains several helpful resources for developers getting started building with subgraphs:

1. The Graph Documentation

The Graph documentation is a comprehensive resource that offers developers all of the knowledge they need to start building subgraphs for decentralized apps. It offers comprehensive instructions, tutorials, and reference materials covering everything from creating a development environment to deploying and querying subgraphs.

2. Example Subgraphs

The Graph's official Github repository contains examples of subgraph implementations for indexing and querying data from blockchain networks, including Ethereum, Polygon, IPFS, and more. It provides a simple subgraph template and example code that can be customized to suit the requirements of a specific dapp.

3. Messari Standard Subgraphs

Messari's subgraph repository offers developers a variety of pre-built subgraphs for analyzing data from prominent blockchain networks like Ethereum and BNB Chain. It provides a variety of features like historical pricing data, onchain metrics, and more, making it a valuable resource for developers looking to leverage subgraphs.

Should I use subgraphs?

If you have a custom smart contract(s) that you want to monitor, building a subgraph may be a great solution for you. 

Subgraphs aggregate application-specific blockchain data for quick access to front end developers.