Skip to content

docs: Apollo-Expose-Query-Plan header #7147

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
dariuszkuc merged 2 commits into from
May 23, 2025
Merged

docs: Apollo-Expose-Query-Plan header #7147

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
113b0b5
DOC-414 update Apollo-Expose-Query-Plan header doc
shorgi Mar 28, 2025
847bcf3
copyedit to align with https://github.com/apollographql/federation/pu…
shorgi Apr 5, 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
16 changes: 12 additions & 4 deletions docs/source/routing/observability/debugging-subgraph-requests.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,25 @@ redirectFrom:
- /technotes/TN0039-debugging-subgraph-requests/
---

As your graph grows, you may need to debug a problematic query for one reason or another. The GraphOS Router and `@apollo/gateway` both serve as an entry point into your federated graph and offer ways to debug requests.
As your graph grows, you may need to debug a problematic query for one reason or another. The Apollo Router (Apollo GraphOS Router or Apollo Router Core) and `@apollo/gateway` both serve as an entry point into your federated graph and offer ways to debug requests.

Each client request goes through a process called [query planning](/graphos/explorer/additional-features/#query-plans-for-supergraphs) that generates the subgraph requests to execute. You can log out the query plan in both the router and gateway.

## Output query plans with headers

With router v0.16.0+ and `@apollo/gateway` v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions:
With the Apollo GraphOS Router or Apollo Router Core 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](/graphos/routing/performance/caching/in-memory)

### Legacy header options

In older versions of the 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
- 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

## Log router subgraph calls
Expand Down