doc: reconcile native query planner page (#6477)

docs/source/routing/query-planning/native-query-planner.mdx

@@ -0,0 +1,56 @@
+---
+title: Native Query Planner
+subtitle: Run the Rust-native query planner in GraphOS Router
+minVersion: 1.49.0
+redirectFrom:
+  - /router/configuration/experimental_query_planner_mode
+  - /router/executing-operations/native-query-planner
+---
+
+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](/graphos/routing/about-router#query-planning) 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](https://www.apollographql.com/docs/graphos/reference/migration/to-federation-version-2#step-2-configure-your-composition-method).
+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
+2024-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
+```