Skip to content

Katara subgraph vs deployment #955

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Katara subgraph vs deployment #955

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
827136b
Initial draft
MichaelMacaulay May 16, 2025
82dc906
Fix
MichaelMacaulay May 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion website/src/pages/en/subgraphs/querying/subgraph-id-vs-deployment-id.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,15 @@
title: Subgraph ID vs Deployment ID
---

Managing and accessing Subgraphs relies on two distinct identification systems: Subgraph IDs and Deployment IDs.

A Subgraph is identified by a Subgraph ID, and each version of the Subgraph is identified by a Deployment ID.

When querying a Subgraph, either ID can be used, though it is generally suggested that the Deployment ID is used due to its ability to specify a specific version of a Subgraph.

Here are some key differences between the two IDs: ![](/img/subgraph-id-vs-deployment-id.png)
Both identifiers are accessible in [Subgraph Studio](https://thegraph.com/studio/):

![Highlights of where to find the Subgraph ID and Deployment ID](/img/subgraph-id-vs-deployment-id.png)

## Deployment ID

Expand All @@ -18,10 +22,33 @@ Example endpoint that uses Deployment ID:

`https://gateway-arbitrum.network.thegraph.com/api/[api-key]/deployments/id/QmfYaVdSSekUeK6expfm47tP8adg3NNdEGnVExqswsSwaB`

Using Deployment IDs for queries offers precise version control but comes with specific implications:

- Advantages: Complete control over which version you're querying, ensuring consistent results
- Challenges: Requires manual updates to query code when new Subgraph versions are published
- Use case: Ideal for production environments where stability and predictability are crucial

## Subgraph ID

The Subgraph ID is a unique identifier for a Subgraph. It remains constant across all versions of a Subgraph. It is recommended to use the Subgraph ID to query the latest version of a Subgraph, although there are some caveats.

Be aware that querying using Subgraph ID may result in queries being responded to by an older version of the Subgraph due to the new version needing time to sync. Also, new versions could introduce breaking schema changes.

Example endpoint that uses Subgraph ID: `https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/FL3ePDCBbShPvfRJTaSCNnehiqxsPHzpLud6CpbHoeKW`

Using Subgraph IDs comes with important considerations:

- Benefits: Automatically queries the latest version, reducing maintenance overhead
- Limitations: May encounter version synchronization delays or breaking schema changes
- Use case: Better suited for development environments or when staying current is more important than version stability

## Deployment ID vs Subgraph ID

Here are the key differences between the two IDs:

| Consideration | Deployment ID | Subgraph ID |
| ----------------------- | --------------------- | --------------- |
| Version Pinning | Specific version | Always latest |
| Maintenance Effort | High (manual updates) | Low (automatic) |
| Environment Suitability | Production | Development |
| Sync Status Awareness | Not required | Critical |