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 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 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.
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
Last updated