Supergraph

The Supergraph is the architectural backbone of Federation, it's an artifact produced by the composition process, and intended to be the recipe, or control-plane, for running your GraphQL router.

To run Hive Router, you'll need a Supergraph and the subgraphs running (see Probes page for additional information about Router health state and the relation to the Supergraph).

The Router will read the Supergraph and will use it for query planning and response construction.

Loading the Supergraph

From Hive Console

To load the Supergraph from Hive Console, the official Hive Router schema-registry, start by creating a project, and follow with pushing subgraph schema and have a valid composition artifact (Supergraph) published to Hive CDN.

Once you have a valid Supergraph published to Hive CDN, gather the following information from Hive Console's dashboard:

• Hive CDN Endpoint: under your target's page, click on Connect to CDN button to grab your endpoint.
• Hive CDN API Key: a secret that allow you to access Hive CDN and fetch your API key.

Once you have both, configure Hive Router to use the supergraph configuration with source: hive field:

supergraph:
  source: hive
  endpoint: https://cdn.graphql-hive.com/artifacts/v1/... # Use your Hive CDN endpoint here
  key: hvABCD # Use your Hive CDN API key here

By default, Hive Router will reload the Supergraph from Hive Console CDN every 10s. You can change this behaviour by adding poll_interval field:

supergraph:
  source: hive
  endpoint: https://cdn.graphql-hive.com/artifacts/v1/... # Use your Hive CDN endpoint here
  key: hvABCD # Use your Hive CDN API key here
  poll_interval: 60s

You can also provide fallback endpoints from cdn-mirror-graphql-hive.com in case of a possible unavailability of the main CDN endpoints, as shown below:

supergraph:
  source: hive
  endpoint:
    - https://cdn.graphql-hive.com/artifacts/v1/... # Use your Hive CDN endpoint here
    - https://cdn-mirror.graphql-hive.com/artifacts/v1/... # Use your Hive CDN mirror endpoint here
  key: hvABCD # Use your Hive CDN API key here
  poll_interval: 60s

For additional configuration options, refer to the supergraph API reference page.

From the file-system

If you wish to load the Supergraph from the file-system, use the supergraph configuration with source: file field:

supergraph:
  source: file
  path: ./supergraph.graphql # point to your local supergraph file

If you wish the router to reload the supergraph from the file-system periodically, add poll_interval field:

supergraph:
  source: file
  path: ./supergraph.graphql # point to your local supergraph file
  poll_interval: 5s # reload the supergraph every 5 seconds

Hive Router will use the file-system's metadata (modified-at attribute) to detect changes and reload the supergraph.

From object storage

You can load the supergraph from a named storage backend such as Amazon S3 or any S3-compatible service (Cloudflare R2, MinIO, LocalStack, DigitalOcean Spaces, Backblaze B2, Tigris, etc.).

This is a good fit when your CI pipeline publishes the supergraph artifact to object storage and you want the router to pick up new versions without redeploying.

Declare the backend once under top-level storages, then point supergraph.source: storage at the object you want to load:

storages:
  artifacts:
    type: s3
    bucket: my-router-artifacts
    region: eu-west-1

supergraph:
  source: storage
  storage_id: artifacts
  location: supergraph/current.graphql
  poll_interval: 30s

• storage_id references an entry in storages. Startup fails if the ID is not declared.
• location is the object key (path within the bucket).
• poll_interval is optional — when omitted, the router loads the supergraph once at startup.

When polling is enabled, the router uses conditional If-None-Match requests against the object's ETag and only reloads when storage reports the content has changed.

For provider-specific configuration (AWS S3 with IRSA, Cloudflare R2, MinIO, LocalStack), and for loading bucket names/credentials from environment variables via expressions, see the storages reference.

Reloading the Supergraph

The reload process of the Supergraph needs to be aligned with other on-going processes running in Hive Router.

When a Supergraph changes, in-flight requests will not be impacted and will complete based on the Supergraph version used when the request was initiated.

In addition, internal caches will be invalidated and all new requests will be served from the updated Supergraph.

In cases when the Supergraph reload process fails, Hive Router will continue to serve requests from the previous version of the Supergraph and will not impact the performance of the router (see Probes to understand how the Supergraph reload process impacts the router).