Docs
Search⌘ K
  • Home
  • About The Graph
  • Supported Networks
  • Protocol Contracts
  • AI Tooling
  • Subgraphs
    • Substreams
      • Indexer Software
        • Gateway Software
          • Data Services
            • Resources
              Subgraphs > Guides & Best Practices

              5 minutes

              Combine Data with Subgraph Composition

              Subgraph composition lets you build a Subgraph on top of other Subgraphs. Instead of one large Subgraph that indexes everything, you maintain small, focused source Subgraphs, then combine their data into a single composed Subgraph for your app. Each source syncs and resyncs on its own, which speeds up development and recovery.

              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 the Graph Node v0.37.0 release notes⁠.
              • 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 perform 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.
              • You cannot combine an onchain data source with a Subgraph data source (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 steps define three source Subgraphs and combine them into one 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.

              Note:

              • Any change to a source Subgraph will likely generate a new deployment ID.
              • Be sure to update the deployment ID in the data source address of the Subgraph manifest to take advantage of the latest changes.
              • All source Subgraphs should be deployed before the composed Subgraph is deployed.

              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

              • Composition lets you combine up to five source Subgraphs on the same chain into one Subgraph.
              • The setup deploys three source Subgraphs first, then the composed Subgraph.
              • Small, focused source Subgraphs are easier to develop, maintain, and resync than one large Subgraph.

              Learn More

              • Check out all the code for this example in this GitHub repo⁠.
              • To add advanced features to your Subgraph, check out Advanced Subgraph Features.
              • To learn more about aggregations, check out Timeseries and Aggregations.
              • Guides & Best Practices overview: the full checklist and how this page fits with the rest of the section.
              ⁠Edit on GitHub⁠

              GraftingTransfer to The Graph
              On this page
              • Benefits of Composition
              • Architecture Overview
              • Prerequisites
              • Source Subgraphs
              • Composed Subgraphs
              • Get Started
              • Specifics
              • Step 1. Deploy Block Time Source Subgraph
              • Step 2. Deploy Block Cost Source Subgraph
              • Step 3. Define Block Size in Source Subgraph
              • Step 4. Combine Into Block Stats Subgraph
              • Key Takeaways
              • Learn More
              The GraphStatusTestnetBrand AssetsForumSecurityPrivacy PolicyTerms of Service