Identifiers and Endpoint Aliases

Every Subgraph query names a version, directly or indirectly. Choose who moves your application to a new version, and whether that move waits until the new version is indexed. The choice decides whether a release can break your queries or briefly leave them without data.

If you want a recommendation rather than the full model, start with Choose your Subgraph setup.

Versions and indexingCopy Anchor Link

A Subgraph changes through versions. Each version is a deployment, identified by its Deployment CID: the content identifier of its manifest, schema and mappings on IPFS. Publishing a change always produces a new Deployment CID.

A deployment has no data until it is indexed. Indexing processes the chain from the deployment's start block up to the network head; how long that takes depends on the block range and the work its mappings do. Until a new version catches up, queries to it can fail, return fewer entities, or report an older block in _meta.

Who indexes a deployment depends on how you use it:

• When the deployment belongs to one of your organization's Managed Subgraphs, GraphOps keeps it indexed for you.
• Otherwise, a query is answered only if an indexer on The Graph Network is serving that deployment. Indexers choose which deployments they serve. A newly published version may not be served yet, and an older version can stop being served after its owner publishes a new one.

Identifier typesCopy Anchor Link

In the GraphOps platform, each identifier is labeled by its role. A Managed Subgraph shows its Current CID and, while one is being indexed, its Next CID. An Endpoint Alias shows its Serving CID, the deployment that answers its queries now. A Graph Network Subgraph ID is labeled Subgraph ID.

Deployment CIDCopy Anchor Link

A Deployment CID identifies one immutable Subgraph deployment. Use it to keep the code and schema version fixed. Its indexed data still changes as new blocks arrive; a CID does not freeze query results.

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>

Deployment CIDs are useful for:

• Verifying a migration against one exact deployment.
• Testing a new version while it indexes, before anything serves it to your users.
• Holding application behavior stable during a release, and recording rollback targets.

A pinned deployment only answers while something indexes it. If you rely on indexers on The Graph Network, check that the deployment is still served after its owner publishes a new version.

Graph Network Subgraph IDCopy Anchor Link

A Graph Network Subgraph ID identifies a Subgraph on The Graph Network. Its owner can upgrade it at any time by publishing a new version, and the ID then points to the new Deployment CID.

https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>

The subgraphId endpoint serves the version the ID points to now. It does not wait for that version to be indexed, and it does not consult your Managed Subgraphs:

• Right after an upgrade, queries can fail with no indexer serving the deployment, or return incomplete data while the new version catches up.
• The new version can change the schema, so queries that worked before can return GraphQL validation errors.

Use a Graph Network Subgraph ID when you want the owner's latest version and your application can tolerate both effects. For a production endpoint, use an Endpoint Alias with the Latest available version target behavior instead: it keeps serving the previous version until indexers can serve the new one.

Endpoint AliasCopy Anchor Link

An Endpoint Alias is an organization-owned name for a query endpoint. Its URL stays the same while your organization chooses its Target type:

• A Deployment CID target stays on that exact deployment until you change the target. Its code and schema are fixed; indexed data can still change.
• A Graph Network Subgraph ID target follows the versions published for that ID on The Graph Network.
• A Managed Subgraph target serves a version of a Managed Subgraph that your organization indexes.

Graph Network Subgraph ID and Managed Subgraph targets also have a Target behavior that decides which of the target's versions serves:

Latest available version moves to a new version once an indexer serving it on The Graph Network reports it healthy and close to the chain head. After it moves, it stays on that version even if indexers later fall behind. Both Graph Network Subgraph ID behaviors follow schema changes chosen by the Subgraph owner.

The Endpoint Alias name is scoped to the organization associated with the API key.

https://subgraphs.graphops.xyz/v1/alias/<ALIAS>

Target a Managed Subgraph when endpoint changes should wait for its promotion checks. Promotion requires a healthy version that meets indexing readiness checks; it does not guarantee schema compatibility. Manual upgrades can accept breaking changes, and following a Graph Network Subgraph ID authorizes them automatically. Test affected clients before enabling following or promoting a manual upgrade. Use a second Endpoint Alias with the Next version behavior as a staging endpoint for those tests. Use a Deployment CID target when your team wants to change deployments manually.

Retargeting an Endpoint Alias doesn't change your application's URL, so you can start with one Target type and change it later.

Managed Subgraph versionsCopy Anchor Link

A Graph Network Subgraph ID points to one deployment at a time; when it moves, the previous version stops being what it serves. A Managed Subgraph holds two versions instead:

• Current version serves queries.
• Next version is a candidate that GraphOps indexes alongside Current.

Next becomes Current only when it is healthy, has caught up close to the network head and is promoted. Promotion checks indexing readiness; it does not guarantee schema compatibility.

A Managed Subgraph gets its Next version in one of two ways, set by its Target type:

• With a Deployment CID target, your team stages each Next version and chooses when to promote it.
• With a Graph Network Subgraph ID target, each version the owner publishes becomes Next and is promoted automatically when it is ready, including breaking schema changes.

Two setups both follow new versions and wait until they are indexed: an Endpoint Alias with a Graph Network Subgraph ID target and the Latest available version target behavior, which waits for indexers on The Graph Network, and an Endpoint Alias with the Current version of a Managed Subgraph that follows the ID, which waits for GraphOps to index and promote it. Querying a following Managed Subgraph's Graph Network Subgraph ID through the subgraphId endpoint doesn't wait for its promotion; query through the Endpoint Alias instead. See Managed Subgraphs for the upgrade procedure.

What happens when a new version is publishedCopy Anchor Link

Suppose the owner publishes version 2 of a Subgraph you query. Each setup moves at a different time:

Validation checks the new version's manifest, such as its schema and its single network; it does not check your queries against the new schema. Every setup that moves automatically can deliver breaking schema changes chosen by the owner.

Queries are charged at the managed query rate when they resolve to one of your Managed Subgraphs' deployments, and at the standard rate otherwise. Only Managed Subgraphs accrue indexing charges. See Usage and limits.

Apply the modelCopy Anchor Link

• Give production clients an Endpoint Alias, so a change of setup never requires an application release.
• Use an Endpoint Alias with a Managed Subgraph target when queries must keep working through upgrades.
• Treat a change to an Endpoint Alias with a Deployment CID target like an application release.
• Prefer Deployment CIDs for migration tests and rollback targets.
• Choose manual Managed Subgraph upgrades when your team must test each release before promotion.
• Enable following, or target a Graph Network Subgraph ID, only when your clients can accept releases chosen by the Subgraph owner, including breaking schema changes.
• Check the X-Deployment-CID response header or _meta.deployment to see which deployment served a request.

Next stepsCopy Anchor Link