The Graph Subgraph

A The Graph Subgraph is a self-contained data indexing unit that defines which blockchain data to index, how to process it, and how to make it queryable via a GraphQL API. It consists of three core components: a subgraph manifest (subgraph.yaml) that specifies the smart contracts, events, and block ranges to monitor; a GraphQL schema (schema.graphql) that defines the shape of the queryable data; and mapping scripts (written in AssemblyScript) that translate raw blockchain events into the entities defined in the schema. This structure allows developers to create a customized, high-performance index of on-chain data without running their own nodes.

The process begins when a subgraph is deployed to a Graph Node, which scans the specified blockchain for the defined events. When a matching event is found, the node executes the corresponding mapping logic. This logic, or handler, takes the raw event data, can perform calculations or fetch additional state from the chain, and then saves the processed information as typed entities to its internal store. This transformation from low-level log data to structured entities is the core value of a subgraph, enabling efficient queries that would be prohibitively slow or complex to run directly against an Ethereum node or other blockchain client.

Subgraphs power the vast majority of decentralized applications in the Web3 ecosystem, serving as the foundational data layer for DeFi dashboards, NFT marketplaces, and analytics platforms. For example, a Uniswap subgraph indexes data for every swap, mint, and burn event across all pools, making it possible to query historical trading volumes, liquidity provider returns, or real-time token prices with a single, fast GraphQL call. By abstracting away the complexities of direct chain interaction and data processing, subgraphs allow dApp frontends to be as responsive and feature-rich as traditional web applications.

A subgraph operates by defining a manifest (subgraph.yaml) that specifies the smart contract addresses, the blockchain events to monitor, and the mapping logic to translate those events into queryable data. This manifest is compiled and deployed to a Graph Node, which begins a continuous process of indexing. The node scans the blockchain for the specified events, executes the mapping logic—written in AssemblyScript—to transform the raw event data, and stores the resulting structured data in a high-performance database. This process creates a real-time, queryable data layer that is decoupled from the blockchain's consensus mechanism, enabling fast and efficient data retrieval.

The core of a subgraph's logic is its mapping functions. These are event handlers written in a subset of TypeScript called AssemblyScript. When the Graph Node detects a specified event—such as a Transfer on an ERC-20 contract or a Swap on a decentralized exchange—it executes the corresponding mapping function. This function's job is to load or create entities (the subgraph's data model objects), update their fields based on the event data, and save them back to the store. This mapping process transforms raw, low-level log data into a structured, application-ready format, defining the entire schema of the queryable API.

Once indexed, the data is served via a GraphQL API endpoint. Developers can query this API using precise GraphQL queries to fetch exactly the data their dApp needs, such as a user's token balances, a list of recent transactions, or aggregated protocol statistics. This eliminates the need for dApps to run their own complex and resource-intensive indexing infrastructure. The decentralized network of Indexers, who stake the protocol's native GRT token, compete to serve these queries reliably and earn query fees. This separation of indexing and querying is fundamental to The Graph's architecture, creating a scalable data layer for Web3.

A subgraph in The Graph protocol is an open API that indexes and organizes blockchain data, specifically for querying NFT metadata, transaction history, and ownership records using GraphQL. It functions by defining a data schema and mapping logic that listens for specific on-chain events—such as Transfer or Mint—and processes them into queryable entities stored in a decentralized network of indexers. For NFTs, this transforms raw, scattered blockchain logs into structured information about collections, individual tokens, traits, and market activity, enabling efficient data retrieval for applications without needing to scan the entire chain.

The architecture of an NFT subgraph centers on its manifest (subgraph.yaml), which specifies the smart contracts to index, the events to watch, and the handlers that process them. Key entities typically defined include Collection, Token, Transfer, and User. When a new NFT is minted or transferred, the subgraph's mapping code written in AssemblyScript executes, creating or updating these entities in the underlying database. This process abstracts the complexity of direct blockchain interaction, allowing a dApp to simply query, for example, "all tokens owned by this address" or "the trading volume for this collection in the last 24 hours" with a single, fast GraphQL call.

For developers and analysts, subgraphs unlock powerful NFT analytics and metadata standardization. They enable features like real-time rarity scoring by indexing trait data, calculating floor prices across marketplaces, and tracking provenance through complete transfer histories. Prominent examples include the subgraphs for CryptoPunks and Bored Ape Yacht Club, which provide canonical, community-maintained datasets. By decentralizing this data layer, The Graph ensures that NFT metadata and analytics are resilient, transparent, and not reliant on a single centralized server, forming the backbone for most NFT marketplaces, galleries, and analytics dashboards in the Web3 ecosystem.