Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
58189a1
Builder appending refactoring
sandugood Jun 17, 2026
7778a84
Formatting, small refactoring and adding docstrings
sandugood Jun 18, 2026
2bee010
Added docstring regarding alignment
sandugood Jun 18, 2026
6abf1f7
Fixed the fallback in an unaligned but NULLABLE case, that was failin…
sandugood Jun 18, 2026
7439706
Merge remote-tracking branch 'upstream/main' into feat/enable-slice-a…
sandugood Jun 18, 2026
74265c7
Changes fixed
sandugood Jun 18, 2026
d2c85e4
Merge remote-tracking branch 'upstream/main' into feat/enable-slice-a…
sandugood Jun 18, 2026
662a7f2
Fixed cargo formatting
sandugood Jun 18, 2026
7bf6f15
Merge remote-tracking branch 'upstream/main' into feat/enable-slice-a…
sandugood Jun 19, 2026
157c73f
Remade the building process using arrow buffers with no hot-spots in …
sandugood Jun 19, 2026
0e5fcad
Formatting fix
sandugood Jun 19, 2026
42bd9dd
Added docstring about runtime check of alignment
sandugood Jun 19, 2026
df678f9
Merge remote-tracking branch 'upstream/main' into feat/enable-slice-a…
sandugood Jun 27, 2026
9cbe7aa
Addressed the review comments
sandugood Jun 27, 2026
9e297b5
Fixed formatting
sandugood Jun 27, 2026
b2eb684
Added docstring regarding endianess
sandugood Jun 27, 2026
ab4d1f6
Merge remote-tracking branch 'upstream/main' into feat/enable-slice-a…
sandugood Jun 29, 2026
ba24cd5
Merge remote-tracking branch 'upstream/main' into feat/enable-slice-a…
sandugood Jun 29, 2026
9b45105
Merge branch 'main' into feat/enable-slice-access
mbutrovich Jul 16, 2026
c3f5898
Merge remote-tracking branch 'apache/main' into feat/enable-slice-access
andygrove Oct 9, 2026
baa5859
test: cover a timestamp array with a timezone in the append round trip
andygrove Oct 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
256 changes: 194 additions & 62 deletions native/shuffle/src/spark_unsafe/list.rs
Original file line number Diff line number Diff line change
Expand Up @@ -15,21 +15,30 @@
// specific language governing permissions and limitations
// under the License.

use std::sync::Arc;

