This is an automated email from the ASF dual-hosted git repository.
etseidl 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 0b0f7cc05d docs: provide performance guide for primitive (#10895)
0b0f7cc05d is described below
commit 0b0f7cc05d88a06337f559074a795fa5a06d9e5f
Author: RIchard Baah <[email protected]>
AuthorDate: Thu Aug 27 15:50:00 2026 -0400
docs: provide performance guide for primitive (#10895)
# Which issue does this PR close?
- Closes #7297.
# Rationale for this change
see #7297
# What changes are included in this PR?
adds doc comment on `PrimitiveBuilder<T>` and `PrimitiveArray<T>`
explaining when to use `Primtive:from(vec![T,T,T...])` vs
`PrimitiveBuilder::new()`
# Are these changes tested?
n/a
# Are there any user-facing changes?
yes! in depth docs to help guide users
---
arrow-array/src/array/primitive_array.rs | 12 +++++++++++
arrow-array/src/builder/primitive_builder.rs | 31 ++++++++++++++++++++++++++++
2 files changed, 43 insertions(+)
diff --git a/arrow-array/src/array/primitive_array.rs
b/arrow-array/src/array/primitive_array.rs
index dc17cdfffd..5058dbc9ac 100644
--- a/arrow-array/src/array/primitive_array.rs
+++ b/arrow-array/src/array/primitive_array.rs
@@ -581,6 +581,18 @@ pub use crate::types::ArrowPrimitiveType;
/// assert!(array.is_null(1));
/// ```
///
+/// # Performance: Choosing Between `from` and [`PrimitiveBuilder`]
+///
+/// When all values are known upfront, constructing a `PrimitiveArray`
directly via
+/// [`PrimitiveArray::from`] or [`PrimitiveArray::new`] is significantly
faster than
+/// using [`PrimitiveBuilder`]:
+///
+/// - **`PrimitiveArray::from(vec![...])`** — zero-copy from `Vec`; no
per-element
+/// bookkeeping. Prefer this whenever values are already collected.
+/// - **[`PrimitiveBuilder`]** — allocates incrementally and tracks nullability
+/// per-element. Use this only when values must be appended one-at-a-time
inside a
+/// loop where the final size is not known in advance.
+///
/// # Example: Get a `PrimitiveArray` from an [`ArrayRef`]
/// ```
/// # use std::sync::Arc;
diff --git a/arrow-array/src/builder/primitive_builder.rs
b/arrow-array/src/builder/primitive_builder.rs
index 060eb4f8dc..e3610e4ea7 100644
--- a/arrow-array/src/builder/primitive_builder.rs
+++ b/arrow-array/src/builder/primitive_builder.rs
@@ -96,6 +96,37 @@ pub type Decimal128Builder =
PrimitiveBuilder<Decimal128Type>;
pub type Decimal256Builder = PrimitiveBuilder<Decimal256Type>;
/// Builder for [`PrimitiveArray`]
+///
+/// # Performance
+///
+/// When all values are known upfront, prefer constructing a
[`PrimitiveArray`] directly
+/// via [`PrimitiveArray::from`] or [`PrimitiveArray::new`] instead of using
this builder.
+/// Direct construction reuses the existing allocation (zero-copy from `Vec`)
and avoids
+/// the overhead of per-element bookkeeping, making it significantly faster.
+///
+/// Use [`PrimitiveBuilder`] when values must be appended **incrementally** —
for example,
+/// inside a loop where the final size is not known in advance.
+///
+/// # Example
+///
+/// ```
+/// # use arrow_array::{Int32Array, Array};
+/// // Prefer this when values are known upfront (zero-copy, no per-element
overhead):
+/// let array = Int32Array::from(vec![1, 2, 3]);
+/// assert_eq!(array.len(), 3);
+/// ```
+///
+/// ```
+/// # use arrow_array::builder::Int32Builder;
+/// # use arrow_array::Array;
+/// // Use the builder when appending values one-by-one:
+/// let mut builder = Int32Builder::new();
+/// for v in [1, 2, 3] {
+/// builder.append_value(v);
+/// }
+/// let array = builder.finish();
+/// assert_eq!(array.len(), 3);
+/// ```
#[derive(Debug)]
pub struct PrimitiveBuilder<T: ArrowPrimitiveType> {
values_builder: Vec<T::Native>,
