Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Docs
Launch GraphOS Studio

Rover subgraph commands


A subgraph is a graph that contributes to the composition of a federated supergraph:

Supergraph (A + B + C)
Subgraph A
Subgraph B
Subgraph C

commands that interact with s begin with rover subgraph.

Fetching a subgraph schema

These commands enable you to fetch the for a single in a . To instead fetch the API schema for a supergraph, use rover graph fetch. To fetch the , use rover supergraph fetch.

subgraph fetch

This command requires authenticating Rover with GraphOS.

You can use to fetch the current of any that belongs to a Studio graph and that Rover has access to.

Run the subgraph fetch command, like so:

rover subgraph fetch my-graph@my-variant --name accounts

The my-graph@my-variant in the example above is a graph ref that specifies the ID of the Studio graph you're fetching from, along with which variant you're fetching.

The --name option is required. It specifies which you're fetching the for.

subgraph introspect

If you need to obtain a running 's , you can use to execute an enhanced query on it. This is especially helpful if the subgraph doesn't define its via (as is the case with graphql-kotlin).

Use the subgraph introspect command, like so:

rover subgraph introspect http://localhost:4001

The must be reachable by . The subgraph does not need to have enabled.

Unlike a standard query, the result of rover subgraph introspect does include certain s (specifically, directives related to federation like @key). This is possible because the command uses a separate mechanism provided by the Apollo Federation subgraph specification.

Watching for schema changes

If you pass --watch to rover subgraph introspect, introspects your every second. Whenever the returned differs from the previously returned , outputs the updated schema. This is most useful when combined with the --output <OUTPUT_FILE> which will write the response out to a file whenever its contents change.

Including headers

If the endpoint you're trying to reach requires HTTP headers, you can use the --header (-H) flag to pass key:value pairs of headers. If you have multiple headers to pass, provide the flag multiple times. If a header includes any spaces, the pair must be quoted.

rover subgraph introspect http://localhost:4001 --header "Authorization: Bearer token329r"

Output format

rover subgraph introspect http://localhost:4001\
| rover subgraph publish my-graph@dev\
--schema - --name accounts\
--routing-url https://my-running-subgraph.com/api

By default, both subgraph fetch and subgraph introspect output fetched SDL to stdout. This is useful for providing the as input to other commands:

rover subgraph introspect http://localhost:4000 | rover subgraph check my-graph --schema -

You can also save the output to a local .graphql file like so:

# Creates accounts-schema.graphql or overwrites if it already exists
rover subgraph introspect http://localhost:4000 --output accounts-schema.graphql

For more on passing values via stdout, see Using stdout.

Listing subgraphs in a supergraph

subgraph list

This command requires authenticating Rover with GraphOS.

You can use the subgraph list to list all of a particular 's available s in :

rover subgraph list my-supergraph@staging

This command lists all s for the specified , including their routing URLs and when they were last updated (in local time). A link to view this information in Apollo Studio is also provided.

Subgraphs:
+----------+-------------- --------------+----------------------------+
| Name | Routing Url | Last Updated |
+----------+-----------------------------+----------------------------+
| reviews | https://reviews.my-app.com | 2020-10-21 12:23:28 -04:00 |
+----------+----------------------------------------+-----------------+
| books | https://books.my-app.com | 2020-09-20 13:58:27 -04:00 |
+----------+----------------------------------------+-----------------+
| accounts | https://accounts.my-app.com | 2020-09-20 12:23:36 -04:00 |
+----------+----------------------------------------+-----------------+
| products | https://products.my-app.com | 2020-09-20 12:23:28 -04:00 |
+----------+----------------------------------------+-----------------+
View full details at https://studio.apollographql.com/graph/my-supergraph/service-list

Publishing a subgraph schema to GraphOS

subgraph publish

This command requires authenticating Rover with GraphOS.

You can use to publish changes to a in one of your -managed supergraphs.

Use the subgraph publish command, like so:

rover subgraph publish my-supergraph@my-variant \
--schema "./accounts/schema.graphql" \
--name accounts \
--routing-url "https://my-running-subgraph.com/api"

