Working with subgraphs
in a federated architecture
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
Fetching from Apollo Studio
This requires first authenticating Rover with Apollo Studio.
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:
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.
You can omit
@
and the variant name. If you do, Rover uses the default variant, namedcurrent
.
The --name
option is also required. It must match the subgraph you're fetching the schema for.
Fetching via enhanced introspection
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:
rover subgraph introspect http://localhost:4001
The subgraph must be reachable by Rover. The subgraph does not need to have introspection enabled.
Unlike a standard introspection query, the result of
rover subgraph introspect
does include certain directives (specifically, directives related to federation like@key
). This is possible because the command uses a separate introspection mechanism provided by the Apollo Federation specification.
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 schema as input to other Rover 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 > accounts-schema.graphql
For more on passing values via
stdout
, see Usingstdout
.
Listing subgraphs for a supergraph
This requires first authenticating Rover with Apollo Studio.
You can use the subgraph list
to list all of a particular supergraph's available subgraphs in Apollo Studio:
rover subgraph list my-supergraph@dev
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.
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-graph/service-list
Publishing a subgraph schema to Apollo Studio
This requires first authenticating Rover with Apollo Studio.
You can use Rover to publish schema changes to a subgraph in one of your Apollo Studio 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 argument my-graph@my-variant
in the example above is a graph ref that specifies the ID of the Studio graph you're publishing to, along with which variant you're publishing to.
You can omit
@
and the variant name. If you do, Rover publishes the schema to the default variant, namedcurrent
.
Options include:
Name | Description |
---|---|
|
Required. The path to a local Alternatively, you can provide |
|
Required. The name of the subgraph to publish to. |
|
Required. Used by a gateway running in managed federation mode. If you're running a subgraph that hasn't been deployed yet or isn't using managed federation, you can pass a placeholder URL or leave the flag empty. |
Checking subgraph schema changes
Schema checks require a paid plan.
Before you publish subgraph schema changes to Apollo Studio, 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, 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.