Building Subgraphs

Mon, 01 Jan 0001 00:00:00 +0000

Subgraph Anatomy#

A subgraph consists of three files:

subgraph.yaml — manifest listing the contracts, networks, start blocks, and event handlers.
schema.graphql — entity definitions that become your queryable data model.
src/mapping.ts — AssemblyScript handlers that transform raw events into entities.

Scaffold and Deploy#

# Install the CLI
npm install -g @graphprotocol/graph-cli

# Scaffold from an existing contract ABI
graph init --from-contract 0x1F98431c8aD98523631AE4a59f267346ea31F984 \
  --network mainnet --abi UniswapV3Factory.json my-subgraph

cd my-subgraph

# Generate AssemblyScript types from the schema
graph codegen

# Build
graph build

# Deploy to Subgraph Studio (requires auth)
graph auth --studio <DEPLOY_KEY>
graph deploy --studio my-subgraph

Manifest (`subgraph.yaml`)#

The manifest declares which contracts and events to index. A minimal example:

Querying Subgraphs

Mon, 01 Jan 0001 00:00:00 +0000

Every deployed subgraph exposes a GraphQL endpoint. You can query it from any HTTP client — no special SDK is required.

Endpoint URL#

Decentralised network queries go through the Gateway:

https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/<SUBGRAPH_ID>

API_KEY — create one at Subgraph Studio.
SUBGRAPH_ID — the deployment ID shown on Graph Explorer.

Basic Query#

Fetch recent swaps from the Uniswap V3 subgraph:

{
  swaps(first: 5, orderBy: timestamp, orderDirection: desc) {
    id
    timestamp
    pool {
      token0 { symbol }
      token1 { symbol }
    }
    amount0
    amount1
    amountUSD
  }
}

TypeScript Client#

The lightweight graphql-request library is a good default:

The Graph on Bitsy Services Wiki