The my-supergraph@my-variant in the example above is a graph ref that specifies the ID of the graph you're publishing to, along with which variant you're publishing to.

You can omit @ and the name. If you do, publishes the to the default variant, named current.

If the graph exists in the graph but the does not, a new is created on publish.

Options include:

NameDescription
--schema

Required. The path to a local .graphql or .gql file, in SDL format.

Alternatively, you can provide -, in which case the command uses an string piped to stdin instead (see Using stdin).

--name

Required. The name of the to publish to.

Every name must:

  • Begin with a letter (capital or lowercase)
  • Include only letters, numbers, underscores (_), and hyphens (-)
  • Have a maximum of 64 characters
--routing-url

The URL that your uses to communicate with the in a managed federation architecture.

Required the first time you publish a particular . If your subgraph isn't deployed yet, or if you aren't using managed federation, you can pass an empty string. Passing an empty string requires you to set the --allow-invalid-routing-url flag.

Optional after your first publish. Provide only if you need to change the 's routing URL.

--convert

If a monolithic for this already exists in the graph instead of multiple schemas, you need to run rover subgraph publish with the --convert flag to convert this to a federated graph with one or more s.

This permanently deletes the monolithic from this and replaces it with a single . In many cases, you need to run subgraph publish for multiple or all of your s before Studio can successfully compose a .

This option has no effect if you publish to a non-monolithic .

--allow-invalid-routing-url

By default, rover subgraph publish will fail if an unparsable routing URL is associated with a . If you need to disable this warning and allow the invalid URL to be published anyway, you can pass this option.

Validating subgraph schema changes

subgraph check

This command requires authenticating Rover with GraphOS.

Before you publish subgraph schema changes to GraphOS, you can check those changes to confirm that you aren't introducing breaking changes to your application clients.

To do so, you can run the subgraph check command:

# using a schema file
rover subgraph check my-graph@my-variant --schema ./schema.graphql --name accounts
# using piped input to stdin
rover subgraph introspect http://localhost:4000 \
| rover subgraph check my-graph@my-variant \
--schema - --name accounts

As shown, s and options are similar to subgraph publish.

To configure the behavior of (such as the time range of past s to check against), see the documentation for schema checks.

If you don't want to wait for the check to complete, you can run the command with the --background flag. You can then look up the check's result in Apollo Studio on the Checks tab.

Running checks in CI

If you're running in CI, you might want to pass the --background flag to rover subgraph check. This flag instructs to initiate but not await their result. If you've connected Apollo Studio to your GitHub repository, the integration detects the checks execution and adds a status to the associated pull request.

subgraph lint

This command requires authenticating Rover with GraphOS.

You can run the linter against your local schema to identify any violations of formatting and naming best practices:

Example command
rover subgraph lint --name products --schema ./products-schema.graphql my-graph@my-variant

The my-graph@my-variant in the example above is a graph ref that specifies the ID of the graph you're comparing your changes against, along with which variant you're comparing against.

linting also runs as one of the checks included in subgraph check. Use this command to perform one-off linting.

Options include:

NameDescription
--schema

Required. The path to a local .graphql or .gql file, in SDL format.

Alternatively, you can provide -, in which case the command uses an string piped to stdin instead (see Using stdin).

--name

Required. The name of the published to compare changes against.

--ignore-existing-lint-violations

If provided, the linter only flags violations that are present in the diff between your local and your published schema.

By default, this command flags all violations in your local .

Deleting a subgraph

subgraph delete

This command requires authenticating Rover with GraphOS.

You can delete a single from a federated by running rover subgraph delete:

# ⚠️ This action is irreversible!
rover subgraph delete my-graph@my-variant --name subgraph-to-delete

This command prompts you for confirmation because the action is irreversible. You can bypass confirmation by passing the --confirm flag.

This command fails with an error if any other references types that originate in this subgraph.

To delete an entire federated graph instead of a single , see Deleting a variant.

Previous
readme
Next
supergraph
Edit on GitHubEditForumsDiscord