use crate::spark_unsafe::{
map::append_map_elements,
row::{append_field, downcast_builder_ref, SparkUnsafeRow},
unsafe_object::{impl_primitive_accessors, SparkUnsafeObject},
};
use arrow::array::{
builder::{
ArrayBuilder, BinaryBuilder, BooleanBuilder, Date32Builder, Decimal128Builder,
Float32Builder, Float64Builder, Int16Builder, Int32Builder, Int64Builder, Int8Builder,
ListBuilder, NullBuilder, StringBuilder, StructBuilder, Time64NanosecondBuilder,
TimestampMicrosecondBuilder,
use arrow::datatypes::{DataType, TimeUnit};
use arrow::{
array::{
builder::{
ArrayBuilder, BinaryBuilder, BooleanBuilder, Date32Builder, Decimal128Builder,
Float32Builder, Float64Builder, Int16Builder, Int32Builder, Int64Builder, Int8Builder,
ListBuilder, NullBuilder, StringBuilder, StructBuilder, Time64NanosecondBuilder,
TimestampMicrosecondBuilder,
},
MapBuilder, PrimitiveArray,
},
buffer::{BooleanBuffer, Buffer, NullBuffer, ScalarBuffer},
datatypes::{
Date32Type, Float32Type, Float64Type, Int16Type, Int32Type, Int64Type, Int8Type,
Time64NanosecondType, TimestampMicrosecondType,
},
MapBuilder,
};
use arrow::datatypes::{DataType, TimeUnit};
use datafusion_comet_jni_bridge::errors::CometError;

/// Element count from which a nullable array with no null elements is appended with one copy
Expand All @@ -46,39 +55,69 @@ const MIN_BULK_APPEND_ELEMENTS: usize = 8;
/// - `null_bitset_ptr()` returns a pointer to `ceil(num_elements/64)` i64 words
/// - These invariants are guaranteed by the SparkUnsafeArray layout from the JVM
macro_rules! impl_append_to_builder {
($method_name:ident, $builder_type:ty, $element_type:ty) => {
pub(crate) fn $method_name<const NULLABLE: bool>(&self, builder: &mut $builder_type) {
($method_name:ident, $builder_type:ty, $element_type:ty, $arrow_type:ty
$(, $timezone:ident)?) => {
pub(crate) fn $method_name<const NULLABLE: bool>(
&self,
builder: &mut $builder_type,
$($timezone: Option<Arc<str>>,)?
) {
let num_elements = self.num_elements;
if num_elements == 0 {
return;
}
// Note: alignment is not guaranteed - that is why do this
// This runtime check is needed. Look at `unsafe_object.rs:49` for more info
let ptr = self.element_offset as *const $element_type;
let aligned = (ptr as usize).is_multiple_of(std::mem::align_of::<$element_type>());

// A nullable array without nulls takes the copy below too, once it is long enough.
if NULLABLE && (num_elements < MIN_BULK_APPEND_ELEMENTS || self.has_null()) {
let mut ptr = self.element_offset as *const $element_type;
let null_words = self.null_bitset_ptr();
debug_assert!(!null_words.is_null(), "null_bitset_ptr is null");
debug_assert!(!ptr.is_null(), "element_offset pointer is null");
for idx in 0..num_elements {
// SAFETY: null_words has ceil(num_elements/64) words, idx < num_elements
let is_null = unsafe { Self::is_null_in_bitset(null_words, idx) };

if is_null {
builder.append_null();
} else {
// SAFETY: ptr is within element data bounds
builder.append_value(unsafe { ptr.read_unaligned() });

// An array shorter than MIN_BULK_APPEND_ELEMENTS stays on the per-element loop,
// which costs less than building the validity and value buffers.
if aligned && num_elements >= MIN_BULK_APPEND_ELEMENTS {
// Raw values
let values = unsafe { std::slice::from_raw_parts(ptr, num_elements) };

// Note: in Spark bitmap is padded to 8 byte word-boundaries
// In Arrow we just use the needed number of whole bytes without padding
let null_mask_len = num_elements.div_ceil(8);
// Spark and Arrow both use little-endian bit ordering within each byte,
// so casting the i64 null words to *const u8 preserves correct bit indexing.
let null_mask = unsafe {
std::slice::from_raw_parts::<u8>(null_words as *const u8, null_mask_len)
};
// We need to perform this flip due to the null bitmap Spark vs Arrow incompatibility
// In `Spark` we have 1 set in bitmap meaning that element IS NULL
// In `Arrow` we have 1 set in bitmap meaning that element IS VALID (non-null)
let flipped: Vec<u8> = null_mask.iter().map(|n| !n).collect();
// Constructing null-buffer
let validity =
NullBuffer::new(BooleanBuffer::new(Buffer::from(flipped), 0, num_elements));

let arr = PrimitiveArray::<$arrow_type>::new(
ScalarBuffer::from(Buffer::from_slice_ref(values)),

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Could we retain an allocation-free path for short arrays? Every aligned nullable append now allocates temporary bitmap/value buffers, and append_array copies the values again into the builder. append_list_column_batch invokes this with <true> for every list, including lists without null elements. Using the exact base/head methods with Arrow 58.3.0, a release benchmark including ListBuilder construction, downcasting, and list appends measured singleton array<int> conversion at 19.34 ns/row before versus 212.48 ns/row after, about 11× slower. An allocation counter independently measured 0 versus 4,000 allocations for 1,000 singleton appends into a preallocated builder. This materially increases conversion CPU for JVM shuffle workloads containing many short arrays. Preserve the scalar loop below a measured size cutoff, or reuse storage to avoid these per-list allocations. The same approach applies to the date and timestamp helpers.

Evidence: Disposable harness: /tmp/comet-4672-append-check. The extracted append-method bodies were verified against both supplied SHAs. Run cargo run --release --offline --manifest-path /tmp/comet-4672-append-check/Cargo.toml --bin list_bench and the same command with --bin allocations. The list benchmark uses 8,192 rows per batch, 64 distinct aligned input arrays, initial values-builder capacity 32, and medians of nine alternating base/head measurements. Singleton arrays without nulls measured 19.34→212.48 ns/row, and singleton null arrays measured 20.86→199.24 ns/row. Shorter-path allocation overhead is confirmed by the deterministic 0→4 allocations per singleton append. A separate 10,000-element benchmark confirmed the intended large-array improvement, so the finding concerns the unconditional use of this path for short arrays.

Some(validity),
);
// `append_array` requires the array's data type to match the builder's,
// timezone included.
$(let arr = arr.with_timezone_opt($timezone);)?
builder.append_array(&arr);
} else {
let mut ptr = ptr;
for idx in 0..num_elements {
if unsafe { Self::is_null_in_bitset(null_words, idx) } {
builder.append_null();
} else {
builder.append_value(unsafe { ptr.read_unaligned() });
}
ptr = unsafe { ptr.add(1) };
}
// SAFETY: ptr stays within bounds, iterating num_elements times
ptr = unsafe { ptr.add(1) };
}
} else {
// SAFETY: element_offset points to contiguous data of length num_elements
debug_assert!(self.element_offset != 0, "element_offset is null");
let ptr = self.element_offset as *const $element_type;
// Use bulk copy when data is properly aligned, fall back to
// per-element unaligned reads otherwise
if (ptr as usize).is_multiple_of(std::mem::align_of::<$element_type>()) {
if aligned {
let slice = unsafe { std::slice::from_raw_parts(ptr, num_elements) };
builder.append_slice(slice);
} else {
Expand Down Expand Up @@ -196,19 +235,26 @@ impl SparkUnsafeArray {
(null_words.add(word_idx).read_unaligned() & (1i64 << bit_idx)) != 0
}

impl_append_to_builder!(append_ints_to_builder, Int32Builder, i32);
impl_append_to_builder!(append_longs_to_builder, Int64Builder, i64);
impl_append_to_builder!(append_time64s_to_builder, Time64NanosecondBuilder, i64);
impl_append_to_builder!(append_shorts_to_builder, Int16Builder, i16);
impl_append_to_builder!(append_bytes_to_builder, Int8Builder, i8);
impl_append_to_builder!(append_floats_to_builder, Float32Builder, f32);
impl_append_to_builder!(append_doubles_to_builder, Float64Builder, f64);
impl_append_to_builder!(append_ints_to_builder, Int32Builder, i32, Int32Type);
impl_append_to_builder!(append_longs_to_builder, Int64Builder, i64, Int64Type);
impl_append_to_builder!(
append_time64s_to_builder,
Time64NanosecondBuilder,
i64,
Time64NanosecondType
);
impl_append_to_builder!(append_shorts_to_builder, Int16Builder, i16, Int16Type);
impl_append_to_builder!(append_bytes_to_builder, Int8Builder, i8, Int8Type);
impl_append_to_builder!(append_floats_to_builder, Float32Builder, f32, Float32Type);
impl_append_to_builder!(append_doubles_to_builder, Float64Builder, f64, Float64Type);
impl_append_to_builder!(
append_timestamps_to_builder,
TimestampMicrosecondBuilder,
i64
i64,
TimestampMicrosecondType,
timezone
);
impl_append_to_builder!(append_dates_to_builder, Date32Builder, i32);
impl_append_to_builder!(append_dates_to_builder, Date32Builder, i32, Date32Type);

/// Bulk append boolean values to builder.
/// Booleans are stored as 1 byte each in SparkUnsafeArray, requiring special handling.
Expand All @@ -220,37 +266,31 @@ impl SparkUnsafeArray {
if num_elements == 0 {
return;
}

let mut ptr = self.element_offset as *const u8;
// Bools have alignment == 1
// We dont have to worry about the fallback. Hence, we do not care about it
debug_assert!(
!ptr.is_null(),
self.element_offset != 0,
"append_booleans: element_offset pointer is null"
);

if NULLABLE {
let null_words = self.null_bitset_ptr();
debug_assert!(
!null_words.is_null(),
"append_booleans: null_bitset_ptr is null"
);
for idx in 0..num_elements {
// SAFETY: null_words has ceil(num_elements/64) words, idx < num_elements
let is_null = unsafe { Self::is_null_in_bitset(null_words, idx) };

if is_null {
let slice = unsafe {
std::slice::from_raw_parts(self.element_offset as *const u8, num_elements)
};
for (idx, &value) in slice.iter().enumerate() {
if unsafe { Self::is_null_in_bitset(null_words, idx) } {
builder.append_null();
} else {
// SAFETY: ptr is within element data bounds
builder.append_value(unsafe { *ptr != 0 });
builder.append_value(value != 0);
}
// SAFETY: ptr stays within bounds, iterating num_elements times
ptr = unsafe { ptr.add(1) };
}
} else {
for _ in 0..num_elements {
// SAFETY: ptr is within element data bounds
builder.append_value(unsafe { *ptr != 0 });
ptr = unsafe { ptr.add(1) };
let values = unsafe {
std::slice::from_raw_parts(self.element_offset as *const u8, num_elements)
};
for &value in values {
builder.append_value(value != 0);
}
}
}
Expand Down Expand Up @@ -307,9 +347,9 @@ pub fn append_to_builder<const NULLABLE: bool>(
let builder = downcast_builder_ref!(Float64Builder, builder);
array.append_doubles_to_builder::<NULLABLE>(builder);
}
DataType::Timestamp(TimeUnit::Microsecond, _) => {
DataType::Timestamp(TimeUnit::Microsecond, tz) => {
let builder = downcast_builder_ref!(TimestampMicrosecondBuilder, builder);
array.append_timestamps_to_builder::<NULLABLE>(builder);
array.append_timestamps_to_builder::<NULLABLE>(builder, tz.clone());
}
DataType::Date32 => {
let builder = downcast_builder_ref!(Date32Builder, builder);
Expand Down Expand Up @@ -415,6 +455,7 @@ pub fn append_list_element(
mod test {
use super::*;
use arrow::array::builder::PrimitiveBuilder;
use arrow::array::Array;
use arrow::datatypes::{
ArrowPrimitiveType, Date32Type, Int16Type, Int32Type, Int64Type, Int8Type,
TimestampMicrosecondType,
Expand Down Expand Up @@ -455,7 +496,7 @@ mod test {
let base = unsafe { (words.as_mut_ptr() as *mut u8).add(shift) };
unsafe { std::ptr::copy_nonoverlapping(bytes.as_ptr(), base, bytes.len()) };
let array = SparkUnsafeArray::new(base as i64);
let mut builder = PrimitiveBuilder::<T>::new();
let mut builder = PrimitiveBuilder::<T>::new().with_data_type(data_type.clone());
append_to_builder::<true>(&data_type, &mut builder, &array).unwrap();
builder.finish().iter().map(|v| v.map(Into::into)).collect()
}
Expand Down Expand Up @@ -508,7 +549,98 @@ mod test {
),
*values
);
// The builder carries the column's timezone, which `append_array` checks.
assert_eq!(
round_trip::<TimestampMicrosecondType>(
DataType::Timestamp(TimeUnit::Microsecond, Some("America/Denver".into())),
values,
shift
),
*values
);
}
}
}

fn make_i32_array(num_elements: usize, null_indices: &[usize]) -> Vec<u8> {
let null_bitset_words = num_elements.div_ceil(64);
let header_size = 8 + null_bitset_words * 8;
let mut buffer = vec![0u8; header_size + num_elements * 4];

buffer[0..8].copy_from_slice(&(num_elements as i64).to_le_bytes());

for &i in null_indices {
let word_offset = 8 + (i / 64) * 8;
let word = i64::from_le_bytes(buffer[word_offset..word_offset + 8].try_into().unwrap());
buffer[word_offset..word_offset + 8]
.copy_from_slice(&(word | (1i64 << (i % 64))).to_le_bytes());
}

for i in 0..num_elements {
let offset = header_size + i * 4;
buffer[offset..offset + 4].copy_from_slice(&(i as i32).to_le_bytes());
}
buffer
}

fn append_i32(buffer: &[u8]) -> arrow::array::Int32Array {
let array = SparkUnsafeArray::new(buffer.as_ptr() as i64);
let mut builder = Int32Builder::new();
append_to_builder::<true>(&DataType::Int32, &mut builder, &array).unwrap();
builder.finish()
}

#[test]
fn test_nullable_7_elements_null_in_last_byte() {
// 7 elements — partial last byte, null at index 6
let buf = make_i32_array(7, &[6]);
let arr = append_i32(&buf);
assert_eq!(arr.len(), 7);
assert!(arr.is_null(6));
for i in 0..6 {
assert!(arr.is_valid(i));
assert_eq!(arr.value(i), i as i32);
}
}

#[test]
fn test_nullable_9_elements_null_in_last_byte() {
let buf = make_i32_array(9, &[8]);
let arr = append_i32(&buf);
assert_eq!(arr.len(), 9);
assert!(arr.is_null(8));
for i in 0..8 {
assert!(arr.is_valid(i));
assert_eq!(arr.value(i), i as i32);
}
}

#[test]
fn test_nullable_17_elements_null_in_last_byte() {
let buf = make_i32_array(17, &[16]);
let arr = append_i32(&buf);
assert_eq!(arr.len(), 17);
assert!(arr.is_null(16));
for i in 0..16 {
assert!(arr.is_valid(i));
assert_eq!(arr.value(i), i as i32);
}
}

#[test]
fn test_all_null() {
let indices: Vec<usize> = (0..9).collect();
let buf = make_i32_array(9, &indices);
let arr = append_i32(&buf);
assert_eq!(arr.len(), 9);
assert_eq!(arr.null_count(), 9);
}

#[test]
fn test_all_valid() {
let buf = make_i32_array(9, &[]);
let arr = append_i32(&buf);
assert_eq!(arr.len(), 9);
assert_eq!(arr.null_count(), 0);
}
}
Loading
Loading