docs: add incremental query planner page - #10345
Merged
Merged
Conversation
…grams The router had no signal for whether the incremental planner's fuel budget was cutting searches short. A search that exhausts its fuel still returns a plan, so the planning outcome reads as success either way. The BULB search now reports the effort spent after its first complete plan, which QueryPlanningStatistics carries as fuel_consumed and fuel_remaining. Mutations run one search per top-level field, each with its own budget, so the statistics keep the search that consumed the most. The router records both as apollo.router.query_planning.plan.fuel_consumed and apollo.router.query_planning.plan.fuel_remaining when the incremental planner is enabled. Fuel values aren't durations, so the global histogram buckets would put nearly every sample in the overflow bucket. Both histograms default to decade buckets from 0 to 1,000,000 that don't depend on the fuel setting, keeping series comparable when it changes. A user view still overrides them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The fuel histograms show how often the budget binds across traffic but not which operations hit it. Recording fuel_consumed and fuel_remaining on the query_planning span puts them in the same trace as the operation name. tracing drops records for fields a span didn't declare, so the span is now built by query_planning_span(), which declares both fields and lets the test exercise the production declaration. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…stics cases Planner config doesn't affect composition, but planner!() generates a fixture per test name, so the three fuel statistics tests carried three identical supergraph files. One test now composes once and builds a planner per case. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds a page under Query Planning covering how the incremental planner differs from the default planner, its configuration and tuning, behavior changes when enabled, the fuel metrics, and rollout. Adds the incremental_planner block to the shared supergraph config references. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
✅ Docs preview readyThe preview is ready to be viewed. View the preview File Changes 2 new, 44 changed, 0 removedBuild ID: d5f6534459e3616f91a24a71 URL: https://www.apollographql.com/docs/deploy-preview/d5f6534459e3616f91a24a71
|
Contributor
|
This pull request does not currently match the merge queue conditions, so it cannot be queued from here. The box comes back if it matches again. |
tninesling
commented
Oct 1, 2026
Reframe the planner as drafting a plan and then optimizing it within the fuel budget, and describe backtracking out of dead ends while drafting. Note the memory and backtracking trade-off for beam_width. Drop the connector expansion detail, the subgraph operation note that applies to both planners, and the rollout section. Describe what evaluated_plans and evaluated_paths count for this planner. List enabled first in the shared config references, and apply style fixes for contractions, may, and since. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds a section covering decisions and options, how options are scored and ranked, discrepancy passes, what fuel counts, timeout behavior before and after the draft, and a worked example where a second pass replaces a three-fetch greedy draft with a two-fetch plan. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from
tninesling/inc-planner-fuel-metrics
to
dev-v3.x
October 2, 2026 15:34
…anner-docs # Conflicts: # apollo-router/src/query_planner/query_planner_service.rs
The doc said "effort budget" in the frontmatter description, the intro paragraph, and steps 2-3 of "How it differs from the default planner," but switched to "fuel budget" everywhere else (Decisions and options, Fuel and timeout, the config table). "Fuel" is the only term users actually see in router.yaml and in the fuel_consumed/fuel_remaining metrics and span attributes, so standardize on it throughout. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The four-step tie-break rule (@provides, current subgraph, entity hops by key size, then schema order) was packed into one run-on sentence, making the order easy to misread. Pull it out into a numbered list. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
"Discrepancies and passes" used "beam" and "discrepancy" before ever explaining what they meant, packed into a single dense sentence with the pass-schedule explanation. Give each term its own sentence: what a beam is, what beam_width controls, and what choosing a discrepancy means and why the search does it. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
|
@tninesling I pushed minor changes but please review for accuracy! Please merge when ready, though sooner the better :) |
…o clarify that there can be multiple beams per decision, and discrepancies are outside the first beam
dcwalter
approved these changes
Oct 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a public docs page for the incremental query planner under Query Planning. It covers:
beam_width,fuel, andtimeoutoptions, with tuning guidance.experimental_*limits.query_planningspan attributes from feat(incremental-planner): add fuel metrics and span attributes #10344.Also adds the
incremental_plannerblock to the sharedsupergraphconfig references and adds the page to the sidebar.Stacked on #10344.
Checklist
Exceptions
Docs only, so no changeset or tests. The router's YAML examples on the page were checked with
router config validate.🤖 Generated with Claude Code