feat: add TableSchemaBuilder; store partition cols as Fields

Introduce `TableSchemaBuilder` as the preferred way to construct a
`TableSchema`. The file schema is the only required input; partition
columns are optional, and the concatenated table schema is computed
exactly once in `build()` (rather than being recomputed on every
incremental setter call).

`TableSchema` now stores its partition columns as `arrow::datatypes::Fields`
(an immutable `Arc<[FieldRef]>`) instead of `Arc<Vec<FieldRef>>`: the
idiomatic Arrow field-list type, a single `Arc<[FieldRef]>` (one fewer
indirection), shareable zero-copy with an existing schema, and -- being
immutable -- it makes the shared-`Arc` mutation panic that motivated recent
changes structurally impossible. `TableSchemaBuilder::with_table_partition_cols`
takes `impl Into<Fields>`, accepting an existing schema's `Fields` without a
`Vec` round-trip.

`TableSchema::table_partition_cols()` (and the delegating
`FileScanConfig::table_partition_cols()`) now return `&Fields`. `Fields`
derefs to `&[FieldRef]`, so iteration/indexing/`len`/`is_empty` callers are
unchanged; only the arrow `FileFormat` path needed `.to_vec()`.

The mutating `TableSchema::with_table_partition_cols` setter is deprecated
in favor of the builder; `new`/`from_file_schema` are kept as conveniences
that route through the builder. Documented in the 55.0.0 upgrade guide.

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

Author: adriangb

datafusion/datasource-arrow/src/file_format.rs

@@ -199,7 +199,7 @@ impl FileFormat for ArrowFormat {
 
         let table_schema = TableSchema::new(
             Arc::clone(conf.file_schema()),
-            conf.table_partition_cols().clone(),
+            conf.table_partition_cols().to_vec(),
         );
 
         let mut source: Arc<dyn FileSource> =

datafusion/datasource/src/file_scan_config/mod.rs

@@ -27,7 +27,7 @@ use crate::{
     file_stream::work_source::SharedWorkSource, source::DataSource,
     statistics::MinMaxStatistics,
 };
-use arrow::datatypes::FieldRef;
+use arrow::datatypes::Fields;
 use arrow::datatypes::{DataType, Schema, SchemaRef};
 use datafusion_common::config::ConfigOptions;
 use datafusion_common::{
@@ -1095,7 +1095,7 @@ impl FileScanConfig {
     }
 
     /// Get the table partition columns
-    pub fn table_partition_cols(&self) -> &Vec<FieldRef> {
+    pub fn table_partition_cols(&self) -> &Fields {
         self.file_source.table_schema().table_partition_cols()
     }
 
@@ -2092,7 +2092,10 @@ mod tests {
             Some(vec![0, 2])
         );
         assert_eq!(new_config.limit, Some(10));
-        assert_eq!(*new_config.table_partition_cols(), partition_cols);
+        assert_eq!(
+            *new_config.table_partition_cols(),
+            Fields::from(partition_cols)
+        );
         assert_eq!(new_config.file_groups.len(), 1);
         assert_eq!(new_config.file_groups[0].len(), 1);
         assert_eq!(

datafusion/datasource/src/mod.rs

@@ -62,7 +62,7 @@ use datafusion_physical_expr::LexOrdering;
 use futures::{Stream, StreamExt};
 use object_store::{GetOptions, GetRange, ObjectStore};
 use object_store::{ObjectMeta, path::Path};
-pub use table_schema::TableSchema;
+pub use table_schema::{TableSchema, TableSchemaBuilder};
 // Remove when add_row_stats is remove
 #[expect(deprecated)]
 pub use statistics::add_row_stats;