Overview
Graph Node maintains metadata across multiple database tables to track subgraphs, their deployments, and sync state. This metadata is distributed between the primary database and sharded databases to optimize for both consistency and performance.Most metadata tables are maintained in the primary shard but are periodically copied to other shards to ensure query availability even when the primary is down.
Mapping Subgraph Names to Deployments
subgraphs.subgraph
List of all known subgraph names. Maintained in the primary, with background jobs periodically copying the table to all other shards for query resilience.Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
id | text! | primary key, UUID |
name | text! | user-chosen name |
current_version | text | subgraph_version.id for current version |
pending_version | text | subgraph_version.id for pending version |
created_at | numeric! | UNIX timestamp |
vid | int8! | unused |
block_range | int4range! | unused |
id is used by the hosted explorer to reference the subgraph.
subgraphs.subgraph_version
Mapping of subgraph names to IPFS hashes. Also maintained in the primary with periodic copies to other shards.Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
id | text! | primary key, UUID |
subgraph | text! | subgraph.id |
deployment | text! | IPFS hash of deployment |
created_at | numeric | UNIX timestamp |
vid | int8! | unused |
block_range | int4range! | unused |
Deployment Management
public.deployment_schemas
Directory of all deployments. Maintained in the primary with background job copies to other shards.Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
id | int4! | primary key |
subgraph | text! | IPFS hash of deployment |
name | text! | name of sgdNNN schema |
version | int4! | version of data layout in sgdNNN |
shard | text! | database shard holding data |
network | text! | network/chain used |
active | boolean! | whether to query this copy of the deployment |
created_at | timestamptz! |
There can be multiple copies of the same deployment, but at most one per shard. The
active flag indicates which copy will be used for queries. Graph Node ensures exactly one active copy exists for each IPFS hash.subgraphs.head
Details about a deployment that change on every block. Maintained in the shard alongside the deployment’s data insgdNNN.
Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
id | integer! | primary key, same as deployment_schemas.id |
block_hash | bytea | current subgraph head |
block_number | numeric | |
entity_count | numeric! | total number of entities |
firehose_cursor | text |
The head block pointer (
block_number and block_hash) represents the latest fully processed block. It remains null until the deployment processes its first block. For grafted or copied deployments, the head stays null until the graft/copy completes, which can take considerable time.subgraphs.deployment
Tracks sync progress and deployment details. Maintained in the shard alongside the deployment’s data.Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
id | integer! | primary key, same as deployment_schemas.id |
subgraph | text! | IPFS hash |
earliest_block_number | integer! | earliest block for which we have data |
health | health! | |
failed | boolean! | |
fatal_error | text | |
non_fatal_errors | text[] | |
graft_base | text | IPFS hash of graft base |
graft_block_hash | bytea | graft block |
graft_block_number | numeric | |
reorg_count | integer! | |
current_reorg_depth | integer! | |
max_reorg_depth | integer! | |
last_healthy_ethereum_block_hash | bytea | |
last_healthy_ethereum_block_number | numeric | |
debug_fork | text | |
synced_at | timestamptz | time when deployment first reach chain head |
synced_at_block_number | integer | block number where deployment first reach chain head |
reorg_count, current_reorg_depth, max_reorg_depth) are set during indexing to determine whether a reorg happened during query execution and if it could have affected the query results.
subgraphs.subgraph_manifest
Stores deployment details that rarely change. Maintained in the shard alongside deployment data.Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
id | integer! | primary key, same as deployment_schemas.id |
spec_version | text! | |
description | text | |
repository | text | |
schema | text! | GraphQL schema |
features | text[]! | |
graph_node_version_id | integer | |
use_bytea_prefix | boolean! | |
start_block_hash | bytea | Parent of the smallest start block from the manifest |
start_block_number | int4 | |
on_sync | text | Additional behavior when deployment becomes synced |
history_blocks | int4! | How many blocks of history to keep |
Additional Metadata Tables
subgraphs.subgraph_deployment_assignment
Tracks which index node is indexing each deployment. Maintained in the primary with periodic copies to other shards.Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
| id | int4! | primary key, ref to deployment_schemas.id |
| node_id | text! | name of index node |
This table could simply be a column on
deployment_schemas.subgraphs.dynamic_ethereum_contract_data_source
Stores dynamic data sources for all subgraphs.This table will soon be moved into each subgraph’s namespace (
sgdNNN).subgraphs.subgraph_error
Stores details about errors encountered during indexing.Deployment Copying
The following tables track deployment copying progress:active_copies(in primary)subgraphs.copy_statesubgraphs.copy_table_state
subgraphs.table_stats
Stores information about which tables should have the ‘account-like’ optimization enabled for query generation.subgraphs.subgraph_features
Details about features used by deployments. Maintained in the primary.Table Schema
Table Schema
| Column | Type | Use |
|---|---|---|
id | text! | primary key |
spec_version | text! | |
api_version | text | |
features | text[]! | |
data_sources | text[]! | |
handlers | text[]! |
Metadata Distribution Strategy
- Critical routing information is available on all shards
- Queries can be served even when the primary shard is unavailable
- Frequently changing data stays close to the deployment data
- Background jobs keep replicated data synchronized