What is a GraphQL query plan and why does it matter for federation?

A query plan is the router's step-by-step execution strategy for a federated operation — which subgraphs to call, in what order, and how to join entities across them. Without it, federated queries are a black box: you can't see why something is slow or whether a schema change broke how an operation resolves.

How do you debug a slow federated GraphQL query?

Add X-WG-Include-Query-Plan: true to the request. The router returns the plan in extensions.queryPlan, showing every subgraph hop and fetch order. From there you can see whether a nested entity fetch is hitting subgraphs sequentially and trace the bottleneck to a specific @key or field.

How do you prevent a GraphQL schema change from breaking production queries?

Run router query-plan -fail-on-error in CI, pointing at the proposed execution config and your folder of production operations. If any operation becomes unplannable after the schema change, the build fails before it reaches the router.

How is a GraphQL query plan cached?

The router hashes the incoming operation after parsing and normalization. That hash is the cache key. On a cache hit, the router skips planning entirely and goes straight to execution. The planning cost is paid once per unique operation.

Does requesting a GraphQL query plan add latency to the response?

For a single request, yes — serializing the plan adds some overhead. Leave the header off in production. Use it for debugging, load testing, and CI

How is a GraphQL query plan cache invalidated when the schema changes?

When the router hot-reloads a new execution config, the new instance starts with a cold plan cache. Clients never see stale cached plans from the old schema.

Can you batch-generate GraphQL query plans locally without a control plane connection?

Yes. The CLI takes an execution config file — either pulled from the CDN or generated locally with wgc router compose. No live control plane connection is required.

What does the X-WG-Skip-Loader header do during GraphQL query plan inspection?

It tells the router to plan the operation but skip subgraph execution. You get the full query plan without triggering any real fetches or side effects on downstream services.

Does GraphQL query planning work the same for subscriptions as for queries and mutations?

No. Subscriptions follow a different execution path. The cached planner described here applies to queries and mutations. For subscriptions, refer to the subscriptions section of the router docs.

What router version is required for CI batch generation of GraphQL query plans?

Router version 0.185.0 or later. Earlier versions support per-request plan inspection with X-WG-Include-Query-Plan, but not the batch CLI command.

GraphQL Query Planning | Cosmo by WunderGraph

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

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

Cache hits keep hot paths fast; CI catches schema drift before deploy.

Query planning

Before & After

Before Cosmo	With Cosmo
Slow queries are a black box with no way to see the execution path	`X-WG-Include-Query-Plan` returns the full plan in the response
Schema changes break production queries with no warning	Batch-generate plans in CI, fail the build on unplannable ops
Plans built from scratch on every request	Plans cached by operation hash, planning cost paid once
Performance tuning is guess-and-check against staging	Inspect plans side-by-side for current vs. proposed configs

Plan cache

Plan timing and cache health

Responses can include detailed timing for parse, normalize, validate, and plan phases when tracing or plan headers are enabled; exact fields depend on your router version and configuration. Watch router metrics for plan-cache behavior after deploys (metric names are in the observability docs).

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.

1

2

3

4

5

6

7

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.

Start Free Read the Docs

GraphQL Query Plan Inspection and Validation