Rover subgraph commands

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

Rover commands that interact with subgraphs begin with rover subgraph.

Fetching a subgraph schema

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

subgraph fetch

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

Run the subgraph fetch command, like so:

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

The argument 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 subgraph you're fetching the schema for.

subgraph introspect

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

Use the subgraph introspect command, like so:

1
rover subgraph introspect http://localhost:4001

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

Watching for schema changes

If you pass --watch to rover subgraph introspect, Rover introspects your subgraph every second. Whenever the returned schema differs from the previously returned schema, Rover outputs the updated schema. This is most useful when combined with the --output <OUTPUT_FILE> argument which will write the introspection 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.

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

Output format

1
rover subgraph introspect http://localhost:4001\
2
  | rover subgraph publish my-graph@dev\
3
  --schema - --name accounts\
4
  --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 schema as input to other Rover commands:

1
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:

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

Listing subgraphs in a supergraph

subgraph list

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

1
rover subgraph list my-supergraph@staging

This command lists all subgraphs for the specified variant, 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.

1
Subgraphs:
2

3
+----------+-------------- --------------+----------------------------+
4
| Name     | Routing Url                 | Last Updated               |
5
+----------+-----------------------------+----------------------------+
6
| reviews  | https://reviews.my-app.com  | 2020-10-21 12:23:28 -04:00 |
7
+----------+----------------------------------------+-----------------+
8
| books    | https://books.my-app.com    | 2020-09-20 13:58:27 -04:00 |
9
+----------+----------------------------------------+-----------------+
10
| accounts | https://accounts.my-app.com | 2020-09-20 12:23:36 -04:00 |
11
+----------+----------------------------------------+-----------------+
12
| products | https://products.my-app.com | 2020-09-20 12:23:28 -04:00 |
13
+----------+----------------------------------------+-----------------+
14

15
View full details at https://studio.apollographql.com/graph/my-supergraph/service-list

Publishing a subgraph schema to GraphOS

subgraph publish

You can use Rover to publish schema changes to a subgraph in one of your GraphOS-managed supergraphs.

Use the subgraph publish command, like so:

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

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

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

Options include:

Validating subgraph schema changes

subgraph check

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:

1
# using a schema file
2
rover subgraph check my-graph@my-variant --schema ./schema.graphql --name accounts
3

4
# using piped input to stdin
5
rover subgraph introspect http://localhost:4000 \
6
  | rover subgraph check my-graph@my-variant \
7
  --schema - --name accounts

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

To configure the behavior of schema checks (such as the time range of past operations 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 schema checks in CI, you might want to pass the --background flag to rover subgraph check. This flag instructs Rover to initiate schema checks 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

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

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

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

Options include:

Deleting a subgraph

subgraph delete

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

1
# ⚠️ This action is irreversible!
2
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 subgraph references types that originate in this subgraph.

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