Apache DataFusion SQL Query Engine
Add upgrade guide for PhysicalOptimizerRule::optimize_plan (#19030)
Adrian Garcia Badaracco7b4593f36e88
diff --git a/docs/source/library-user-guide/upgrading.md b/docs/source/library-user-guide/upgrading.mdindex d40fee0938..7fb12353b9 100644--- a/docs/source/library-user-guide/upgrading.md+++ b/docs/source/library-user-guide/upgrading.md@@ -332,6 +332,102 @@ let config = FileScanConfigBuilder::new(url, source)**Handling projections in `FileSource`:**+### `PhysicalOptimizerRule::optimize` deprecated in favor of `optimize_plan`++The `PhysicalOptimizerRule` trait has been updated to provide optimizer rules with access to broader session context. A new method `optimize_plan` has been added that accepts an `OptimizerContext` parameter, and the existing `optimize` method has been deprecated.++**Who is affected:**++- Users who have implemented custom `PhysicalOptimizerRule` implementations++**Breaking changes:**++1. **New `optimize_plan` method**: This is the preferred method for implementing optimization rules. It provides access to the full `SessionConfig` through `OptimizerContext`, rather than just `ConfigOptions`.++2. **`optimize` method deprecated**: The old `optimize` method that takes `&ConfigOptions` is now deprecated and will be removed in DataFusion 58.0.0.++**Migration guide:**++If you have a custom `PhysicalOptimizerRule` implementation, update it to implement `optimize_plan` instead of `optimize`:++**Before:**++```rust+use datafusion::physical_optimizer::PhysicalOptimizerRule;+use datafusion_common::config::ConfigOptions;+use datafusion_common::Result;+use datafusion_physical_plan::ExecutionPlan;+use std::sync::Arc;++#[derive(Debug)]+struct MyOptimizerRule;++#[allow(deprecated)]+impl PhysicalOptimizerRule for MyOptimizerRule {+ fn optimize(+ &self,+ plan: Arc<dyn ExecutionPlan>,+ _config: &ConfigOptions,+ ) -> Result<Arc<dyn ExecutionPlan>> {+ // Use config.optimizer, config.execution, etc.+ // ... optimization logic ...+ Ok(plan)+ }++ fn name(&self) -> &str {+ "my_optimizer_rule"+ }++ fn schema_check(&self) -> bool {+ true+ }+}+```++**After:**++```rust+use datafusion::physical_optimizer::{OptimizerContext, PhysicalOptimizerRule};+use datafusion_common::Result;+use datafusion_physical_plan::ExecutionPlan;+use std::sync::Arc;++#[derive(Debug)]+struct MyOptimizerRule;++impl PhysicalOptimizerRule for MyOptimizerRule {+ fn optimize_plan(+ &self,+ plan: Arc<dyn ExecutionPlan>,+ context: &OptimizerContext,+ ) -> Result<Arc<dyn ExecutionPlan>> {+ // Access ConfigOptions through session_config+ let _config = context.session_config().options();+ // Or access extensions through session_config+ let _extensions = context.session_config().extensions();+ // ... optimization logic ...+ Ok(plan)+ }++ fn name(&self) -> &str {+ "my_optimizer_rule"+ }++ fn schema_check(&self) -> bool {+ true+ }+}+```++**What is `OptimizerContext`?**++`OptimizerContext` is a new struct that provides context during physical plan optimization, similar to how `TaskContext` provides context during execution. It wraps `SessionConfig`, giving optimizer rules access to:++- Configuration options via `context.session_config().options()`+- Session extensions via `context.session_config().extensions()`++This enables optimizer rules to access custom extensions registered with the session, which was not possible with the old `&ConfigOptions` parameter.+## DataFusion `51.0.0`### `arrow` / `parquet` updated to 57.0.0