Skip to content

[docs] Document new dry-run query plan header #3226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smyrick merged 2 commits into from
Mar 28, 2025
Merged

[docs] Document new dry-run query plan header #3226

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e94133
Document new dry-run query plan header
smyrick Mar 10, 2025
ae6a514
Update docs/source/reference/federation/query-plans.mdx
smyrick Mar 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/source/schema-design/federated-schemas/reference/query-plans.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -489,14 +489,22 @@ You can view the query plan for a particular operation in any of the following w

### Outputting query plans with headers

With [the Apollo Router Core](https://github.com/apollographql/router) v0.16.0+ and [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway/) v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions:
With [the Apollo Router Core](https://github.com/apollographql/router) v1.61.0+ or v2.x+, you can pass the following header to return the query plans in the GraphQL response extensions:

- The header `Apollo-Expose-Query-Plan` must be set with one of the following options:
- A value of `true` returns a human-readable string and JSON blob of the query plan
- A value of `dry-run` will generate the query plan and then abort execution. This can be helpful if you want to warm up any internal or external [query plan caches](https://www.apollographql.com/docs/graphos/routing/performance/caching/in-memory)

### Legacy header options

In older versions of [the Apollo Router Core](https://github.com/apollographql/router) v0.16.0+ and [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway/) v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions:

- Including the `Apollo-Query-Plan-Experimental` header returns the query plan in the response extensions
- Additionally including the `Apollo-Query-Plan-Experimental-Format` header with one of the supported options changes the output format:
- A value of `prettified` returns a human-readable string of the query plan
- A value of `internal` returns a JSON representation of the query plan

### Outputting query plans with `@apollo/gateway`
#### Manually outputting query plans with `@apollo/gateway`

Your gateway can output the query plan for each incoming operation as it's calculated. To do so, add the following to the file where you initalize your `ApolloGateway` instance:

Expand Down