# Versions

Source: https://docs.graphops.xyz/subgraphs/concepts/versions

A release can break your queries or briefly leave them without data. Whether it does depends on
when your application moves to the new version, and whether that move waits until the new version
is indexed. This page explains the model behind that choice.

## Versions and indexing

A Subgraph changes through versions. Each version is a deployment, identified by its
Deployment CID. Publishing a change always produces a new Deployment CID.
[Identifier types](./identifier-types) compares the ways a query can name a version.

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.

## 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.

An Endpoint Alias with a Managed Subgraph target follows its Current or Next
version, so your application's URL stays the same through each promotion. 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.

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.

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

* 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.
* 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.

## Next steps

* [Develop and release a Subgraph](../guides/develop-and-release): Test each version, then promote it behind a stable URL.
* [Endpoint Aliases](../endpoint-aliases): Choose what an Endpoint Alias follows.
* [Managed Subgraphs](../managed-subgraphs): Run indexing and control promotions for a Subgraph.