Choose your Subgraph setup

Pick a setup that keeps your queries working when a Subgraph changes. Answer three questions below, then follow the recommended setup. You can change most choices later without changing your application's URL.

Know the pieces

You need five terms to make this choice:

• A Subgraph turns blockchain data into entities you query with GraphQL. It changes over time through new versions.
• A version, or deployment, is identified by its Deployment CID, a value starting with Qm. A version has no data until it is indexed, which takes time after it is released.
• The Graph Network is where Subgraph owners publish versions under a Graph Network Subgraph ID. That ID moves to each new version as soon as the owner publishes it, indexed or not.
• A Managed Subgraph has GraphOps keep a Subgraph indexed for your organization. It prepares each new version alongside the one serving queries and switches only when the new one is ready.
• An Endpoint Alias is a query URL your organization names, such as /v1/alias/orders. You choose what it points to and can change that without changing your application.

Identifiers and Endpoint Aliases explains each piece in detail.

Answer three questions

1. Whose Subgraph is it? Someone else's, already published on The Graph Network, or your own.
2. Should GraphOps keep it indexed? A Managed Subgraph has GraphOps index it for your organization and prepare each new version before your application moves, with indexing charges. Without one, indexers on The Graph Network serve it at the standard query rate, while an indexer serves the version you query. Managed indexing is available only on its supported networks.
3. When a new version appears, what should happen?
   • Your application moves to it automatically, but only once it is indexed.
   • Your team reviews and tests each version before your application moves.
   • Your application moves to it once indexers on The Graph Network serve it.
   • Your application stays on one version until you change it.

Setups with a Managed Subgraph need an Owner or Developer role, available credits, room in your plan and a deployment on a supported network. See Start indexing for the full requirements.

If you are an Owner or Developer, the platform can ask these questions for you. Open Managed Subgraphs and choose Set up a Subgraph, or choose it from the actions menu while you explore a Subgraph. It asks the same three questions, each linked to the part of this guide that explains it, and offers only the choices that apply to your Subgraph and its network. It then shows what the setup will create, what it costs and the query URL your application will use, and creates it. The page address records your answers, so you can share it or reload it without starting over.

Follow the latest version

Best when your application should follow the owner's newest version without indexing charges.

1. Find the Subgraph in Discover Subgraphs.
2. Create an Endpoint Alias with a Graph Network Subgraph ID target and the Latest available version target behavior, and use its URL in your application.

When the owner publishes a new version, your Endpoint Alias keeps serving the previous version until an indexer on The Graph Network serves the new one healthy and close to the chain head, then moves to it. A schema change from the owner still reaches your application with the new version. Queries use the standard rate, with no indexing charges.

The Graph Network Subgraph ID endpoint from Get query endpoint, and an Endpoint Alias with the Latest published version target behavior, move as soon as the owner publishes instead. Until indexers serve the new version, queries can fail or return incomplete data.

If you start from a Deployment CID instead, the endpoint stays on that exact version until you change it, and answers only while an indexer on The Graph Network serves that version.

Follow the owner's versions safely

Best for production applications that should stay current without an indexing gap.

1. Create a Managed Subgraph with a Graph Network Subgraph ID target.
2. Create an Endpoint Alias with a Managed Subgraph target and the Current version target behavior, and use its URL in your application.

GraphOps indexes each new version as Next while the current one keeps serving, then promotes it when it is ready. Your Endpoint Alias moves at promotion. Promotion doesn't wait for your approval, so a breaking schema change from the owner still reaches your application; watch the Subgraph's releases and test your queries against the Next version.

The Managed Subgraph accrues indexing charges, for both versions during an upgrade, and uses one of your plan's Managed Subgraph slots. Queries use the managed rate.

Approve each upgrade

Best for production applications that must not change without testing.

1. Create a Managed Subgraph with a Deployment CID target, using the version you have tested.
2. Create an Endpoint Alias with a Managed Subgraph target, and use its URL in your application.
3. When the owner publishes a version you want, choose Start upgrade with its Deployment CID, test it while it indexes, and choose Promote version.

Nothing changes until you promote, and GraphOps keeps your version indexed even if indexers on The Graph Network stop serving it. Charges match the previous setup.

Without managed indexing, an Endpoint Alias with a Deployment CID target also waits for you, at no indexing cost. It depends on indexers on The Graph Network continuing to serve that version, and its move to a new version doesn't wait for indexing, so test the new Deployment CID before you change the target.

Develop and release your own Subgraph

Best while you build a Subgraph and iterate through many versions.

1. Deploy your Subgraph with Graph CLI and create a Managed Subgraph with a Deployment CID target from its Deployment CID.
2. Create a production Endpoint Alias with a Managed Subgraph target and the Current version target behavior. Optionally, create a staging Endpoint Alias on the same Managed Subgraph with the Next version target behavior; Set up a Subgraph can create both.
3. Stage each new version as Next, query it through the staging Endpoint Alias or its Deployment CID while it indexes, and promote it when you are ready to release.

Until you promote, your production URL keeps serving the current version. Each version you stage indexes from its start block and accrues indexing charges while it is staged. Develop and release a Subgraph walks through iterating, releasing and rolling back.

If managed indexing doesn't support your Subgraph's network, publish it on The Graph Network and pin a tested version with an Endpoint Alias, as in Approve each upgrade.

Release by publishing

Best when your team already publishes on The Graph Network and wants that publication to be the release.

1. Create a Managed Subgraph with a Graph Network Subgraph ID target for your Subgraph's ID.
2. Create an Endpoint Alias with a Managed Subgraph target for your application.

Each version you publish is indexed and promoted automatically once it is ready, so test it before you publish. Develop and release a Subgraph shows one way to do that.

Compare the setups

Every setup that moves automatically can deliver breaking schema changes chosen by the Subgraph owner. Current prices are on Usage and limits.

Change your setup later

Point your application at an Endpoint Alias from the start, and you can move between setups without an application release:

• Retarget the Endpoint Alias with Change target.
• Switch a Managed Subgraph between approving and following versions with Change target type.

Next steps