Since 1.49.0

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 planner

  • legacy - 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:

Bash
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
Feedback

Edit on GitHub

Forums