Skip to content

Deploy your own Subgraph

Take your Subgraph project to an indexed Managed Subgraph, with one GraphOps CLI command or with Graph CLI and GraphOps Platform.

Get the Subgraph you built indexed by GraphOps and serving queries, without running a Graph Node. You build with the standard Graph CLI either way. Then either the GraphOps CLI creates the Managed Subgraph for you, or you give its Deployment CID to GraphOps Platform.

Choose how to deploy

If youUseSection
Work in a terminal or CI, and want build, upload and setup in one commandGraphOps CLIDeploy with the GraphOps CLI
Prefer to set up the Subgraph in the browser, or can't install another CLIGraph CLI and GraphOps PlatformDeploy from GraphOps Platform
Already have a Deployment CID from another build or pipelineGraphOps CLI with --cidDeploy a build made elsewhere
Publish the Subgraph on The Graph Network, or want to index someone else'sGraphOps PlatformConnect an existing Subgraph

Both paths end in the same place: a Managed Subgraph that GraphOps keeps indexed, which you then release new versions of as Develop and release a Subgraph describes.

You build with Graph CLI and upload the build to IPFS. The Deployment CID it prints is what you query, give to a Managed Subgraph, or set as an Endpoint Alias target.

Prerequisites

  • A Subgraph project with subgraph.yaml, for example one created with graph init, and Graph CLI in its dependencies (npm install --save-dev @graphprotocol/graph-cli).
  • A GraphOps organization with Subgraphs access, and the owner or developer role.
  • A monthly plan with room for another Managed Subgraph. Managed indexing accrues charges while a version is indexed, whether or not it receives queries; see Plan indexing costs.
  • An API key that includes Subgraphs, to query the result.

Deploy with the GraphOps CLI

graphops subgraphs deploy runs your project's Graph CLI to build and upload the Subgraph, then creates the Managed Subgraph. You need the GraphOps CLI, signed in to your organization.

Deploy with --create

Run the deploy from your project. The name you pass names the Managed Subgraph, and Graph CLI uses it as the Subgraph name. --create is required the first time, because indexing and its charges start when the Managed Subgraph is created. Without it, the CLI stops before building when no Managed Subgraph has that name.

CLI · GraphOps CLI

# Run from your Subgraph project. Builds with your graph-cli and creates the Managed Subgraph.
graphops subgraphs deploy my-subgraph --create

Graph CLI's build output appears as usual. Graph CLI deploys through a local GraphOps bridge, so the Graph node address it prints is on 127.0.0.1. The CLI then prints the Deployment CID, the network, the query URL of the Current version and a link to the Managed Subgraph in GraphOps Platform.

A Managed Subgraph indexes one network: to index the same Subgraph on another network, deploy it under another name, for example with the network in the name. When you pass Graph CLI's --network, the CLI checks it against the Managed Subgraph's network before building.

Wait for it to sync

CLI · GraphOps CLI

# Wait until the current version has caught up with the network (default timeout 30m).
graphops subgraphs wait my-subgraph --for synced
graphops subgraphs status my-subgraph

--for synced waits until the Current version has caught up with the network. The wait gives up after 30 minutes by default, exiting with code 6; indexing continues, so wait again or check graphops subgraphs status. The wait stops at once with code 5 if the deployment reports a failure, or if the Managed Subgraph is suspended or being deleted. When the organization's credits run out, the error code is credits_exhausted: add credits to resume indexing.

Give applications a stable URL

The deploy and graphops subgraphs status print the query URL of the Current version's Deployment CID, which stops working once you promote a newer version. Give applications an Endpoint Alias instead, which moves to each version you promote:

CLI · GraphOps CLI

# A query URL that follows each version you promote.
graphops subgraphs endpoint-aliases create my-subgraph-prod --managed-subgraph my-subgraph

Query it with an API key that includes Subgraphs. graphops api-keys create --store creates one and stores it for graphops exec, as Developer workflow shows. See Query a Subgraph.

Deploy from GraphOps Platform

Build and upload with Graph CLI, then create the Managed Subgraph in the browser from the Deployment CID that Graph CLI prints.

Generate types

CLI · Graph CLI

graph codegen

Build the Subgraph

CLI · Graph CLI

graph build

Upload the build

Build again with --ipfs to upload the manifest, schema, ABIs and mappings to IPFS, where GraphOps reads them.

CLI · Graph CLI

graph build --ipfs https://api.thegraph.com/ipfs/api/v0

Graph CLI prints Build completed: followed by the Deployment CID. Record it with the release. A Deployment CID identifies this exact version, and it is all a Managed Subgraph needs.

Use the Deployment CID in GraphOps

Start Set up a Subgraph, answer My own Subgraph, and paste the Deployment CID.

Set up a Subgraph(opens in a new tab)

The setup then asks whether GraphOps should keep it indexed and creates the Managed Subgraph and Endpoint Alias your answers need.

Check the deployment

Prerequisites

  1. Set GRAPHOPS_API_KEY to your GraphOps API key.

  2. Replace <DEPLOYMENT_CID> with the Deployment CID to query.

CLI · curl

curl --fail-with-body --silent --show-error "https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>" \
  -H "Authorization: Bearer ${GRAPHOPS_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "query DeploymentStatus { _meta { deployment block { number hash } hasIndexingErrors } }"
  }'

Output

{  "data": {    "_meta": {      "deployment": "QmTZ8ejXJxRo7vDBS4uwqBeGoxLSWbhaA7oXa1RvxunLy7",Should match the CID from graph deploy      "block": {        "number": 26427421,Rises as the new deployment indexes        "hash": "0xe6bbe9a916406b49a60992587fcb445601905716e360a01885885a3401442f83"      },      "hasIndexingErrors": falseMust stay false before you release    }  }}

_meta.block.number rises while the new deployment indexes. Query your application's fields only after it reaches the blocks your application needs.

Deploy a build made elsewhere

--cid works for any Deployment CID, so you can build in one place and release from another. For example, run graph build --ipfs in a CI build job, then graphops subgraphs deploy my-subgraph --cid <Deployment CID> --create in a release job. The outcome, the flags and the permissions are the same as when the CLI builds.

To follow the versions published to a Graph Network Subgraph ID instead, run graphops subgraphs create my-subgraph --subgraph-id <Graph Network Subgraph ID>. See Connect an existing Subgraph to choose between them.

Release new versions

Each later deploy of the same Managed Subgraph stages the new build as its Next version, while the Current version keeps serving. Your Endpoint Alias moves only when you promote it. Develop and release a Subgraph covers testing a version, promoting it, rolling back and releasing from CI, from the GraphOps CLI or GraphOps Platform.

  • Keep each released Deployment CID as a rollback target.
  • Check _meta.hasIndexingErrors after deploying and after each release.

Next steps

Last updated