What are tags?
- Tags let you version and manage your subgraph endpoints without changing your URL.
- They act as pointers that direct your GraphQL endpoint to a specific subgraph deployment.
subgraph-name + version
For example: mainnet-usdc/v0.0.1
This tag is composed of:
- Name - The subgraph name (
mainnet-usdc) - Version - The deployed version (
v0.0.1)
Tags always point to a specific subgraph deployment. When you deploy a subgraph, a tag is created automatically based on the name and version.
How tags work
- Tags let you update or replace a subgraph deployment without breaking your existing endpoint.
- This allows you to test, sync, and deploy new versions without downtime or front-end changes.
Example workflow
- You deploy
mainnet-usdc v0.0.1and tag it asprod, giving you this endpoint:
- You deploy an updated version of
mainnet-usdc v0.0.1for testing and call it:
- Name:
mainnet-usdc - Version:
v2.0
- Once it’s synced and ready, you reassign the
prodtag to themainnet-usdc v2.0subgraph.
/mainnet-usdc/prod), but now it serves data from the new version without downtime or code changes.
Tags can only be reassigned between deployments that share the same subgraph name. If you change the name, the tag will no longer apply.
When to use tags
- Product stability: Swap new versions in real-time without downtime.
- Testing environments: Route traffic between subgraphs used in
staging, andprod. - Version management: Keep a single stable URL across multiple subgraph updates.
Tags are ideal when you need continuous data delivery while testing or upgrading. They’re not needed for one-off or experimental subgraphs.
How to create tags
Step 1: Access 0xGraph and press the >_ icon
Step 2: Click on the Tags tab
Step 3: Generate a tag
We created a new tag calledtesting
Step 4: Query using the tag
