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:

router.config.yaml

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.

From a plugin

A plugin can select a supergraph for each request in on_http_request. This supports two models:

Override a configured file, Hive Console, or storage supergraph for selected requests.
Use supergraph.source: plugin with no configured fallback.

router.config.yaml

supergraph:
  source: plugin

The plugin constructs and retains an Arc<Supergraph>, then selects it with set_supergraph:

use std::sync::Arc;

use hive_router::plugins::hooks::on_supergraph_load::Supergraph;

let supergraph = Arc::new(Supergraph::from_sdl(
    include_str!("supergraph.graphql"),
    Default::default(),
)?);

// later, in on_http_request
payload.set_supergraph(supergraph.clone());
payload.proceed()

A selection is request-local. It does not replace the configured supergraph or become a default for other requests. The router pins the selected schema and its router runtime together, so validation, introspection, planning, authorization, execution, usage reporting, coprocessors, and request deduplication all use the same supergraph instance.

The plugin owns how long a supergraph remains selectable. Dropping its final Arc<Supergraph> retires it: new requests can no longer select that owner, ordinary in-flight requests finish, and subscriptions using it close with SUBSCRIPTION_SCHEMA_RELOAD. Plugins should therefore construct each reusable variant once and retain its Arc rather than constructing it for every request.

In plugin-only mode, every GraphQL and readiness request must receive a selection. Missing selection returns HTTP 503 with NO_SUPERGRAPH_AVAILABLE. A WebSocket connection is accepted and then closed with No supergraph available yet, allowing browser clients to observe the failure reason.

See Selecting a supergraph in on_http_request, the replace_schema example for overriding a configured default, and the feature_flags example for a plugin-only source.

Reloading and retiring a Supergraph

When a configured supergraph changes, in-flight requests continue with the exact schema and runtime they selected when the request began. New requests use the newly published supergraph.

Schema-aware validation, normalization, query-plan, and demand-control caches belong to a specific supergraph runtime. Replacing one configured supergraph does not clear caches belonging to unrelated plugin-selected supergraphs. Old caches remain alive only while requests or streams still use their old runtime. The shared parse cache is unaffected because parsing an operation is schema-independent.

Subscriptions close with SUBSCRIPTION_SCHEMA_RELOAD only when their selected supergraph retires. Configured replacement retires the previous configured generation. For plugin-selected supergraphs, retirement occurs when the plugin drops the final owning Arc<Supergraph>.

If configured schema or runtime construction fails, Hive Router continues serving the previous configured version (see Probes for its effect on router health).

Edit on GitHub