Every Subgraph query names a version, directly or indirectly, through the identifier in its URL. Pick the identifier by who should be able to move your application to a new version: no one, the Subgraph's owner, or your organization.
If you want a recommendation rather than the full model, start with Choose your Subgraph setup.
Compare the identifiers
| Identifier | Endpoint segment | What it serves | Who changes it |
|---|---|---|---|
| Deployment CID | deploymentCID/<DEPLOYMENT_CID> | One exact deployment. | No one. The deployment is immutable. |
| Graph Network Subgraph ID | subgraphId/<SUBGRAPH_ID> | The version currently published for that ID. | The Subgraph owner, by publishing on The Graph Network. |
| Endpoint Alias | alias/<ALIAS> | Whatever its Target type selects. | Your organization, in the GraphOps platform. |
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.
Whichever identifier you query, the data comes from a deployment that someone indexes. A deployment that nothing indexes answers no queries. Versions explains who indexes a deployment and what happens while a new one catches up.
Deployment CID
A Deployment CID identifies one immutable Subgraph deployment: the content identifier of its manifest, schema and mappings on IPFS. 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.
Reference
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 ID
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.
Reference
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 Alias
An Endpoint Alias is an organization-owned name for a query endpoint. Its URL stays the same while your organization chooses what it serves: a Deployment CID, a Graph Network Subgraph ID or a Managed Subgraph. The name is scoped to the organization of the API key that queries it.
Reference
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>
Give production clients an Endpoint Alias, so a change of setup never requires an application release. Endpoint Aliases explains each target type and behavior, and when each one moves to a new version.
Apply the model
- Give production clients an Endpoint Alias.
- Prefer Deployment CIDs for migration tests and rollback targets.
- Query a Graph Network Subgraph ID directly only when your clients can accept releases chosen by the Subgraph owner, including breaking schema changes, before they are indexed.
- Check the
X-Deployment-CIDresponse header or_meta.deploymentto see which deployment served a request.
Next steps
Last updated