Launch Apollo Studio

Configuring schema checks

Define exactly what schema changes are checked against

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

  • Exclude past operations that were executed by a particular client, such as a client that you only use for testing
  • Check schema changes against multiple graph variants

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

Check configuration page in Apollo Studio

Configuration options

  • Time range: Include all distinct operations that were executed within this range. The default value is 7 days ("Within the last week").
  • Operation count threshold: Exclude all operations that were executed fewer than this number of times within the specified time range.
  • Variants: Include all distinct operations that were executed against each selected variant of your graph. The default value is "Base variant" (i.e., whichever variant schema checks are being run against).
  • Client exclusions: Exclude all operations that were executed by particular clients, such as clients used exclusively for development and testing.Excluded clients configuration in Apollo Studio

Using the Apollo CLI

You can customize the execution of a single apollo service:check command by providing command-line options to it. If you've also configured default rules for schema checks in Apollo Studio, any command-line options you provide take precedence over those rules.

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

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

apollo service:check --validationPeriod=P2W

Valid durations are represented in ISO 8601 format. You can also provide a number in seconds (e.g., 86400 for a single day).

If you specify a validationPeriod that exceeds your organization's operation retention period, the service:check command fails with an error.

Threshold values

You can also customize the behavior of schema checks by specifying threshold values to the service:check command. These values tell checks to ignore all historical operations that do not exceed the threshold(s) you specify.

For example, you might want to discontinue support for an old version of your client that uses deprecated fields. 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:

  • --queryCountThreshold - Validate your schema only against operations that have been executed at least the specified number of times within the specified duration.
  • --queryCountThresholdPercentage - Validate your schema only against operations that account for at least the specified percentage of all operations against the graph 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 operation must meet or exceed both thresholds for schema checks to include it.

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

npx apollo service:check \
# Validate the schema against operations that have run in the last 5 days
--validationPeriod=P5D \
# Only validate against operations that have run at least 5 times during the 5 day duration
--queryCountThreshold=5 \
# Only validate against operations that account for at least 3% of total operation volume

If you have any requests for other filtering or threshold mechanisms, please get in touch with us on the apollo-tooling repository.

Checking against multiple environments

You might want to check your 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 Apollo Studio, these schemas are represented as variants of a single data graph.

You can check your schema against a particular variant by including the --variant flag in your call to apollo service:check, like so:

$ apollo service:check --variant=staging

If you want to check your schema against multiple variants, call apollo service:check once for each variant. Running service:check against multiple variants results in status checks similar to the following:

multiple service checks

Edit on GitHub