Native Query Planner
Run the Rust-native query planner in GraphOS Router
Learn about the Rust-native query planner in GraphOS Router. The planner is GA as of v1.59.0.
Background about query planner implementations
In v1.49.0 the router introduced a query planner implemented natively in Rust. This native query planner improves the overall performance and resource utilization of query planning. It exists alongside the legacy JavaScript implementation that uses the V8 JavaScript engine, and it will eventually replace the legacy implementation.
As of v1.59.0, the native query planner is the default planner in the router. As part of this, Deno, and by extension v8, are no longer initialized at router startup. The legacy implementation is deprecated, but it is still possible to configure the router to run with the legacy query planner.
Configuring query planning
You can configure the experimental_query_planner_mode
option in your router.yaml
to set the query planner to run.
The experimental_query_planner_mode
option has the following supported modes:
new
(default) - enables only the new Rust-native query plannerlegacy
- enables only the legacy JavaScript query planner. The legacy planner is deprecated and will be removed in the next router release.both_best_effort
- enables both new and legacy query planners for comparison. The legacy query planner is used for execution.
experimental_query_planner_mode
will be removed in the next router release.
Comparing query planner implementations
As part of the effort to ensure correctness and stability of the new query planner, starting in v1.53.0 the router enables both the new and legacy planners and runs them in parallel to compare their results by default. After their comparison, the router discards the native query planner's results and uses only the legacy planner to execute requests. The native query planner uses a single thread in the cold path of the router. It has a bounded queue of ten queries. If the queue is full, the router simply does not run the comparison to avoid excessive resource consumption.
Metrics for native query planner
When running both query planners for comparison with experimental_query_planner_mode: both_best_effort
, the following metrics track mismatches and errors:
apollo.router.operations.query_planner.both
with the following attributes:generation.is_matched
(bool)generation.js_error
(bool)generation.rust_error
(bool)
apollo.router.query_planning.plan.duration
with the following attributes to differentiate between planners:planner
(rust | js)
Federation v1 composed supergraphs
The native query planner does not support supergraphs composed with Federation v1, so the router will fallback to the legacy planner for any variants still using a Federation v1 supergraph in v1.59.0. Users are highly encouraged to recompose with Federation v2. Federation v1 subgraphs continue to be supported.
Customers that are on Federation v1 composed supergraph should see this as an info level log on startup:
12024-12-05T10:13:39.760333Z INFO Falling back to the legacy query planner: failed to initialize the query planner: Supergraphs composed with federation version 1 are not supported. Please recompose your supergraph with federation version 2 or greater