From 1cb7eaaf56ada718e4ca2774c054561974f5ec53 Mon Sep 17 00:00:00 2001 From: Richard Baah Date: Tue, 3 Nov 2026 08:59:59 -0500 Subject: [PATCH 1/5] bench(arrow-row): cover oversized sparse dictionaries Add an 8,192-row cardinality sweep so sparse dictionary encoding can be compared at the measured crossover and at larger retained value counts. --- arrow/benches/row_format.rs | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/arrow/benches/row_format.rs b/arrow/benches/row_format.rs index 09d3800fae0b..5beb2c20bbb7 100644 --- a/arrow/benches/row_format.rs +++ b/arrow/benches/row_format.rs @@ -24,7 +24,7 @@ use arrow::row::{RowConverter, SortField}; use arrow::util::bench_util::{ create_boolean_array, create_boolean_array_with_seed, create_dict_from_values, create_f64_array_with_seed, create_primitive_array, create_primitive_array_with_seed, - create_primitive_run_array, create_string_array_with_len, + create_primitive_run_array, create_sparse_dict_from_values, create_string_array_with_len, create_string_array_with_len_range_and_prefix_and_seed, create_string_dict_array, create_string_view_array_with_len, create_string_view_array_with_max_len, }; @@ -282,6 +282,17 @@ fn row_bench(c: &mut Criterion) { let cols = vec![Arc::new(dict) as ArrayRef]; do_bench(c, "4096 string_dictionary_low_cardinality(100, 0)", cols); + for value_count in [10_000, 32_768, 100_000, 1_000_000] { + let values = create_string_array_with_len::(value_count, 0., 10); + let dict = create_sparse_dict_from_values::(8_192, 0., &values, 0..8_192); + let cols = vec![Arc::new(dict) as ArrayRef]; + do_bench( + c, + &format!("8192 string_dictionary_sparse_keys({value_count} values)"), + cols, + ); + } + let cols = vec![ Arc::new(create_string_array_with_len::(4096, 0.5, 20)) as ArrayRef, Arc::new(create_string_array_with_len::(4096, 0., 30)) as ArrayRef, From 1252049ea59fe98a10fd1498c2da14fb10dace48 Mon Sep 17 00:00:00 2001 From: Richard Baah Date: Tue, 3 Nov 2026 08:59:59 -0500 Subject: [PATCH 2/5] perf(arrow-row): gather sparse dictionary values by row RowConverter currently encodes every dictionary value, even when a batch references only a small subset. Gather one value per row for dictionaries with at least 32K values and four times more values than rows, avoiding the large values-array cost without penalizing ordinary dictionaries. The cutoff is based on an 8,192-row cardinality sweep: the gathered path crosses over between 20K and 24.6K values, so 32K is deliberately conservative. --- arrow-row/src/lib.rs | 103 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/arrow-row/src/lib.rs b/arrow-row/src/lib.rs index fa2ed015c671..6a7aae377e16 100644 --- a/arrow-row/src/lib.rs +++ b/arrow-row/src/lib.rs @@ -176,6 +176,7 @@ use arrow_array::cast::*; use arrow_array::types::{ArrowDictionaryKeyType, ByteArrayType, ByteViewType}; use arrow_array::*; use arrow_buffer::{ArrowNativeType, Buffer, OffsetBuffer, ScalarBuffer}; +use arrow_data::transform::MutableArrayData; use arrow_schema::*; use variable::{decode_binary_view, decode_string_view}; @@ -189,6 +190,9 @@ mod list; mod run; mod variable; +const DICTIONARY_GATHER_MIN_VALUES: usize = 32 * 1024; +const DICTIONARY_GATHER_RATIO: usize = 4; + /// Converts [`ArrayRef`] columns into a [row-oriented](self) format. /// /// *Note: The encoding of the row format may change from release to release.* @@ -775,7 +779,22 @@ impl Codec { match self { Codec::Stateless => Ok(Encoder::Stateless), Codec::Dictionary(converter, nulls) => { - let values = array.as_any_dictionary().values().clone(); + let dictionary = array.as_any_dictionary(); + let values = dictionary.values(); + // Gathering pays an O(rows) copy to avoid O(values) encoding. + // The cutoff keeps the existing path for small or dense dictionaries. + if values.len() >= DICTIONARY_GATHER_MIN_VALUES + && values.len() >= dictionary.len().saturating_mul(DICTIONARY_GATHER_RATIO) + { + let values = downcast_dictionary_array! { + array => gather_dictionary_values(array)?, + _ => unreachable!(), + }; + let rows = converter.convert_columns(&[values])?; + return Ok(Encoder::DictionaryRows(rows, nulls.row())); + } + + let values = Arc::clone(values); let rows = converter.convert_columns(&[values])?; Ok(Encoder::Dictionary(rows, nulls.row())) } @@ -911,6 +930,8 @@ enum Encoder<'a> { Stateless, /// The encoding of the child array and the encoding of a null row Dictionary(Rows, Row<'a>), + /// The encoding of one dictionary value per input row and a null row + DictionaryRows(Rows, Row<'a>), /// The row encoding of the child arrays and the encoding of a null row /// /// It is necessary to encode to a temporary [`Rows`] to avoid serializing @@ -1893,6 +1914,17 @@ fn row_lengths(cols: &[ArrayRef], encoders: &[Encoder]) -> LengthTracker { _ => unreachable!(), } } + Encoder::DictionaryRows(values, null) => { + downcast_dictionary_array! { + array => tracker.push_variable( + array.keys().iter().enumerate().map(|(row, key)| match key { + Some(_) => values.row_len(row), + None => null.data.len(), + }) + ), + _ => unreachable!(), + } + } Encoder::Struct(rows, null) => { let array = as_struct_array(array); if rows.num_rows() > 0 { @@ -2121,6 +2153,12 @@ fn encode_column( _ => unreachable!() } } + Encoder::DictionaryRows(values, nulls) => { + downcast_dictionary_array! { + column => encode_dictionary_rows(data, offsets, column, values, nulls), + _ => unreachable!() + } + } Encoder::Struct(rows, null) => { fn struct_encode_helper( array: &StructArray, @@ -2262,6 +2300,36 @@ pub fn encode_dictionary_values( } } +fn gather_dictionary_values( + array: &DictionaryArray, +) -> Result { + let data = array.values().to_data(); + let mut mutable = MutableArrayData::new(vec![&data], false, array.len()); + for key in array.keys() { + let index = key.map(|key| key.as_usize()).unwrap_or_default(); + mutable.try_extend(0, index, index + 1)?; + } + Ok(make_array(mutable.freeze())) +} + +fn encode_dictionary_rows( + data: &mut [u8], + offsets: &mut [usize], + column: &DictionaryArray, + values: &Rows, + null: &Row<'_>, +) { + for (row, (offset, key)) in offsets.iter_mut().skip(1).zip(column.keys()).enumerate() { + let value = match key { + Some(_) => values.row(row).data, + None => null.data, + }; + let end_offset = *offset + value.len(); + data[*offset..end_offset].copy_from_slice(value); + *offset = end_offset; + } +} + macro_rules! decode_primitive_helper { ($t:ty, $rows:ident, $data_type:ident, $options:ident) => { Arc::new(decode_primitive::<$t>($rows, $data_type, $options)) @@ -3295,6 +3363,39 @@ mod tests { assert!(rows.row(3) < rows.row(0)); } + #[test] + fn test_sparse_dictionary_values() { + let values = StringArray::from_iter_values((0..100_000).map(|i| format!("value-{i}"))); + let keys = Int32Array::from(vec![ + Some(0), + Some(99_999), + None, + Some(7), + Some(99_999), + Some(3), + ]); + let dictionary = DictionaryArray::::try_new(keys, Arc::new(values)).unwrap(); + let sparse = Arc::new(dictionary.slice(1, 4)) as ArrayRef; + + let expected = Arc::new(DictionaryArray::::from_iter([ + Some("value-99999"), + None, + Some("value-7"), + Some("value-99999"), + ])) as ArrayRef; + + let converter = + RowConverter::new(vec![SortField::new(sparse.data_type().clone())]).unwrap(); + let actual_rows = converter.convert_columns(&[sparse]).unwrap(); + let expected_rows = converter.convert_columns(&[Arc::clone(&expected)]).unwrap(); + + for (actual, expected) in actual_rows.iter().zip(&expected_rows) { + assert_eq!(actual, expected); + } + let decoded = converter.convert_rows(&actual_rows).unwrap(); + dictionary_eq(&decoded[0], &expected); + } + #[test] fn test_from_binary_shared_buffer() { let converter = RowConverter::new(vec![SortField::new(DataType::Binary)]).unwrap(); From 1feadc51792bd44d445545773957651cf87c8d91 Mon Sep 17 00:00:00 2001 From: Richard Baah Date: Tue, 3 Nov 2026 09:21:06 -0500 Subject: [PATCH 3/5] chore(arrow-row): remove temporary benchmark cases The focused cases were only needed to establish the cutoff and capture hosted evidence. Remove them from the permanent suite and document why the gather path is guarded. --- arrow-row/src/lib.rs | 4 ++-- arrow/benches/row_format.rs | 13 +------------ 2 files changed, 3 insertions(+), 14 deletions(-) diff --git a/arrow-row/src/lib.rs b/arrow-row/src/lib.rs index 6a7aae377e16..460879463cd3 100644 --- a/arrow-row/src/lib.rs +++ b/arrow-row/src/lib.rs @@ -190,6 +190,8 @@ mod list; mod run; mod variable; +// Gathering copies one value per row before encoding, so only use it when the +// dictionary is large and sparse enough for skipping unused values to pay off. const DICTIONARY_GATHER_MIN_VALUES: usize = 32 * 1024; const DICTIONARY_GATHER_RATIO: usize = 4; @@ -781,8 +783,6 @@ impl Codec { Codec::Dictionary(converter, nulls) => { let dictionary = array.as_any_dictionary(); let values = dictionary.values(); - // Gathering pays an O(rows) copy to avoid O(values) encoding. - // The cutoff keeps the existing path for small or dense dictionaries. if values.len() >= DICTIONARY_GATHER_MIN_VALUES && values.len() >= dictionary.len().saturating_mul(DICTIONARY_GATHER_RATIO) { diff --git a/arrow/benches/row_format.rs b/arrow/benches/row_format.rs index 5beb2c20bbb7..09d3800fae0b 100644 --- a/arrow/benches/row_format.rs +++ b/arrow/benches/row_format.rs @@ -24,7 +24,7 @@ use arrow::row::{RowConverter, SortField}; use arrow::util::bench_util::{ create_boolean_array, create_boolean_array_with_seed, create_dict_from_values, create_f64_array_with_seed, create_primitive_array, create_primitive_array_with_seed, - create_primitive_run_array, create_sparse_dict_from_values, create_string_array_with_len, + create_primitive_run_array, create_string_array_with_len, create_string_array_with_len_range_and_prefix_and_seed, create_string_dict_array, create_string_view_array_with_len, create_string_view_array_with_max_len, }; @@ -282,17 +282,6 @@ fn row_bench(c: &mut Criterion) { let cols = vec![Arc::new(dict) as ArrayRef]; do_bench(c, "4096 string_dictionary_low_cardinality(100, 0)", cols); - for value_count in [10_000, 32_768, 100_000, 1_000_000] { - let values = create_string_array_with_len::(value_count, 0., 10); - let dict = create_sparse_dict_from_values::(8_192, 0., &values, 0..8_192); - let cols = vec![Arc::new(dict) as ArrayRef]; - do_bench( - c, - &format!("8192 string_dictionary_sparse_keys({value_count} values)"), - cols, - ); - } - let cols = vec![ Arc::new(create_string_array_with_len::(4096, 0.5, 20)) as ArrayRef, Arc::new(create_string_array_with_len::(4096, 0., 30)) as ArrayRef, From 2b7b812e7c76c64d8836a0b2e5f7a6315c0f1096 Mon Sep 17 00:00:00 2001 From: Richard Baah Date: Wed, 4 Nov 2026 10:55:46 -0500 Subject: [PATCH 4/5] docs(arrow-row): clarify flattened dictionary rows --- arrow-row/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arrow-row/src/lib.rs b/arrow-row/src/lib.rs index 460879463cd3..c6a171d3c44c 100644 --- a/arrow-row/src/lib.rs +++ b/arrow-row/src/lib.rs @@ -930,7 +930,7 @@ enum Encoder<'a> { Stateless, /// The encoding of the child array and the encoding of a null row Dictionary(Rows, Row<'a>), - /// The encoding of one dictionary value per input row and a null row + /// The encoding of the flattened dictionary array and a null row DictionaryRows(Rows, Row<'a>), /// The row encoding of the child arrays and the encoding of a null row /// From 6269c5802d2370df5ea18c5861f366cc4473bbe3 Mon Sep 17 00:00:00 2001 From: Richard Baah Date: Wed, 4 Nov 2026 10:58:13 -0500 Subject: [PATCH 5/5] fix(arrow-row): fall back when dictionary gather overflows --- arrow-row/src/lib.rs | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/arrow-row/src/lib.rs b/arrow-row/src/lib.rs index c6a171d3c44c..afbb808282c7 100644 --- a/arrow-row/src/lib.rs +++ b/arrow-row/src/lib.rs @@ -787,11 +787,15 @@ impl Codec { && values.len() >= dictionary.len().saturating_mul(DICTIONARY_GATHER_RATIO) { let values = downcast_dictionary_array! { - array => gather_dictionary_values(array)?, + array => gather_dictionary_values(array), _ => unreachable!(), }; - let rows = converter.convert_columns(&[values])?; - return Ok(Encoder::DictionaryRows(rows, nulls.row())); + // Gathering can overflow nested offsets or run ends even when + // encoding the original dictionary values would succeed. + if let Ok(values) = values { + let rows = converter.convert_columns(&[values])?; + return Ok(Encoder::DictionaryRows(rows, nulls.row())); + } } let values = Arc::clone(values); @@ -3396,6 +3400,32 @@ mod tests { dictionary_eq(&decoded[0], &expected); } + #[test] + fn test_sparse_dictionary_gather_overflow_falls_back() { + let inner = RunArray::::try_new( + &PrimitiveArray::from(vec![1_i16]), + &Int32Array::from(vec![1]), + ) + .unwrap(); + let values = RunArray::::try_new( + &PrimitiveArray::from(vec![ + (DICTIONARY_GATHER_MIN_VALUES * DICTIONARY_GATHER_RATIO) as i64, + ]), + &inner, + ) + .unwrap(); + let keys = Int32Array::from(vec![0; DICTIONARY_GATHER_MIN_VALUES]); + let dictionary = DictionaryArray::::try_new(keys, Arc::new(values)).unwrap(); + + let input = Arc::new(dictionary) as ArrayRef; + let converter = RowConverter::new(vec![SortField::new(input.data_type().clone())]).unwrap(); + let rows = converter.convert_columns(&[input]).unwrap(); + + assert_eq!(rows.num_rows(), DICTIONARY_GATHER_MIN_VALUES); + let first = rows.row(0); + assert!(rows.iter().all(|row| row == first)); + } + #[test] fn test_from_binary_shared_buffer() { let converter = RowConverter::new(vec![SortField::new(DataType::Binary)]).unwrap();