Docs
Launch GraphOS Studio

Configuring schema checks

Define how schema checks are applied to schema changes


After you enable schema checks for your , you can customize their behavior to suit your use case. For example, you can:

  • Exclude past that were executed by a particular client, such as a client that you only use for testing
  • Exclude past that were executed relatively infrequently
  • Check schema changes against multiple s

In GraphOS Studio, you can configure default rules that are applied to every executed schema check. You define these rules from the Configuration tab of your 's Checks page:

Check configuration page in GraphOS Studio

Configuration options

  • Time range: Include all distinct that were executed within this range. The default value is 7 days ("Within the last week").

  • Operation count threshold: Exclude all that were executed fewer than this number of times within the specified time range.

  • Variants: Include all distinct that were executed against each selected of your . The default value is "Base variant" (that is, whichever variant are being run against).

  • Client exclusions: Exclude all that were executed by particular clients, such as clients used exclusively for development and testing.

    Excluded clients configuration in GraphOS Studio

Using the Rover CLI

You can customize a single run of by providing options to the . If you've also configured default rules for , any command-line options you provide take precedence over those rules.

Validation period

You can provide the --validation-period option to specify how far back in time Studio should look when determining the compatibility of past with the changes to your schema (by default, the command uses the last 7 days of operations).

This command checks schema changes against the past two weeks of :

rover subgraph check docs-example-graph@current --name products --schema ./schema.graphql --validation-period="2 weeks"

Valid durations are represented as any combination of years, months, weeks, days, min, and sec:

  • 1 month 2 weeks
  • 525600 min

NOTE

If you specify a --validation-period that exceeds your organization's retention period, the subgraph check command fails with an error.

Threshold values

You can provide threshold values to to ignore historical that are relatively rare.

For example, you might want to discontinue support for an old version of your client that uses deprecated . You can set threshold values to determine when an acceptably small number of users are using the outdated client, thus reducing the impact of discontinuing support.

Provide threshold values with the following flags:

  • --query-count-threshold - Check your schema only against that have been executed at least the specified number of times within the specified duration.
  • --query-percentage-threshold - Check your schema only against that account for at least the specified percentage of all operations against the within the specified duration. For example, specify 3 to set this threshold to 3%.

NOTE

You can provide values for both of these flags. If you do, an must meet or exceed both thresholds for to include it.

Here's an example of running rover subgraph check with threshold values:

rover subgraph check docs-example-graph@current \
# Path to schema file
--schema ./schema.graphql
# Name of subgraph with schema updates
--name products
# Check the schema against operations that have run in the last 5 days
--validation-period="5 days" \
# Only check against operations that have run at least 5 times during the 5-day duration
--query-count-threshold=5 \
# Only check against operations that account for at least 3% of total operation volume
--query-percentage-threshold=3

To request other filtering or threshold mechanisms, please get in touch with us on the Rover repository.

Checking against multiple environments

You might want to check schema changes against multiple environments, such as production, staging, and beta. Each of these environments might have a slightly different schema to support features that are experimental or in active development. In , these schemas are represented as variants of a single .

You specify which you want to check against in the graph ref you provide to rover subgraph check:

rover subgraph check docs-example-graph@staging --name products --schema ./schema.graphql

The docs-example-graph@staging specifies the staging of the docs-example-graph .

To check your schema against multiple , call rover subgraph check once for each . Doing so results in status checks similar to the following:

Multiple service checks
Previous
Overview
Next
Connect to GitHub
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company