Can I create and publish a subgraph in one step?

Yes. `wgc subgraph publish` with --routing-url and --label flags creates the subgraph and publishes the schema simultaneously if the subgraph does not exist yet. This is the fastest path for new service registration.

What is an Event-Driven Graph subgraph?

An Event-Driven Graph (EDG) subgraph does not have a routing URL because it receives events rather than serving HTTP requests. Use the --edg flag when creating it: `wgc subgraph create events --label team=A --edg`.

How do I check the impact before deleting a subgraph?

Run `wgc subgraph check [name] --delete`. This shows which federated graphs depend on the subgraph before anything is removed. After reviewing the output and confirming there are no critical dependencies, run `wgc subgraph delete [name]`.

Can I manage subgraphs across multiple environments?

Yes. Namespaces isolate environments. Use the --namespace flag on any publish, check, or delete command to target the correct environment. The same subgraph name can exist independently in dev, staging, and production namespaces.

Does subgraph management work with a self-hosted Cosmo deployment?

Yes. All subgraph operations — create, publish, check, update, delete — run against the control plane and work with both Cosmo Cloud and self-hosted deployments without configuration changes.

GraphQL Subgraph Management | Cosmo by WunderGraph

The problem

Subgraph operations without unified tooling create drift

Registering services, publishing schema changes, managing labels, and retiring old subgraphs each require different tools when there is no unified system — and inconsistencies compound over time.

Subgraph configurations drift across environments

When teams manage routing URLs, labels, and schema versions manually across dev, staging, and production, inconsistencies accumulate. A staging subgraph points to one URL; production points to another. No one notices until a query fails.

Deleting a subgraph without checking impact causes cascading failures

Removing a subgraph that other parts of the federated graph depend on breaks composition. Without pre-deletion impact analysis, teams find out after the damage is done.

No visibility across teams without central management

Which subgraph is registered for which federated graph? Which schema version is currently published? Without central management, answering these questions requires talking to each service team individually.

Our solution

Complete lifecycle control in five operations

Cosmo's Subgraph Management gives teams complete lifecycle control over federated services. Create, publish, update, check, and delete subgraphs through a unified CLI and Studio interface — with label-based composition rules and namespace isolation for multi-environment workflows.

Create registers the subgraph in the control plane with a name, routing URL, and label set.
Publish pushes the schema file and triggers automatic composition with all matching federated graphs.
Check validates composition impact before publishing — and flags deletion impact with the --delete flag.
Update changes routing URLs or labels without republishing the schema.
Delete removes the subgraph after a pre-deletion impact check confirms no critical dependencies remain.

All operations available via CLI for CI/CD automation and via Studio for visual management.

Subgraph management

Before & After

Before Cosmo	With Cosmo
Manual subgraph registration	CLI/API-driven creation
Ad-hoc schema file distribution	Centralized publish workflow
Unclear subgraph-to-graph relationships	Label-based composition rules
Risky subgraph removal	Pre-deletion impact analysis

Label-based composition

How labels control composition

Labels are key-value pairs assigned to each subgraph (e.g., team=backend).
Federated graphs define label matchers. A subgraph joins any federated graph whose matchers include its labels.
Publishing a schema triggers composition with all matching federated graphs automatically.
Updating labels with wgc subgraph update changes graph membership without touching the schema.

Key benefits

Complete lifecycle control for your federated services

All five operations included on Free, Pro, and Enterprise.

Full lifecycle control from one place

Lifecycle

Create, publish, update, and delete subgraphs through a unified CLI and Studio interface. Every operation targets the same control plane, so state is consistent across all environments.

Label-based composition ties subgraphs to federated graphs

Labels

Labels are key-value pairs assigned to subgraphs (e.g., team=backend). Federated graphs define label matchers. A subgraph joins any federated graph whose matchers include its labels — no manual wiring required.

Namespace isolation for multi-environment workflows

Namespaces

Dev, staging, and production run in separate namespaces. The same subgraph name can exist in each namespace independently. Publish to staging with --namespace staging; promote to production with --namespace production.

Validate impact before any change lands

Check

Run wgc subgraph check before publishing to catch composition errors and breaking changes. Run wgc subgraph check --delete to see exactly which federated graphs would be affected before removing a subgraph.

Automation-friendly via CLI and API

CI/CD

Every subgraph operation — create, publish, update, check, delete — is available as a CLI command. Integrate into CI/CD pipelines to automate schema promotion and catch problems before they reach production.

How subgraph management works

01

Registered in the control plane.

Create the subgraph

Run `wgc subgraph create` with a name, routing URL, and label set. This registers the subgraph in the control plane. For event-driven subgraphs, add the --edg flag instead of a routing URL.

02

Triggers automatic composition.

Publish the schema

Run `wgc subgraph publish` with a schema file. The control plane triggers composition with all federated graphs whose label matchers include the subgraph's labels.

03

Nothing published until you say so.

Check before publishing

Run `wgc subgraph check` with the proposed schema file to validate composition impact and detect breaking changes before anything is published.

04

No schema republish needed.

Update metadata

Use `wgc subgraph update` to change the routing URL or label set without republishing the schema. Useful when a service moves domains or team ownership changes.

05

Impact analysis before removal.

Delete safely

Run `wgc subgraph check --delete` to see which federated graphs depend on the subgraph. After confirming no critical dependencies remain, run `wgc subgraph delete`.

CLI examples

Every operation from the terminal

Create, publish-and-update, check, and delete — all via wgc.

1

2

3

4

5

6

7

Use cases

Where teams use subgraph management

New subgraph registration

create + publish

A team launches a new microservice and needs to join the federated graph. They run `wgc subgraph create products --label team=backend --routing-url http://products:4001/graphql`, then publish the initial schema with `wgc subgraph publish products --schema ./schema.graphql`.

Safe schema update

check + publish

A developer needs to add new fields and deprecate old ones. They run `wgc subgraph check products --schema ./new-schema.graphql` first. If checks pass, they run `wgc subgraph publish products --schema ./new-schema.graphql`.

Environment promotion

--namespace

A schema change tested in staging is ready for production. They publish with `wgc subgraph publish products --namespace production --schema ./schema.graphql`. Labels match production federated graphs for automatic composition.

Subgraph retirement

check --delete

A legacy subgraph is being deprecated. They run `wgc subgraph check products --delete` to see the impact on all connected federated graphs. After confirming no critical dependencies, they run `wgc subgraph delete products`.

When to use subgraph management

When to use

You are registering a new microservice in a federated GraphQL architecture.
You want automated schema promotion across dev, staging, and production namespaces.
You need to safely remove a subgraph and verify there are no breaking dependencies first.

Requirements

Namespace access with appropriate permissions in Cosmo.
A routing URL accessible from the router — for non-Event-Driven Graph subgraphs.
A schema file in GraphQL SDL format for publish operations.

Start managing subgraphs in minutes

One CLI. Full lifecycle control. Free to start.

Start Free See the docs

Ready to go deeper?

Full CLI reference for every subgraph operation.

wgc subgraph →create →publish →update →check →delete →

Related capabilities

Schema Composition — Every subgraph publish triggers automatic composition with the full history recorded.
Schema Checks — Validate proposed schema changes before publishing with breaking change detection and traffic analysis.
GraphQL Federation — Subgraphs using v1 or v2 directives are supported without version restrictions.
Monograph Support — For single-service GraphQL, monographs simplify management with automatic internal subgraph handling.

Manage every federated service from one CLI and Studio