Aggregate Data Using Subgraph Composition

Leverage Subgraph composition to speed up development time. Create a base Subgraph with essential data, then build additional Subgraphs on top of it.

Optimize your Subgraph by merging data from independent, source Subgraphs into a single composable Subgraph to enhance data aggregation.

Introduction

Composable Subgraphs enable you to combine multiple Subgraphs’ data sources into a new Subgraph, facilitating faster and more flexible Subgraph development. Subgraph composition empowers you to create and maintain smaller, focused Subgraphs that collectively form a larger, interconnected dataset.

Benefits of Composition

Subgraph composition is a powerful feature for scaling, allowing you to:

• Reuse, mix, and combine existing data
• Streamline development and queries
• Use multiple data sources (up to five source Subgraphs)
• Speed up your Subgraph’s syncing speed
• Handle errors and optimize the resync

Architecture Overview

The setup for this example involves two Subgraphs:

1. Source Subgraph: Tracks event data as entities.
2. Dependent Subgraph: Uses the source Subgraph as a data source.

You can find these in the source and dependent directories.

• The source Subgraph is a basic event-tracking Subgraph that records events emitted by relevant contracts.
• The dependent Subgraph references the source Subgraph as a data source, using the entities from the source as triggers.

While the source Subgraph is a standard Subgraph, the dependent Subgraph uses the Subgraph composition feature.

Prerequisites

Source Subgraphs

• All Subgraphs need to be published with a specVersion 1.3.0 or later (Use the latest graph-cli version to be able to deploy composable Subgraphs).
• See notes here: https://github.com/graphprotocol/graph-node/releases/tag/v0.37.0⁠
• Immutable entities only: All Subgraphs must have immutable entities when the Subgraph is deployed.
• Pruning can be used in the source Subgraphs, but only entities that are immutable can be composed on top of.
• Source Subgraphs cannot use grafting on top of existing entities.
• Aggregated entities can be used in composition, but entities that are composed from them cannot performed additional aggregations directly.

Composed Subgraphs

• You can only compose up to a maximum of 5 source Subgraphs.
• Composed Subgraphs can only use datasources from the same chain.
• Nested composition is not yet supported: Composing on top of another composed Subgraph isn’t allowed at this time.
• Aggregated entities can be used in composition, but the composed entities on them cannot also use aggregations directly.
• Developers cannot compose an onchain datasource with a Subgraph datasource (i.e. you can’t do normal event handlers and call handlers and block handlers in a composed Subgraph).

Additionally, you can explore the example-composable-subgraph⁠ repository for a working implementation of composable Subgraphs

Get Started

The following guide provides examples for defining 3 source Subgraphs to create one powerful composed Subgraph.

Specifics

• To keep this example simple, all source Subgraphs use only block handlers. However, in a real environment, each source Subgraph will use data from different smart contracts.
• The examples below show how to import and extend the schema of another Subgraph to enhance its functionality.
• Each source Subgraph is optimized with a specific entity.
• All the commands listed install the necessary dependencies, generate code based on the GraphQL schema, build the Subgraph, and deploy it to your local Graph Node instance.

Step 1. Deploy Block Time Source Subgraph

This first source Subgraph calculates the block time for each block.

• It imports schemas from other Subgraphs and adds a block entity with a timestamp field, representing the time each block was mined.
• It listens to time-related blockchain events (e.g., block timestamps) and processes this data to update the Subgraph’s entities accordingly.

To deploy this Subgraph locally, run the following commands:

1npm install2npm run codegen3npm run build4npm run create-local5npm run deploy-local

Step 2. Deploy Block Cost Source Subgraph

This second source Subgraph indexes the cost of each block.

Key Functions

• It imports schemas from other Subgraphs and adds a block entity with cost-related fields.
• It listens to blockchain events related to costs (e.g. gas fees, transaction costs) and processes this data to update the Subgraph’s entities accordingly.

To deploy this Subgraph locally, run the same commands as above.

Step 3. Define Block Size in Source Subgraph

This third source Subgraph indexes the size of each block. To deploy this Subgraph locally, run the same commands as above.

Key Functions

• It imports existing schemas from other Subgraphs and adds a block entity with a size field representing each block’s size.
• It listens to blockchain events related to block sizes (e.g., storage or volume) and processes this data to update the Subgraph’s entities accordingly.

Step 4. Combine Into Block Stats Subgraph

This composed Subgraph combines and aggregates the information from the source Subgraphs above, providing a unified view of block statistics. To deploy this Subgraph locally, run the same commands as above.

Key Functions

• It provides a consolidated data model that encompasses all relevant block metrics.
• It combines data from 3 source Subgraphs, and provides a comprehensive view of block statistics, enabling more complex queries and analyses.

Key Takeaways

• This powerful tool will scale your Subgraph development and allow you to combine multiple Subgraphs.
• The setup includes the deployment of 3 source Subgraphs and one final deployment of the composed Subgraph.
• This feature unlocks scalability, simplifying both development and maintenance efficiency.

Additional Resources

• Check out all the code for this example in this GitHub repo⁠.
• To add advanced features to your Subgraph, check out Subgraph advanced features.
• To learn more about aggregations, check out Timeseries and Aggregations.