Skip to content

Identifier types

Choose between a Deployment CID, a Graph Network Subgraph ID and an Endpoint Alias by what each one serves and who can change it.

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

IdentifierEndpoint segmentWhat it servesWho changes it
Deployment CIDdeploymentCID/<DEPLOYMENT_CID>One exact deployment.No one. The deployment is immutable.
Graph Network Subgraph IDsubgraphId/<SUBGRAPH_ID>The version currently published for that ID.The Subgraph owner, by publishing on The Graph Network.
Endpoint Aliasalias/<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-CID response header or _meta.deployment to see which deployment served a request.

Next steps

Last updated