refactor(spark): rename LegacyMode to PerPartitionMode

The "legacy" naming implied a deprecated path, but this is all new, unreleased code with no prior path. Rename the scan mode and scrub "legacy" wording from comments to describe what the mode actually does. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
timsaucer · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
commit 4b997345099a39025acf07269455109628370664
diff --git a/spark/bridge/src/scan.rs b/spark/bridge/src/scan.rs
@@ -38,9 +38,8 @@
 //!     succeeds when every operator in that partition's pipeline supports
 //!     repeated `execute()` — stateless scans do, `RepartitionExec`
 //!     pipelines do not;
-//!   - [`execute_stream`] — the whole plan as one stream (legacy
-//!     per-partition payload mode, where the provider itself is the task's
-//!     slice);
+//!   - [`execute_stream`] — the whole plan as one stream (per-partition
+//!     mode, where the provider itself is the task's slice);
 //!   - [`close_scan`] — drop the plan. The single unsafe interleaving is
 //!     closing a handle that still has an in-flight call; the Java consumer
 //!     (the shared-scan cache) prevents it with a refcount covering every
@@ -282,7 +281,7 @@ pub fn execute_stream_partition(
     })
 }
 
-/// Whole-plan stream for legacy per-partition payload mode (the provider
+/// Whole-plan stream for per-partition mode (the provider
 /// itself is the task's slice, so all plan partitions merge into one reader).
 pub fn execute_stream(env: &mut JNIEnv, handle: jlong, ffi_stream_addr: jlong) {
     try_unwrap_or_throw(env, (), |_env| -> JniResult<()> {

diff --git a/spark/src/main/java/io/datafusion/spark/ScanBackend.java b/spark/src/main/java/io/datafusion/spark/ScanBackend.java
@@ -70,7 +70,7 @@ long createScan(
 
   /**
    * Stream the WHOLE plan (all partitions coalesced) into the caller-allocated {@code
-   * FFI_ArrowArrayStream} at {@code ffiStreamAddr}. Used by legacy per-partition payload mode.
+   * FFI_ArrowArrayStream} at {@code ffiStreamAddr}. Used by per-partition mode.
    */
   void executeStream(long scanHandle, long ffiStreamAddr);
 

diff --git a/spark/src/main/scala/io/datafusion/spark/DatafusionBatch.scala b/spark/src/main/scala/io/datafusion/spark/DatafusionBatch.scala
@@ -26,7 +26,7 @@ import org.apache.spark.sql.connector.read.{Batch, InputPartition, PartitionRead
 
 /**
  * Spark `Batch` for a DataFusion-backed scan. Driver-side partition planning:
- *   - [[LegacyMode]]: one task per `PartitionInfo` (resolved by [[DatafusionScanBuilder]]); when
+ *   - [[PerPartitionMode]]: one task per `PartitionInfo` (resolved by [[DatafusionScanBuilder]]); when
  *     the bridge reported a partitioning and every entry carries key values, tasks implement
  *     `HasPartitionKey` so Spark can actually use the `KeyGroupedPartitioning`.
  *   - [[SharedScanMode]]: one task per DataFusion plan partition index.
@@ -38,7 +38,7 @@ class DatafusionBatch(val scan: DatafusionScan) extends Batch {
     val filterBytes: Array[Array[Byte]] = scan.pushedPredicateBytes
 
     scan.mode match {
-      case LegacyMode(partitions, reported) =>
+      case PerPartitionMode(partitions, reported) =>
         val keyed = DatafusionBatch.validateKeyedState(scan.factoryFqcn, partitions, reported)
         partitions.iterator.map { p =>
           val base = DatafusionInputPartition(

diff --git a/spark/src/main/scala/io/datafusion/spark/DatafusionColumnarPartitionReader.scala b/spark/src/main/scala/io/datafusion/spark/DatafusionColumnarPartitionReader.scala
@@ -26,7 +26,7 @@ import org.apache.spark.sql.types.StructType
 import org.apache.spark.sql.vectorized.ColumnarBatch
 
 /**
- * Per-task columnar reader for the per-partition payload (legacy) path. Lifecycle:
+ * Per-task columnar reader for the per-partition path. Lifecycle:
  *
  *   1. Reflectively instantiate the bridge's `BridgeProviderFactory` (no-arg) and take its
  *      [[ScanBackend]].

diff --git a/spark/src/main/scala/io/datafusion/spark/DatafusionInputPartition.scala b/spark/src/main/scala/io/datafusion/spark/DatafusionInputPartition.scala
@@ -29,7 +29,7 @@ import org.apache.spark.sql.connector.read.{HasPartitionKey, InputPartition}
 sealed trait DatafusionPartition extends InputPartition
 
 /**
- * Per-task payload for the per-partition payload (legacy) read path.
+ * Per-task payload for the per-partition read path.
  *
  *  - `factoryFqcn`: fully-qualified class name of the bridge's `BridgeProviderFactory`. The
  *    executor reflectively instantiates this and calls
@@ -59,7 +59,7 @@ final case class DatafusionInputPartition(
 }
 
 /**
- * Legacy-path payload that additionally carries this partition's key values, precomputed
+ * Per-partition payload that additionally carries this partition's key values, precomputed
  * driver-side into an [[InternalRow]]. Emitted by [[DatafusionBatch]] when the bridge reported a
  * partitioning AND every `PartitionInfo` carries `partitionKeyValues` — implementing
  * [[HasPartitionKey]] is what makes the reported `KeyGroupedPartitioning` visible to Spark 3.3+

diff --git a/spark/src/main/scala/io/datafusion/spark/DatafusionScan.scala b/spark/src/main/scala/io/datafusion/spark/DatafusionScan.scala
@@ -39,7 +39,7 @@ sealed trait DatafusionScanMode extends Serializable
  * from that entry's `partitionBytes`. `reported` is the bridge's optional partitioning
  * declaration (may be null).
  */
-final case class LegacyMode(
+final case class PerPartitionMode(
     partitions: Array[PartitionInfo],
     reported: ReportedPartitioning
 ) extends DatafusionScanMode
@@ -62,7 +62,7 @@ final case class SharedScanMode(
  * executor applies natively via `ScanBackend.createScan`, and the driver-resolved
  * [[DatafusionScanMode]].
  *
- * Legacy mode with a bridge-declared [[ReportedPartitioning]] surfaces `KeyGroupedPartitioning`
+ * Per-partition mode with a bridge-declared [[ReportedPartitioning]] surfaces `KeyGroupedPartitioning`
  * via `SupportsReportPartitioning`; note Spark 3.3+ only consumes it when the input partitions
  * also implement `HasPartitionKey` (see [[DatafusionBatch]]). Shared-scan mode always reports
  * `UnknownPartitioning` — DataFusion-native partitions carry no key contract.
@@ -82,7 +82,7 @@ class DatafusionScan(
 
   override def description(): String = {
     val modeDesc = mode match {
-      case LegacyMode(partitions, reported) =>
+      case PerPartitionMode(partitions, reported) =>
         s"mode=per-partition, partitions=${partitions.length}," +
           s" reportedPartitioning=${if (reported == null) "unknown" else "key-grouped"}"
       case SharedScanMode(scanId, n, _, _) =>
@@ -95,7 +95,7 @@ class DatafusionScan(
   override def toBatch: Batch = new DatafusionBatch(this)
 
   override def outputPartitioning(): Partitioning = mode match {
-    case LegacyMode(partitions, reported) =>
+    case PerPartitionMode(partitions, reported) =>
       if (reported == null) new UnknownPartitioning(partitions.length)
       else new KeyGroupedPartitioning(reported.keys().toArray, partitions.length)
     case SharedScanMode(_, numPartitions, _, _) =>

diff --git a/spark/src/main/scala/io/datafusion/spark/DatafusionScanBuilder.scala b/spark/src/main/scala/io/datafusion/spark/DatafusionScanBuilder.scala
@@ -87,7 +87,7 @@ class DatafusionScanBuilder(
     val factory = instantiateFactory(factoryFqcn)
     val mode: DatafusionScanMode =
       if (factory.sharedScan(optionsBytes)) buildSharedScanMode()
-      else buildLegacyMode(factory)
+      else buildPerPartitionMode(factory)
     new DatafusionScan(
       factoryFqcn,
       optionsBytes,
@@ -99,15 +99,15 @@ class DatafusionScanBuilder(
     )
   }
 
-  private def buildLegacyMode(factory: BridgeProviderFactory): LegacyMode = {
+  private def buildPerPartitionMode(factory: BridgeProviderFactory): PerPartitionMode = {
     val partitions: Array[PartitionInfo] =
       factory.listPartitions(optionsBytes, pushedBytes)
     if (partitions == null || partitions.isEmpty) {
       throw new IllegalStateException(
         s"BridgeProviderFactory '$factoryFqcn' returned no partitions to scan"
       )
     }
-    LegacyMode(partitions, factory.reportPartitioning(optionsBytes))
+    PerPartitionMode(partitions, factory.reportPartitioning(optionsBytes))
   }
 
   /**