Setting the file. One moment.
Subchapter 12.5
references/subgraphs.mdMarkdown6 KBView on GitHub
Commands for managing federated subgraph schemas in Apollo GraphOS.
Download a subgraph schema from GraphOS.
# Basic fetch
rover subgraph fetch my-graph@production --name products
# Output to file
rover subgraph fetch my-graph@production --name products > products.graphql
# JSON output
rover subgraph fetch my-graph@production --name products --format jsonOptions:
| Option | Description |
|---|---|
--name <NAME> | Subgraph name (required) |
--format <FORMAT> | Output format: plain (default) or json |
Extract schema from a running GraphQL server via introspection.
# Basic introspection
rover subgraph introspect http://localhost:4001/graphql
# With headers
rover subgraph introspect http://localhost:4001/graphql \
--header "Authorization: Bearer token123"
# Multiple headers
rover subgraph introspect http://localhost:4001/graphql \
--header "Authorization: Bearer token" \
--header "X-Custom-Header: value"
# Watch mode (poll for changes)
rover subgraph introspect http://localhost:4001/graphql --watchOptions:
| Option | Description |
|---|---|
--header <HEADER> | HTTP header(s) to include |
--watch | Poll endpoint and output changes |
--polling-interval <SECONDS> | Interval for watch mode (default: 1) |
List all subgraphs in a graph variant.
rover subgraph list my-graph@productionOutput includes:
Publish a subgraph schema to GraphOS.
# From file
rover subgraph publish my-graph@production \
--name products \
--schema ./products.graphql \
--routing-url https://products.example.com/graphql
# From stdin (introspection)
rover subgraph introspect http://localhost:4001/graphql | \
rover subgraph publish my-graph@production \
--name products \
--schema - \
--routing-url https://products.example.com/graphql
# Process substitution
rover subgraph publish my-graph@production \
--name products \
--schema <(rover subgraph introspect http://localhost:4001/graphql) \
--routing-url https://products.example.com/graphqlOptions:
| Option | Description |
|---|---|
--name <NAME> | Subgraph name (required) |
--schema <PATH> | Schema file path or - for stdin (required) |
--routing-url <URL> | URL where Router sends requests |
--allow-invalid-routing-url | Allow non-HTTPS or non-standard URLs |
--no-url | Skip URL update (schema only) |
Routing URL:
Validate schema changes against GraphOS.
# Basic check
rover subgraph check my-graph@production \
--name products \
--schema ./products.graphql
# Check with specific validation period
rover subgraph check my-graph@production \
--name products \
--schema ./products.graphql \
--query-count-threshold 1000 \
--query-count-threshold-percentage 5Check validates:
Options:
| Option | Description |
|---|---|
--name <NAME> | Subgraph name (required) |
--schema <PATH> | Schema file path (required) |
--query-count-threshold <N> | Min operations for breaking change |
--query-count-threshold-percentage <N> | Min % of operations |
--background | Run check in background (returns check ID) |
Exit codes:
0 - Check passed1 - Check failed (breaking changes or errors)2 - Check completed with warningsRun GraphOS linting rules against a schema.
# Lint local schema
rover subgraph lint --name products ./products.graphql
# Lint with specific graph for rules
rover subgraph lint my-graph@production --name products ./products.graphqlCommon lint rules:
Remove a subgraph from a graph variant.
# Delete with confirmation prompt
rover subgraph delete my-graph@production --name products
# Delete without confirmation
rover subgraph delete my-graph@production --name products --confirmWarning: Deleting a subgraph:
Options:
| Option | Description |
|---|---|
--name <NAME> | Subgraph name (required) |
--confirm | Skip confirmation prompt |
For authenticated endpoints:
# Bearer token
rover subgraph introspect http://localhost:4001/graphql \
--header "Authorization: Bearer $(cat token.txt)"
# API key
rover subgraph introspect http://localhost:4001/graphql \
--header "x-api-key: my-api-key"
# From environment variable
rover subgraph introspect http://localhost:4001/graphql \
--header "Authorization: Bearer $AUTH_TOKEN"rover subgraph publish my-graph@production \
--name products \
--schema <(rover subgraph introspect http://localhost:4001/graphql) \
--routing-url https://products.example.com/graphql# In CI/CD pipeline
rover subgraph check my-graph@production \
--name products \
--schema ./products.graphql && \
rover subgraph publish my-graph@production \
--name products \
--schema ./products.graphql \
--routing-url https://products.example.com/graphql# List and fetch each
for name in $(rover subgraph list my-graph@production --format json | jq -r '.data.subgraphs[].name'); do
rover subgraph fetch my-graph@production --name "$name" > "$name.graphql"
done