Setting the file. One moment.
Subchapter 13.5
references/contracts.mdMarkdown6 KBView on GitHub
Commands for managing contract variants in Apollo GraphOS. Contracts create filtered views of a supergraph schema, exposing different API surfaces to different consumers.
A contract variant applies tag-based filters to a source variant’s supergraph schema. Subgraph authors annotate types and fields with @tag(name: "...") directives, and the contract’s include/exclude lists determine which tagged elements appear in the filtered schema. This lets you serve tailored APIs (public vs. internal, partner vs. mobile) from a single supergraph.
View the current configuration of a contract variant.
rover contract describe my-graph@public-apiOutput includes:
Options:
| Option | Description |
|---|---|
<GRAPH_REF> | The contract variant to describe (required) |
Publish an updated contract configuration to GraphOS and trigger a launch.
# Include only fields tagged "public", exclude "internal", hide unreachable types
rover contract publish my-graph@public-api \
--include-tag public \
--no-exclude-tags \
--hide-unreachable-types
# Multiple include tags
rover contract publish my-graph@partner-api \
--include-tag public \
--include-tag partner \
--no-exclude-tags \
--hide-unreachable-types
# Exclude specific tags, include everything else
rover contract publish my-graph@external-api \
--no-include-tags \
--exclude-tag internal \
--exclude-tag experimental \
--hide-unreachable-types
# Set the source variant (required on first publish)
rover contract publish my-graph@public-api \
--source-variant production \
--include-tag public \
--no-exclude-tags \
--hide-unreachable-types
# Publish without triggering a launch
rover contract publish my-graph@public-api \
--include-tag public \
--no-exclude-tags \
--hide-unreachable-types \
--no-launchOptions:
| Option | Description |
|---|---|
<GRAPH_REF> | The contract variant to publish to (required) |
--source-variant <NAME> | Source variant for this contract (required on first publish, cannot be changed later) |
--include-tag <TAG> | Tag names to include (repeatable) |
--no-include-tags | Use an empty include list (mutually exclusive with --include-tag) |
--exclude-tag <TAG> | Tag names to exclude (repeatable) |
--no-exclude-tags | Use an empty exclude list (mutually exclusive with --exclude-tag) |
--hide-unreachable-types | Hide types that are unreachable from any root operation |
--no-hide-unreachable-types | Keep unreachable types in the contract schema |
--no-launch | Do not trigger a launch after publishing |
Every publish requires exactly one flag from each pair: --include-tag or --no-include-tags, --exclude-tag or --no-exclude-tags, and --hide-unreachable-types or --no-hide-unreachable-types.
Preview the contract schema a filter configuration would produce, without publishing it. The build runs asynchronously on GraphOS. By default, Rover polls until it completes.
# Preview a filter configuration
rover contract preview my-graph@production \
--include-tag public \
--no-exclude-tags \
--hide-unreachable-types
# Start the build and return immediately
rover contract preview my-graph@production \
--include-tag public \
--no-exclude-tags \
--hide-unreachable-types \
--async
# Check the status of a previously started build
rover contract preview my-graph@production \
--build-id abc123Options:
| Option | Description |
|---|---|
<GRAPH_REF> | The variant whose supergraph to filter (required) |
--include-tag <TAG> | Tag names to include (repeatable) |
--no-include-tags | Use an empty include list |
--exclude-tag <TAG> | Tag names to exclude (repeatable) |
--no-exclude-tags | Use an empty exclude list |
--hide-unreachable-types | Hide unreachable types |
--no-hide-unreachable-types | Keep unreachable types |
--async | Return immediately with a build ID instead of polling |
--build-id <ID> | Check the status of a previous build (conflicts with all filter flags) |
When not using --build-id, filter flags follow the same pairing rules as contract publish.
# 1. Tag subgraph fields in your schemas with @tag(name: "public")
# 2. Publish the contract configuration
rover contract publish my-graph@public-api \
--source-variant production \
--include-tag public \
--no-exclude-tags \
--hide-unreachable-types
# 3. Verify the result
rover contract describe my-graph@public-api# Test a new filter configuration without affecting the live contract
rover contract preview my-graph@production \
--include-tag public \
--include-tag partner \
--no-exclude-tags \
--hide-unreachable-types
# If the preview looks good, publish
rover contract publish my-graph@partner-api \
--source-variant production \
--include-tag public \
--include-tag partner \
--no-exclude-tags \
--hide-unreachable-types# Add a new tag to the existing contract
rover contract publish my-graph@public-api \
--include-tag public \
--include-tag beta \
--no-exclude-tags \
--hide-unreachable-typesE039 - Not a contract variant:
The specified variant is not a contract variant. Verify the graph@variant is correct and that the variant is configured as a contract in GraphOS Studio.
E040 - Contract publish failed: The contract configuration could not be published. Check the error message for details on invalid inputs.
contract preview before publishing.