Check - WunderGraph

Usage

Check schema changes

npx wgc subgraph check <name> --schema <path-to-schema>

Use this command whenever you make modifications to your subgraphs. It will report any GraphQL or composition errors before they land on production. The report will be made visible under Schema Checks.

Check deletion of a subgraph

npx wgc subgraph check <name> --delete

This command will check any breaking changes or composition errors in case the subgraph is deleted.

Check how a new subgraph affects the federated graph

# There are two ways to check the impact of a new subgraph:

# 1. Create the subgraph and check the impact
npx wgc subgraph create products --label team=A --routing-url http://localhost:4001/graphql
npx wgc subgraph check <name> --schema schema.graphql

# 2. Check the impact without creating the subgraph
npx wgc subgraph check <name> --schema schema.graphql --label team=A

Description

The npx wgc subgraph check command checks for breaking changes and composition errors in all connected federated graphs associated with the specified subgraph. This validation process ensures that the new schema you intend to use does not introduce any issues that could negatively impact existing federated graphs.

This command also checks feature subgraphs. Pass its name to validate the proposed schema against the feature flag compositions that include it. See Schema Checks. Composition errors, composition warnings, and composed breaking changes include a FEATURE_FLAG column identifying the feature flag each entry belongs to (empty for the base supergraph).

Parameters

<name>: The name of the subgraph for which you want to perform the validation check. This should be the exact name of the subgraph you wish to check.

Options

-n, --namespace : The namespace of the federated graph (Default: “default”).
--schema <path-to-schema>: The path to the new schema file that you want to validate. This file should contain the complete schema definition in the GraphQL Schema Definition Language (SDL) format.
--delete: Check for breaking changes and composition errors in case the subgraph will be deleted.
--skip-traffic-check : This will skip checking against client traffic and any breaking change will fail the run.
-j, --json: Prints the check result in JSON format instead of table output. Useful for CI/CD automation and scripts.
-o, --out [string]: Writes the JSON check result to a destination file. This option enables JSON output automatically.
--label [labels...]: The labels to apply to the new subgraph. The labels are passed in the format <key>=<value> <key>=<value>. This parameter is always ignored if the subgraph already exists.
--disable-resolvability-validation: This flag disables the validation for whether all nodes of the federated graph are resolvable. Do not use unless troubleshooting.
-l, --limit [number]: The maximum number of entries to display for each category of results, such as schema changes, composed schema breaking changes, composition errors, composition warnings, lint issues, and graph pruning issues. Defaults to 50.

The check command requires either the --schema or --delete parameter.

Examples

Check for breaking changes and composition errors for the subgraph “products” with the new schema file located at ”./schemas/new_schema.graphql”:

npx wgc subgraph check products -n default --schema ./schemas/new_schema.graphql

Check for breaking changes and composition errors for the subgraph which does not exist yet:

npx wgc subgraph check newSubgraph -n default --schema ./schemas/new_schema.graphql --label team=A

Output the check result as JSON for automation:

npx wgc subgraph check products -n default --schema ./schemas/new_schema.graphql --json

Write the JSON check result to a file:

npx wgc subgraph check products -n default --schema ./schemas/new_schema.graphql --out ./check-result.json

The labels should match the labels of the federated graph you want to check against.

Sample output with changes and errors

Changes

CHANGE	TYPE	DESCRIPTION	BREAKING
BREAKING	FIELD_REMOVED	Field ‘email’ was removed from object type ‘User’
NON-BREAKING	FIELD_ADDED	Field ‘emailID’ was added to object type ‘User’

Composition Errors

FEDERATED_GRAPH_NAME	ERROR_MESSAGE
inventory	Type “Product” is an extension type, but there is no type definition for “Product” in any subgraphs.

Check for breaking changes and composition errors for the subgraph “products” with the new schema file located at ”./schemas/new_schema.graphql”:

npx wgc subgraph check employees --delete

Sample output

Changes

CHANGE	TYPE	DESCRIPTION	BREAKING
BREAKING	TYPE_REMOVED	Type ‘Department’ was removed
NON-BREAKING	TYPE_REMOVED	Type ‘RoleType’ was removed

Composition Errors

FEDERATED_GRAPH_NAME	ERROR_MESSAGE
inventory	The subgraph “products” could not be federated for the following reason: The object type “Employee” defines the directive “@override(from: “employees)” on the following field: “notes”. The required “from” argument of type “String!” must be provided with an existing subgraph name. However, a subgraph by the name of “employees” does not exist.

VCS Context

If you want to associate custom information with the checks being performed, you can do so by setting the following environment variables:

COSMO_VCS_AUTHOR: The author’s email address associated with the commit (e.g: foo@bar.com).
COSMO_VCS_COMMIT: The specific commit hash for the changes you are testing (e.g: de233ddwqedqwe).
COSMO_VCS_BRANCH: The branch name where the commit resides (e.g: main).

export COSMO_VCS_AUTHOR=foo@bar.com
export COSMO_VCS_COMMIT=de233ddwqedqwe
export COSMO_VCS_BRANCH=main

Usage in CI and GitHub Integration

Checkout the tutorial here on how to use the subgraph check command in CI with GitHub.

Notes

The npx wgc subgraph check command interacts with the Cosmo platform’s control plane and connected federated graphs to perform the validation checks.
If there are no breaking changes or composition errors detected, the tables will be empty, indicating that the new schema is compatible with the existing federated graphs.