docs: upgrade guide for FilterConjunct in physical filter pushdown

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: adriangb

docs/source/library-user-guide/upgrading/56.0.0.md

@@ -695,3 +695,92 @@ impl FileSource for MySource {
     // ...
 }
 ```
+
+### Physical filter pushdown passes `FilterConjunct`s
+
+Physical filter pushdown now carries each filter as a `FilterConjunct` (from
+`datafusion_physical_expr::filter`). A `FilterConjunct` is a boolean
+`PhysicalExpr` together with its properties. At this time, the only property
+is `is_optional`: an optional conjunct (for example, a dynamic filter from a
+hash join, TopK or aggregate) can be skipped without an effect on the query
+result. The properties now move through pushdown together with each filter.
+
+These public APIs changed:
+
+- `ExecutionPlan::gather_filters_for_pushdown` receives
+  `parent_filters: Vec<FilterConjunct>` instead of
+  `Vec<Arc<dyn PhysicalExpr>>`.
+- `ChildFilterDescription::from_child`, `from_child_with_column_mapping`,
+  `from_child_with_allowed_indices`, `all_unsupported`,
+  `FilterDescription::from_children` and `FilterDescription::all_unsupported`
+  take `FilterConjunct`s.
+- `PushedDownPredicate::predicate` is a `FilterConjunct`.
+  `PushedDownPredicate::supported`, `PushedDownPredicate::unsupported` and
+  `PushedDown::wrap_expression` take a `FilterConjunct`, and
+  `PushedDownPredicate::into_inner` returns one.
+- `ChildFilterPushdownResult::filter` is a `FilterConjunct`.
+- `DataSource::try_pushdown_filters` and `FileSource::try_pushdown_filters`
+  are deprecated. Implement and call `try_pushdown_filter` instead. It takes a
+  `PhysicalFilter` (an ordered list of `FilterConjunct`s).
+- `FileSource` has a new `physical_filter` method. `ParquetSource::physical_filter`
+  now comes from this trait method and returns an owned `PhysicalFilter`.
+
+**Migration guide:**
+
+In `gather_filters_for_pushdown`, change the type of `parent_filters`. Use
+`FilterConjunct::expr` to read the expression. When a node rewrites a parent
+filter (for example, to remap its columns), use `FilterConjunct::with_expr` to
+keep the properties of the filter:
+
+```rust,ignore
+fn gather_filters_for_pushdown(
+    &self,
+    _phase: FilterPushdownPhase,
+    parent_filters: Vec<FilterConjunct>,
+    _config: &ConfigOptions,
+) -> Result<FilterDescription> {
+    let parent_filters = parent_filters
+        .into_iter()
+        .map(|filter| {
+            let rewritten = rewrite(filter.expr())?;
+            // Before: PushedDownPredicate::supported(rewritten)
+            Ok(PushedDownPredicate::supported(filter.with_expr(rewritten)))
+        })
+        .collect::<Result<Vec<_>>>()?;
+    // ...
+}
+```
+
+Code that makes a filter from an expression can use
+`FilterConjunct::required(expr)` or `FilterConjunct::from(expr)`.
+
+**Custom `DataSource` and `FileSource` implementations: check them manually.**
+The compiler does not warn when an implementation overrides a deprecated
+trait method. It warns only when code calls the method. Thus, a source that
+overrides `try_pushdown_filters` compiles without a warning. Such a source
+continues to work: the default `try_pushdown_filter` calls
+`try_pushdown_filters` with the expressions. But the source does not get the
+conjunct properties, and it applies optional conjuncts as required conjuncts.
+The deprecated method will be removed in a future release, so search your code
+for `fn try_pushdown_filters` and migrate each implementation now.
+
+To migrate, rename `try_pushdown_filters` to `try_pushdown_filter` and read
+the expressions from the `PhysicalFilter`:
+
+```rust,ignore
+fn try_pushdown_filter(
+    &self,
+    filter: PhysicalFilter,
+    config: &ConfigOptions,
+) -> Result<FilterPushdownPropagation<Arc<dyn FileSource>>> {
+    let filters: Vec<Arc<dyn PhysicalExpr>> = filter
+        .into_conjuncts()
+        .into_iter()
+        .map(FilterConjunct::into_expr)
+        .collect();
+    // ... the previous body of `try_pushdown_filters` ...
+}
+```
+
+A source that keeps the conjuncts (and thus their properties) should also
+implement `FileSource::physical_filter`.