# Identifiers and Endpoint Aliases Source: https://docs.graphops.xyz/subgraphs/concepts/identifiers-and-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](../choose-a-setup). ## Versions and indexing 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 types | Identifier | Endpoint segment | What it serves | Who changes it | | ------------------------- | -------------------------------- | -------------------------------------------- | ------------------------------------------------------- | | Deployment CID | `deploymentCID/` | One exact deployment. | No one; the deployment is immutable. | | Graph Network Subgraph ID | `subgraphId/` | The version currently published for that ID. | The Subgraph owner, by publishing on The Graph Network. | | Endpoint 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**. ## Deployment CID 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. ```text https://subgraphs.graphops.xyz/v1/deploymentCID/ ``` 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. ```text https://subgraphs.graphops.xyz/v1/subgraphId/ ``` 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](../troubleshooting#subgraph-unavailable-no-indexer-is-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 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: | Target type | Target behavior | Serves | | ------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Graph Network Subgraph ID | Latest available version | The newest published version that indexers on The Graph Network can serve. While a new version is still being indexed, the previous version keeps serving. | | Graph Network Subgraph ID | Latest published version | Each new version as soon as its owner publishes it, even before indexers can serve it. | | Managed Subgraph | Current version | The serving Current version. It moves when a ready Next version is promoted, through a manual upgrade or automatic following. | | Managed Subgraph | Next version | The Next version while it's being indexed, including partially indexed data. Without a Next version that can serve, it falls back to the Current version. | 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. ```text https://subgraphs.graphops.xyz/v1/alias/ ``` _An Endpoint Alias keeps one URL while your organization chooses its target and target behavior. A Deployment CID target never moves on its own; a Managed Subgraph target serves its Current or Next version; a Graph Network Subgraph ID target follows the network._ - Deployment CID: Stays on one deployment until you change the target. - Managed Subgraph: Current version moves when a ready Next version is promoted; Next version serves the version being indexed. - Graph Network Subgraph ID: Latest available version moves once indexers serve a new publication; Latest published version moves at once. 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 versions 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](../managed-subgraphs) for the upgrade procedure. ## What happens when a new version is published Suppose the owner publishes version 2 of a Subgraph you query. Each setup moves at a different time: | Setup | When it serves version 2 | While version 2 indexes | If version 2 is invalid | | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------- | | `deploymentCID` endpoint, or Endpoint Alias with a Deployment CID target | When your team changes the CID or target. | Keeps serving version 1 while it is still indexed. | Unaffected. | | `subgraphId` endpoint | Immediately. | Can fail or return incomplete data. | Points to it anyway. | | Endpoint Alias with a Graph Network Subgraph ID target, Latest published version | Shortly after it is validated. | Can fail or return incomplete data. | Keeps version 1 and shows a tracking error. | | Endpoint Alias with a Graph Network Subgraph ID target, Latest available version | Once an indexer on The Graph Network serves it healthy and close to the chain head. | Keeps serving version 1. | Keeps version 1 and shows a tracking error. | | Endpoint Alias with the Current version of a Managed Subgraph that follows the ID | After version 2 is ready and promoted. | Keeps serving version 1. | Keeps version 1 and shows a tracking error. | | Endpoint Alias with the Current version of a Managed Subgraph with a Deployment CID target | After your team stages, tests and promotes version 2. | Keeps serving version 1. | Staging reports the problem. | | Endpoint Alias with the Next version of either Managed Subgraph | As soon as version 2 is staged and can serve queries, while it is still indexing. | Serves version 2's partially indexed data. | Falls back to version 1. | 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](../usage-and-limits). ## Apply the model * 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](../api#response-headers) or `_meta.deployment` to see which deployment served a request. ## Next steps * [Choose your Subgraph setup](../choose-a-setup): Pick a setup for your application from a few questions. * [Manage Endpoint Aliases](../guides/manage-aliases): Create an Endpoint Alias and see when each target type moves. * [Managed Subgraphs](../managed-subgraphs): Run indexing and control promotions for a Subgraph.