feat: SamplePushdown rule + Sample logical/physical nodes for parquet

Adds the infrastructure for pushing TABLESAMPLE-shaped sampling into
file sources, with parquet as the first absorbing source. There is
no SQL surface yet; this commit only ships the primitives. Wiring a
RelationPlanner / ExtensionPlanner so it works out of the box from
SQL is a follow-up.

- `Sample` `UserDefinedLogicalNodeCore` extension node in
  `datafusion-expr` (`logical_plan/sample.rs`). Schema-preserving;
  validates `fraction ∈ (0, 1]`. Currently encodes
  `SampleMethod::System` only.
- `SampleExec` placeholder in `datafusion-physical-plan`. Errors at
  `execute` (it's a marker — the `SamplePushdown` rule is expected
  to remove it). Implements filter / sort pushdown passthrough so
  unrelated optimizer rules see straight through it.
- New `try_push_sample` method on `ExecutionPlan` and `FileSource`,
  returning `Absorbed { inner }` / `Passthrough` / `Unsupported
  { reason }`. Default is `Unsupported`; per-node `Passthrough`
  overrides on filter, projection, coalesce_batches,
  coalesce_partitions, repartition, and non-fetch sort.
- `ParquetSource::try_push_sample` runs the (intentionally private)
  hierarchical block-level reduction across files / row groups /
  rows, with adaptive collapse when an axis can't reduce. Coordinates
  with the opener via a `pub(crate)` `system_target_remaining` field
  on `ParquetSampling`. Single-file, single-row-group inputs hit
  ~p × N rows instead of undershooting at p^(1/3) × N.
- `SamplePushdown` optimizer rule (between `PushdownSort` and
  `EnsureCooperative`) walks top-down. On `Absorbed` it replaces
  `SampleExec` with the rebuilt source; on `Passthrough` it pushes
  through the single-child node and recurses; on `Unsupported` it
  errors at planning time with `"TABLESAMPLE is not supported for
  this source"`. There is intentionally no generic post-scan
  `SampleExec` yet.
- EXPLAIN visibility: `ParquetSource::fmt_extra` surfaces
  `sample_system_target_remaining` when set.
- `optimizer_rule_reference.md` updated to list `SamplePushdown` in
  the documented rule order.
- `explain.slt` updated with `physical_plan after SamplePushdown SAME
  TEXT AS ABOVE` lines under each verbose-explain test.

Tests: 7 unit tests on `ParquetSource::try_push_sample` covering the
pushdown contract (full / single-file / multi-file / target clamping
/ REPEATABLE determinism / multi-file rounding compensation), and 2
opener end-to-end tests covering the adaptive split for single vs
multi row group inputs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: adriangb

datafusion/core/src/optimizer_rule_reference.md

@@ -88,6 +88,7 @@ in multiple phases.
 | 17    | `TopKRepartition`              | -                       | Pushes TopK below hash repartition when the partition key is a prefix of the sort key.                       |
 | 18    | `ProjectionPushdown`           | late pass               | Runs projection pushdown again after limit and TopK rewrites expose new pruning opportunities.               |
 | 19    | `PushdownSort`                 | -                       | Pushes sort requirements into data sources that can already return sorted output.                            |
-| 20    | `EnsureCooperative`            | -                       | Wraps non-cooperative plan parts so long-running tasks yield fairly.                                         |
-| 21    | `FilterPushdown(Post)`         | post-optimization phase | Pushes dynamic filters at the end of optimization, after plan references stop moving.                        |
-| 22    | `SanityCheckPlan`              | -                       | Validates that the final physical plan meets ordering, distribution, and infinite-input safety requirements. |
+| 20    | `SamplePushdown`               | -                       | Pushes `TABLESAMPLE` into the source; errors at planning time if the sample can't be absorbed.               |
+| 21    | `EnsureCooperative`            | -                       | Wraps non-cooperative plan parts so long-running tasks yield fairly.                                         |
+| 22    | `FilterPushdown(Post)`         | post-optimization phase | Pushes dynamic filters at the end of optimization, after plan references stop moving.                        |
+| 23    | `SanityCheckPlan`              | -                       | Validates that the final physical plan meets ordering, distribution, and infinite-input safety requirements. |

datafusion/datasource-parquet/src/mod.rs

@@ -33,6 +33,7 @@ mod page_filter;
 mod reader;
 mod row_filter;
 mod row_group_filter;
+mod sampling;
 mod sort;
 pub mod source;
 mod supported_predicates;