GraphQL Query Plan Inspection and Validation

See which subgraphs each operation touches, trace the execution order, and catch broken operations in CI before they ship.

Built into the router. One header to inspect. One CLI command to gate your build.

The problem

Slow queries stay opaque without an execution map

Federation spreads work across services. You need visibility into how the router splits and schedules that work.

Queries are a black box

When a query is slow, there's no obvious way to find out which subgraph call is the bottleneck, or whether the query is even being planned efficiently in the first place.

Schema changes silently break operations

A rename in one subgraph can make a production query unplannable. You find out when the query fails, not when the schema is merged.

Performance tuning is guesswork

Teams try reshaping the query, adding @shareable, tweaking @key fields, and then push to staging to see if it helped. The feedback loop is slow, and the changes are hard to justify.

Our solution

Query plans you can see, cache, and validate in CI

Cosmo Router's query planner breaks every GraphQL operation into an explicit execution plan across your subgraphs, caches it by operation hash, and lets you inspect or batch-validate plans in CI so you catch broken operations before they reach production.

Three ways to use plans

1. Send X-WG-Include-Query-Plan: true and the router returns the plan in the response extensions.
2. In the Cosmo Studio playground, it renders visually.
3. For CI, batch-generate plans for every operation in a folder and fail the build if any operation becomes unplannable.

Query planning

Before & After

How federated query planning works

01

Stable hash → reusable cache entries.

Parse and normalize

Router parses the incoming operation, normalizes it against the federated schema, and hashes it. The hash is the cache key.

02

Miss pays planning cost once.

Check the plan cache

Cache hit: skip straight to execution. Cache miss: build a plan (which subgraphs hold which fields, how entity joins resolve, what order the fetches run in).

03

Same runtime path as production traffic.

Execute the plan

Subgraph calls run according to the plan. Entity references resolve through federation _entities requests (shared types fetched by reference across subgraphs). Results merge and return to the client.

04

Debug without guessing.

Inspect on demand

Any request can ask for its plan back with X-WG-Include-Query-Plan: true. Studio renders it visually; CI consumes it as JSON.

Examples

Request a plan · batch-generate in CI

Use headers for ad-hoc inspection; use the CLI to validate every persisted operation.

Batch plan generation requires Cosmo Router 0.185.0 or later. Full flag reference: batch-generate query plans.

Ship plans alongside your schema

Debug in Studio, gate in CI, cache at runtime: one planner end to end.

FAQ

GraphQL query planning

• What is a GraphQL query plan and why does it matter for federation?
• How do you debug a slow federated GraphQL query?
• How do you prevent a GraphQL schema change from breaking production queries?
• How is a GraphQL query plan cached?
• Does requesting a GraphQL query plan add latency to the response?
• How is a GraphQL query plan cache invalidated when the schema changes?
• Can you batch-generate GraphQL query plans locally without a control plane connection?
• What does the X-WG-Skip-Loader header do during GraphQL query plan inspection?
• Does GraphQL query planning work the same for subscriptions as for queries and mutations?
• What router version is required for CI batch generation of GraphQL query plans?

Deep dive in the query plan documentation.