register TABLESAMPLE SYSTEM RelationPlanner by default

Out-of-the-box TABLESAMPLE SYSTEM support, achieved through the
RelationPlanner extension API (#17843) instead of baking SQL parsing
into the in-tree SQL planner.

- New `TableSampleSystemPlanner` (RelationPlanner) in datafusion-sql,
  auto-registered via `SessionStateDefaults::default_relation_planners`
  and `SessionStateBuilder::with_default_features`. Lifts
  `TABLESAMPLE SYSTEM(p%) [REPEATABLE(n)]` to the core `Sample`
  extension node; rejects every other form at planning time with a
  clear error and a pointer to RelationPlanner for downstream
  semantics. `register_relation_planner` inserts at the front of the
  chain, so a user-supplied planner can override built-in semantics
  without touching core.

- `DefaultPhysicalPlanner::default()` now pre-registers
  `SamplePhysicalPlanner` so the core `Sample` node lowers to
  `SampleExec` automatically. Callers using
  `with_extension_planners(...)` replace the defaults and need to
  re-add `SamplePhysicalPlanner` if they want sampling.

- Restored the sqllogictest fixture
  (`datafusion/sqllogictest/test_files/tablesample.slt`) — TABLESAMPLE
  now works with the default `SessionContext` that the harness uses.
  Drops the Rust integration test that existed only to register the
  planner manually.

- Drops the redundant `relation_planner/table_sample_system.rs`
  example. The remaining `table_sample.rs` example still demonstrates
  registering a custom RelationPlanner ahead of the built-in one for
  BERNOULLI / ROW / BUCKET semantics — note added in main.rs.

- 7 new ParquetSource unit tests around `try_push_sample` directly
  (cube-root math, file-drop bounds, REPEATABLE determinism, single-
  file short-circuit, target clamping). These exercise the
  `FileSource` API without a SQL or SessionContext layer.

Net effect: `datafusion-cli` users get TABLESAMPLE SYSTEM(p%)
out of the box; downstream extensions can still take over by
registering their own `RelationPlanner` first.

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

Author: adriangb

datafusion-examples/examples/relation_planner/main.rs

@@ -35,7 +35,14 @@
 //!   (file: pivot_unpivot.rs, desc: Implement PIVOT / UNPIVOT)
 //!
 //! - `table_sample`
-//!   (file: table_sample.rs, desc: Implement TABLESAMPLE)
+//!   (file: table_sample.rs, desc: Implement TABLESAMPLE BERNOULLI / ROW / BUCKET via per-batch sampling)
+//!
+//! Note: `TABLESAMPLE SYSTEM(p%)` is supported out of the box by the
+//! built-in `datafusion_sql::sample::TableSampleSystemPlanner`, which is
+//! auto-registered on a default `SessionContext`. The `table_sample`
+//! example below shows how to register a *different* planner for the
+//! row-level forms (`BERNOULLI`, `ROW`, `BUCKET`) that the built-in
+//! intentionally does not handle.
 //!
 //! ## Snapshot Testing
 //!

datafusion/core/src/execution/session_state.rs

@@ -1175,6 +1175,10 @@ impl SessionStateBuilder {
             .get_or_insert_with(Vec::new)
             .extend(SessionStateDefaults::default_expr_planners());
 
+        self.relation_planners
+            .get_or_insert_with(Vec::new)
+            .extend(SessionStateDefaults::default_relation_planners());
+
         self.scalar_functions
             .get_or_insert_with(Vec::new)
             .extend(SessionStateDefaults::default_scalar_functions());

datafusion/core/src/execution/session_state_defaults.rs

@@ -35,7 +35,7 @@ use datafusion_catalog::{MemoryCatalogProvider, MemorySchemaProvider};
 use datafusion_execution::config::SessionConfig;
 use datafusion_execution::object_store::ObjectStoreUrl;
 use datafusion_execution::runtime_env::RuntimeEnv;
-use datafusion_expr::planner::ExprPlanner;
+use datafusion_expr::planner::{ExprPlanner, RelationPlanner};
 use datafusion_expr::registry::ExtensionTypeRegistrationRef;
 use datafusion_expr::{AggregateUDF, HigherOrderUDF, ScalarUDF, WindowUDF};
 use std::collections::HashMap;
@@ -82,6 +82,18 @@ impl SessionStateDefaults {
         default_catalog
     }
 
+    /// Returns the list of default [`RelationPlanner`]s installed by
+    /// [`Self::default_relation_planners`]. Currently this is just the
+    /// built-in `TableSampleSystemPlanner`, which lifts
+    /// `TABLESAMPLE SYSTEM(p%) [REPEATABLE(n)]` into the core `Sample`
+    /// extension node so the `SamplePushdown` rule can absorb it into
+    /// the scan. Other `TABLESAMPLE` flavors are rejected at planning
+    /// time — register a `RelationPlanner` ahead of this one to add
+    /// custom semantics.
+    pub fn default_relation_planners() -> Vec<Arc<dyn RelationPlanner>> {
+        vec![Arc::new(datafusion_sql::sample::TableSampleSystemPlanner)]
+    }
+
     /// returns the list of default [`ExprPlanner`]s
     pub fn default_expr_planners() -> Vec<Arc<dyn ExprPlanner>> {
         let expr_planners: Vec<Arc<dyn ExprPlanner>> = vec![

datafusion/core/src/physical_planner.rs

@@ -258,10 +258,12 @@ pub trait ExtensionPlanner {
 /// ]);
 /// ```
 ///
-/// `Sample` is intentionally not built into [`DefaultPhysicalPlanner`]
-/// by default: that would force callers who use a different SQL
-/// surface (or who don't want any TABLESAMPLE story) to carry the
-/// physical glue. The planner is small enough to opt into.
+/// `SamplePhysicalPlanner` is registered automatically in
+/// [`DefaultPhysicalPlanner::default`] so that `TABLESAMPLE SYSTEM`
+/// works out of the box on a default `SessionContext`. Callers who
+/// supply their own list via [`DefaultPhysicalPlanner::with_extension_planners`]
+/// **replace** the defaults — re-add `SamplePhysicalPlanner` to the
+/// front of their list if they want sampling support.
 ///
 /// [`Sample`]: datafusion_expr::logical_plan::sample::Sample
 /// [`SampleExec`]: datafusion_physical_plan::sample::SampleExec
@@ -326,11 +328,21 @@ impl ExtensionPlanner for SamplePhysicalPlanner {
 /// execute concurrently.
 ///
 /// [`planning_concurrency`]: crate::config::ExecutionOptions::planning_concurrency
-#[derive(Default)]
 pub struct DefaultPhysicalPlanner {
     extension_planners: Vec<Arc<dyn ExtensionPlanner + Send + Sync>>,
 }
 
+impl Default for DefaultPhysicalPlanner {
+    /// Constructs a planner with [`SamplePhysicalPlanner`] pre-registered
+    /// so the core `Sample` extension node lowers without any extra
+    /// wiring on a default `SessionContext`.
+    fn default() -> Self {
+        Self {
+            extension_planners: vec![Arc::new(SamplePhysicalPlanner)],
+        }
+    }
+}
+
 #[async_trait]
 impl PhysicalPlanner for DefaultPhysicalPlanner {
     /// Create a physical plan from a logical plan

datafusion/core/tests/parquet/mod.rs

@@ -57,7 +57,6 @@ mod page_pruning;
 mod row_group_pruning;
 mod schema;
 mod schema_coercion;
-mod tablesample;
 mod utils;
 
 #[cfg(test)]