This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 8f03078eb6 docs + feature : Introduce schemaBuilder::project + make
better docs (#10924)
8f03078eb6 is described below
commit 8f03078eb6c9f5e92bad13c43bdaf2bd900b14db
Author: RIchard Baah <[email protected]>
AuthorDate: Tue Sep 1 14:17:45 2026 -0400
docs + feature : Introduce schemaBuilder::project + make better docs
(#10924)
# Which issue does this PR close?
<!--
We generally require a GitHub issue to be filed for all bug fixes and
enhancements and this helps us generate change logs for our releases.
You can link an issue to this PR using the GitHub syntax.
-->
- Closes #6575.
# Rationale for this change
`SchemaBuilder` had no doc examples, making it hard to discover the
common pattern of deriving a new schema from an existing one (copy all
fields and metadata, push new columns, finish). There was also no
built-in way to reorder fields or select a subset without manually
removing and re-inserting them.
<!--
Why are you proposing this change? If this is already explained clearly
in the issue then this section is not needed.
Explaining clearly why changes are proposed helps reviewers understand
your changes and offer better suggestions for fixes.
-->
# What changes are included in this PR?
- Added doc examples on SchemaBuilder showing how to build a schema from
scratch, extend an existing schema with new fields (carrying metadata
over), and replace a single field in-place via field_mut.
- Added `SchemaBuilder::project(indices: &[usize]) -> Result<Schema,
ArrowError>`; consumes the builder and returns a schema containing only
the fields at the given indices, in the given order. Rejects
out-of-bounds or repeated indices with a descriptive error.
- Added two unit tests: `test_schema_builder_project` (reorder + subset
happy paths) and `test_schema_builder_project_errors` (out-of-bounds and
repeated-index error paths).
<!--
There is no need to duplicate the description in the issue here but it
is sometimes worth providing a summary of the individual changes in this
PR.
-->
# Are these changes tested?
yes, doc test + existing/new unit test pass
<!--
We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
2. Serve as another way to document the expected behavior of the code
If tests are not included in your PR, please explain why (for example,
are they covered by existing tests)?
If this PR claims a performance improvement, please include evidence
such as benchmark results.
-->
# Are there any user-facing changes?
yes, new method + better docs!
<!--
If there are user-facing changes then we may require documentation to be
updated before approving the PR.
If there are any breaking changes to public APIs, please call them out.
-->
---
arrow-schema/src/schema.rs | 178 ++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 177 insertions(+), 1 deletion(-)
diff --git a/arrow-schema/src/schema.rs b/arrow-schema/src/schema.rs
index 47d031deab..85f4d59099 100644
--- a/arrow-schema/src/schema.rs
+++ b/arrow-schema/src/schema.rs
@@ -23,7 +23,46 @@ use crate::error::ArrowError;
use crate::field::Field;
use crate::{DataType, FieldRef, Fields, Metadata};
-/// A builder to facilitate building a [`Schema`] from iteratively from
[`FieldRef`]
+/// A builder to facilitate building a [`Schema`] iteratively from [`FieldRef`]
+///
+/// # Examples
+///
+/// Build a schema from scratch:
+///
+/// ```
+/// # use arrow_schema::*;
+/// let schema = {
+/// let mut builder = SchemaBuilder::new();
+/// builder.push(Field::new("id", DataType::Int64, false));
+/// builder.push(Field::new("name", DataType::Utf8, true));
+/// builder.finish()
+/// };
+/// assert_eq!(schema.fields().len(), 2);
+/// ```
+///
+/// Derive a new schema from an existing one, keeping all fields and metadata
+/// while appending new columns:
+///
+/// ```
+/// # use arrow_schema::*;
+/// let base = Schema::new_with_metadata(
+/// vec![
+/// Field::new("id", DataType::Int64, false),
+/// Field::new("name", DataType::Utf8, true),
+/// ],
+/// [("created_by", "myapp")],
+/// );
+///
+/// // Build a new schema that extends `base` with an extra field.
+/// let mut builder = SchemaBuilder::from(&base); // copies all fields *and*
metadata.
+/// builder.push(Field::new("score", DataType::Float64, true));
+/// let extended = builder.finish();
+///
+/// assert_eq!(extended.fields().len(), 3);
+/// assert_eq!(extended.field(0).name(), "id"); // original fields
preserved
+/// assert_eq!(extended.field(2).name(), "score"); // new field appended
+/// assert_eq!(extended.metadata()["created_by"], "myapp"); // metadata
carried over
+/// ```
#[derive(Debug, Default)]
pub struct SchemaBuilder {
fields: Vec<FieldRef>,
@@ -69,6 +108,25 @@ impl SchemaBuilder {
/// Returns a mutable reference to the [`FieldRef`] at index `idx`
///
+ /// # Example
+ ///
+ /// ```
+ /// # use std::sync::Arc;
+ /// # use arrow_schema::*;
+ /// let original = Schema::new(vec![
+ /// Field::new("id", DataType::Int32, false),
+ /// Field::new("value", DataType::Utf8, true),
+ /// ]);
+ ///
+ /// let mut builder = SchemaBuilder::from(&original);
+ /// // Widen the "id" column from Int32 to Int64
+ /// *builder.field_mut(0) = Arc::new(Field::new("id", DataType::Int64,
false));
+ /// let widened = builder.finish();
+ ///
+ /// assert_eq!(widened.field(0).data_type(), &DataType::Int64);
+ /// assert_eq!(widened.field(1).name(), "value"); // unchanged
+ /// ```
+ ///
/// # Panics
///
/// Panics if index out of bounds
@@ -119,6 +177,72 @@ impl SchemaBuilder {
metadata: self.metadata,
}
}
+
+ /// Consume this [`SchemaBuilder`] yielding a [`Schema`] with fields
reordered
+ /// or subsetted according to `indices`.
+ ///
+ /// Fields appear in the output in the order given by `indices`. Metadata
is
+ /// carried over from the builder unchanged.
+ ///
+ /// # Errors
+ ///
+ /// Returns an error if any index is out of bounds or if any index is
repeated.
+ ///
+ /// # Example: reorder fields
+ ///
+ /// ```
+ /// # use arrow_schema::*;
+ /// let schema = Schema::new(vec![
+ /// Field::new("id", DataType::Int64, false),
+ /// Field::new("name", DataType::Utf8, true),
+ /// Field::new("score", DataType::Float64, true),
+ /// ]);
+ ///
+ /// let reordered = SchemaBuilder::from(&schema).project(&[2, 0,
1]).unwrap();
+ /// assert_eq!(reordered.field(0).name(), "score");
+ /// assert_eq!(reordered.field(1).name(), "id");
+ /// assert_eq!(reordered.field(2).name(), "name");
+ /// ```
+ ///
+ /// # Example: select a subset of fields
+ ///
+ /// ```
+ /// # use arrow_schema::*;
+ /// let schema = Schema::new(vec![
+ /// Field::new("id", DataType::Int64, false),
+ /// Field::new("name", DataType::Utf8, true),
+ /// Field::new("score", DataType::Float64, true),
+ /// ]);
+ ///
+ /// let subset = SchemaBuilder::from(&schema).project(&[0, 2]).unwrap();
+ /// assert_eq!(subset.fields().len(), 2);
+ /// assert_eq!(subset.field(0).name(), "id");
+ /// assert_eq!(subset.field(1).name(), "score");
+ /// ```
+ pub fn project(self, indices: &[usize]) -> Result<Schema, ArrowError> {
+ let num_fields = self.fields.len();
+ let mut seen = std::collections::HashSet::new();
+ for &idx in indices {
+ if idx >= num_fields {
+ return Err(ArrowError::SchemaError(format!(
+ "project index {idx} out of bounds, schema has
{num_fields} fields"
+ )));
+ }
+ if !seen.insert(idx) {
+ return Err(ArrowError::SchemaError(format!(
+ "project index {idx} is repeated"
+ )));
+ }
+ }
+ let fields: Vec<FieldRef> = indices
+ .iter()
+ .map(|&idx| self.fields[idx].clone())
+ .collect();
+ Ok(Schema {
+ fields: fields.into(),
+ metadata: self.metadata,
+ })
+ }
}
impl From<&Fields> for SchemaBuilder {
@@ -1429,4 +1553,56 @@ mod tests {
assert_eq!(out.metadata["k"], "v");
assert_eq!(out.metadata["key"], "value");
}
+
+ #[test]
+ fn test_schema_builder_project() {
+ let schema = Schema::new_with_metadata(
+ vec![
+ Field::new("a", DataType::Int32, false),
+ Field::new("b", DataType::Utf8, true),
+ Field::new("c", DataType::Float64, true),
+ Field::new("d", DataType::Boolean, false),
+ ],
+ [("meta", "data")],
+ );
+
+ // Reorder: reverse field order, keeping all fields.
+ let reordered = SchemaBuilder::from(&schema).project(&[3, 2, 1,
0]).unwrap();
+ assert_eq!(reordered.fields().len(), 4);
+ assert_eq!(reordered.field(0).name(), "d");
+ assert_eq!(reordered.field(1).name(), "c");
+ assert_eq!(reordered.field(2).name(), "b");
+ assert_eq!(reordered.field(3).name(), "a");
+ assert_eq!(reordered.metadata()["meta"], "data"); // metadata carried
over
+
+ // Subset: keep only the two middle fields.
+ let subset = SchemaBuilder::from(&schema).project(&[1, 2]).unwrap();
+ assert_eq!(subset.fields().len(), 2);
+ assert_eq!(subset.field(0).name(), "b");
+ assert_eq!(subset.field(1).name(), "c");
+ }
+
+ #[test]
+ fn test_schema_builder_project_errors() {
+ let schema = Schema::new(vec![
+ Field::new("a", DataType::Int32, false),
+ Field::new("b", DataType::Utf8, true),
+ ]);
+
+ // Out of bounds.
+ let err = SchemaBuilder::from(&schema).project(&[0, 5]).unwrap_err();
+ assert!(
+ err.to_string().contains("out of bounds"),
+ "unexpected error: {err}"
+ );
+
+ // Repeated index.
+ let err = SchemaBuilder::from(&schema)
+ .project(&[0, 1, 0])
+ .unwrap_err();
+ assert!(
+ err.to_string().contains("repeated"),
+ "unexpected error: {err}"
+ );
+ }
}
