Skip to content

Apache DataFusion SQL Query Engine

feat: optimise copying in `left` for Utf8 and LargeUtf8 (#19980)

theirix8152b4443043
diff --git a/datafusion/functions/benches/left.rs b/datafusion/functions/benches/left.rs
index 3ea628fe29..d208e7d4fc 100644
--- a/datafusion/functions/benches/left.rs
+++ b/datafusion/functions/benches/left.rs
@@ -22,14 +22,29 @@ use std::sync::Arc;
use arrow::array::{ArrayRef, Int64Array};
use arrow::datatypes::{DataType, Field};
-use arrow::util::bench_util::create_string_array_with_len;
+use arrow::util::bench_util::{
+ create_string_array_with_len, create_string_view_array_with_len,
+};
use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main};
use datafusion_common::config::ConfigOptions;
use datafusion_expr::{ColumnarValue, ScalarFunctionArgs};
use datafusion_functions::unicode::left;
-fn create_args(size: usize, str_len: usize, use_negative: bool) -> Vec<ColumnarValue> {
- let string_array = Arc::new(create_string_array_with_len::<i32>(size, 0.1, str_len));
+fn create_args(
+ size: usize,
+ str_len: usize,
+ use_negative: bool,
+ is_string_view: bool,
+) -> Vec<ColumnarValue> {
+ let string_arg = if is_string_view {
+ ColumnarValue::Array(Arc::new(create_string_view_array_with_len(
+ size, 0.1, str_len, true,
+ )))
+ } else {
+ ColumnarValue::Array(Arc::new(create_string_array_with_len::<i32>(
+ size, 0.1, str_len,
+ )))
+ };
// For negative n, we want to trigger the double-iteration code path
let n_values: Vec<i64> = if use_negative {
@@ -40,70 +55,84 @@ fn create_args(size: usize, str_len: usize, use_negative: bool) -> Vec<ColumnarV
let n_array = Arc::new(Int64Array::from(n_values));
vec![
- ColumnarValue::Array(string_array),
+ string_arg,
ColumnarValue::Array(Arc::clone(&n_array) as ArrayRef),
]
}
fn criterion_benchmark(c: &mut Criterion) {
- for size in [1024, 4096] {
- let mut group = c.benchmark_group(format!("left size={size}"));
+ for is_string_view in [false, true] {
+ for size in [1024, 4096] {
+ let mut group = c.benchmark_group(format!("left size={size}"));
- // Benchmark with positive n (no optimization needed)
- let args = create_args(size, 32, false);
- group.bench_function(BenchmarkId::new("positive n", size), |b| {
- let arg_fields = args
- .iter()
- .enumerate()
- .map(|(idx, arg)| {
- Field::new(format!("arg_{idx}"), arg.data_type(), true).into()
+ // Benchmark with positive n (no optimization needed)
+ let mut function_name = if is_string_view {
+ "string_view_array positive n"
+ } else {
+ "string_array positive n"
+ };
+ let args = create_args(size, 32, false, is_string_view);
+ group.bench_function(BenchmarkId::new(function_name, size), |b| {
+ let arg_fields = args
+ .iter()
+ .enumerate()
+ .map(|(idx, arg)| {
+ Field::new(format!("arg_{idx}"), arg.data_type(), true).into()
+ })
+ .collect::<Vec<_>>();
+ let config_options = Arc::new(ConfigOptions::default());
+
+ b.iter(|| {
+ black_box(
+ left()
+ .invoke_with_args(ScalarFunctionArgs {
+ args: args.clone(),
+ arg_fields: arg_fields.clone(),
+ number_rows: size,
+ return_field: Field::new("f", DataType::Utf8, true)
+ .into(),
+ config_options: Arc::clone(&config_options),
+ })
+ .expect("left should work"),
+ )
})
- .collect::<Vec<_>>();
- let config_options = Arc::new(ConfigOptions::default());
+ });
- b.iter(|| {
- black_box(
- left()
- .invoke_with_args(ScalarFunctionArgs {
- args: args.clone(),
- arg_fields: arg_fields.clone(),
- number_rows: size,
- return_field: Field::new("f", DataType::Utf8, true).into(),
- config_options: Arc::clone(&config_options),
- })
- .expect("left should work"),
- )
- })
- });
+ // Benchmark with negative n (triggers optimization)
+ function_name = if is_string_view {
+ "string_view_array negative n"
+ } else {
+ "string_array negative n"
+ };
+ let args = create_args(size, 32, true, is_string_view);
+ group.bench_function(BenchmarkId::new(function_name, size), |b| {
+ let arg_fields = args
+ .iter()
+ .enumerate()
+ .map(|(idx, arg)| {
+ Field::new(format!("arg_{idx}"), arg.data_type(), true).into()
+ })
+ .collect::<Vec<_>>();
+ let config_options = Arc::new(ConfigOptions::default());
- // Benchmark with negative n (triggers optimization)
- let args = create_args(size, 32, true);
- group.bench_function(BenchmarkId::new("negative n", size), |b| {
- let arg_fields = args
- .iter()
- .enumerate()
- .map(|(idx, arg)| {
- Field::new(format!("arg_{idx}"), arg.data_type(), true).into()
+ b.iter(|| {
+ black_box(
+ left()
+ .invoke_with_args(ScalarFunctionArgs {
+ args: args.clone(),
+ arg_fields: arg_fields.clone(),
+ number_rows: size,
+ return_field: Field::new("f", DataType::Utf8, true)
+ .into(),
+ config_options: Arc::clone(&config_options),
+ })
+ .expect("left should work"),
+ )
})
- .collect::<Vec<_>>();
- let config_options = Arc::new(ConfigOptions::default());
-
- b.iter(|| {
- black_box(
- left()
- .invoke_with_args(ScalarFunctionArgs {
- args: args.clone(),
- arg_fields: arg_fields.clone(),
- number_rows: size,
- return_field: Field::new("f", DataType::Utf8, true).into(),
- config_options: Arc::clone(&config_options),
- })
- .expect("left should work"),
- )
- })
- });
+ });
- group.finish();
+ group.finish();
+ }
}
}
diff --git a/datafusion/functions/src/unicode/left.rs b/datafusion/functions/src/unicode/left.rs
index db27d900b6..c7b37ea3ec 100644
--- a/datafusion/functions/src/unicode/left.rs
+++ b/datafusion/functions/src/unicode/left.rs
@@ -19,13 +19,13 @@ use std::any::Any;
use std::cmp::Ordering;
use std::sync::Arc;
+use crate::utils::make_scalar_function;
use arrow::array::{
- Array, ArrayAccessor, ArrayIter, ArrayRef, GenericStringArray, Int64Array,
- OffsetSizeTrait,
+ Array, ArrayAccessor, ArrayIter, ArrayRef, ByteView, GenericStringArray, Int64Array,
+ OffsetSizeTrait, StringViewArray,
};
use arrow::datatypes::DataType;
-
-use crate::utils::{make_scalar_function, utf8_to_str_type};
+use arrow_buffer::{NullBuffer, ScalarBuffer};
use datafusion_common::Result;
use datafusion_common::cast::{
as_generic_string_array, as_int64_array, as_string_view_array,
@@ -94,7 +94,7 @@ impl ScalarUDFImpl for LeftFunc {
}
fn return_type(&self, arg_types: &[DataType]) -> Result<DataType> {
- utf8_to_str_type(&arg_types[0], "left")
+ Ok(arg_types[0].clone())
}
fn invoke_with_args(
@@ -103,13 +103,13 @@ impl ScalarUDFImpl for LeftFunc {
) -> Result<ColumnarValue> {
let args = &args.args;
match args[0].data_type() {
- DataType::Utf8 | DataType::Utf8View => {
- make_scalar_function(left::<i32>, vec![])(args)
+ DataType::Utf8 | DataType::Utf8View | DataType::LargeUtf8 => {
+ make_scalar_function(left, vec![])(args)
}
- DataType::LargeUtf8 => make_scalar_function(left::<i64>, vec![])(args),
other => exec_err!(
- "Unsupported data type {other:?} for function left,\
- expected Utf8View, Utf8 or LargeUtf8."
+ "Unsupported data type {other:?} for function {},\
+ expected Utf8View, Utf8 or LargeUtf8.",
+ self.name()
),
}
}
@@ -121,50 +121,42 @@ impl ScalarUDFImpl for LeftFunc {
/// Returns first n characters in the string, or when n is negative, returns all but last |n| characters.
/// left('abcde', 2) = 'ab'
+/// left('abcde', -2) = 'ab'
/// The implementation uses UTF-8 code points as characters
-fn left<T: OffsetSizeTrait>(args: &[ArrayRef]) -> Result<ArrayRef> {
+fn left(args: &[ArrayRef]) -> Result<ArrayRef> {
let n_array = as_int64_array(&args[1])?;
- if args[0].data_type() == &DataType::Utf8View {
- let string_array = as_string_view_array(&args[0])?;
- left_impl::<T, _>(string_array, n_array)
- } else {
- let string_array = as_generic_string_array::<T>(&args[0])?;
- left_impl::<T, _>(string_array, n_array)
+ match args[0].data_type() {
+ DataType::Utf8 => {
+ let string_array = as_generic_string_array::<i32>(&args[0])?;
+ left_impl::<i32, _>(string_array, n_array)
+ }
+ DataType::LargeUtf8 => {
+ let string_array = as_generic_string_array::<i64>(&args[0])?;
+ left_impl::<i64, _>(string_array, n_array)
+ }
+ DataType::Utf8View => {
+ let string_view_array = as_string_view_array(&args[0])?;
+ left_impl_view(string_view_array, n_array)
+ }
+ _ => exec_err!("Not supported"),
}
}
+/// `left` implementation for strings
fn left_impl<'a, T: OffsetSizeTrait, V: ArrayAccessor<Item = &'a str>>(
string_array: V,
n_array: &Int64Array,
) -> Result<ArrayRef> {
let iter = ArrayIter::new(string_array);
- let mut chars_buf = Vec::new();
let result = iter
.zip(n_array.iter())
.map(|(string, n)| match (string, n) {
- (Some(string), Some(n)) => match n.cmp(&0) {
- Ordering::Less => {
- // Collect chars once and reuse for both count and take
- chars_buf.clear();
- chars_buf.extend(string.chars());
- let len = chars_buf.len() as i64;
-
- // For negative n, take (len + n) chars if n > -len (avoiding abs() which panics on i64::MIN)
- Some(if n > -len {
- chars_buf
- .iter()
- .take((len + n) as usize)
- .collect::<String>()
- } else {
- "".to_string()
- })
- }
- Ordering::Equal => Some("".to_string()),
- Ordering::Greater => {
- Some(string.chars().take(n as usize).collect::<String>())
- }
- },
+ (Some(string), Some(n)) => {
+ let byte_length = left_byte_length(string, n);
+ // Extract first `byte_length` bytes from a byte-indexed slice
+ Some(&string[0..byte_length])
+ }
_ => None,
})
.collect::<GenericStringArray<T>>();
@@ -172,10 +164,104 @@ fn left_impl<'a, T: OffsetSizeTrait, V: ArrayAccessor<Item = &'a str>>(
Ok(Arc::new(result) as ArrayRef)
}
+/// `left` implementation for StringViewArray
+fn left_impl_view(
+ string_view_array: &StringViewArray,
+ n_array: &Int64Array,
+) -> Result<ArrayRef> {
+ let len = n_array.len();
+
+ let views = string_view_array.views();
+ // Every string in StringViewArray has one corresponding view in `views`
+ debug_assert!(views.len() == string_view_array.len());
+
+ // Compose null buffer at once
+ let string_nulls = string_view_array.nulls();
+ let n_nulls = n_array.nulls();
+ let new_nulls = NullBuffer::union(string_nulls, n_nulls);
+
+ let new_views = (0..len)
+ .map(|idx| {
+ let view = views[idx];
+
+ let is_valid = match &new_nulls {
+ Some(nulls_buf) => nulls_buf.is_valid(idx),
+ None => true,
+ };
+
+ if is_valid {
+ let string: &str = string_view_array.value(idx);
+ let n = n_array.value(idx);
+
+ // Input string comes from StringViewArray, so it should fit in 32-bit length
+ let new_length: u32 = left_byte_length(string, n) as u32;
+ let byte_view = ByteView::from(view);
+ // Construct a new view
+ shrink_string_view_array_view(string, new_length, byte_view)
+ } else {
+ // For nulls, keep the original view
+ view
+ }
+ })
+ .collect::<Vec<u128>>();
+
+ // Buffers are unchanged
+ let result = StringViewArray::try_new(
+ ScalarBuffer::from(new_views),
+ Vec::from(string_view_array.data_buffers()),
+ new_nulls,
+ )?;
+ Ok(Arc::new(result) as ArrayRef)
+}
+
+/// Calculate the byte length of the substring of `n` chars from string `string`
+fn left_byte_length(string: &str, n: i64) -> usize {
+ match n.cmp(&0) {
+ Ordering::Less => string
+ .char_indices()
+ .nth_back(n.unsigned_abs() as usize - 1)
+ .map(|(index, _)| index)
+ .unwrap_or(0),
+ Ordering::Equal => 0,
+ Ordering::Greater => string
+ .char_indices()
+ .nth(n as usize)
+ .map(|(index, _)| index)
+ .unwrap_or(string.len()),
+ }
+}
+
+/// Construct a new StringViewArray view from existing view `byte_view` and new length `len`.
+/// Prefix is taken from the original string `string`.
+/// Handles both inline and non-inline views, referencing the same buffers.
+fn shrink_string_view_array_view(string: &str, len: u32, byte_view: ByteView) -> u128 {
+ debug_assert!(len <= byte_view.length);
+ // Acquire bytes view to string (no allocations)
+ let bytes = string.as_bytes();
+
+ if len <= 12 {
+ // Inline view
+ // Construct manually since ByteView cannot work with inline views
+ let mut view_buffer = [0u8; 16];
+ // 4 bytes: length
+ view_buffer[0..4].copy_from_slice(&len.to_le_bytes());
+ // 12 bytes: the whole zero-padded string
+ view_buffer[4..4 + len as usize].copy_from_slice(&bytes[..len as usize]);
+ u128::from_le_bytes(view_buffer)
+ } else {
+ // Non-inline view.
+ // Use ByteView constructor to reference existing buffers
+ let new_byte_view = ByteView::new(len, &bytes[..4])
+ .with_buffer_index(byte_view.buffer_index)
+ .with_offset(byte_view.offset);
+ new_byte_view.as_u128()
+ }
+}
+
#[cfg(test)]
mod tests {
- use arrow::array::{Array, StringArray};
- use arrow::datatypes::DataType::Utf8;
+ use arrow::array::{Array, StringArray, StringViewArray};
+ use arrow::datatypes::DataType::{Utf8, Utf8View};
use datafusion_common::{Result, ScalarValue};
use datafusion_expr::{ColumnarValue, ScalarUDFImpl};
@@ -218,6 +304,17 @@ mod tests {
Utf8,
StringArray
);
+ test_function!(
+ LeftFunc::new(),
+ vec![
+ ColumnarValue::Scalar(ScalarValue::from("abcde")),
+ ColumnarValue::Scalar(ScalarValue::from(i64::MIN)),
+ ],
+ Ok(Some("")),
+ &str,
+ Utf8,
+ StringArray
+ );
test_function!(
LeftFunc::new(),
vec![
@@ -299,6 +396,74 @@ mod tests {
StringArray
);
+ // StringView cases
+ test_function!(
+ LeftFunc::new(),
+ vec![
+ ColumnarValue::Scalar(ScalarValue::Utf8View(Some("abcde".to_string()))),
+ ColumnarValue::Scalar(ScalarValue::from(2i64)),
+ ],
+ Ok(Some("ab")),
+ &str,
+ Utf8View,
+ StringViewArray
+ );
+ test_function!(
+ LeftFunc::new(),
+ vec![
+ ColumnarValue::Scalar(ScalarValue::Utf8View(Some("abcde".to_string()))),
+ ColumnarValue::Scalar(ScalarValue::from(200i64)),
+ ],
+ Ok(Some("abcde")),
+ &str,
+ Utf8View,
+ StringViewArray
+ );
+ test_function!(
+ LeftFunc::new(),
+ vec![
+ ColumnarValue::Scalar(ScalarValue::Utf8View(Some("".to_string()))),
+ ColumnarValue::Scalar(ScalarValue::from(200i64)),
+ ],
+ Ok(Some("")),
+ &str,
+ Utf8View,
+ StringViewArray
+ );
+ test_function!(
+ LeftFunc::new(),
+ vec![
+ ColumnarValue::Scalar(ScalarValue::Utf8View(Some(
+ "joséésoj".to_string()
+ ))),
+ ColumnarValue::Scalar(ScalarValue::from(-3i64)),
+ ],
+ Ok(Some("joséé")),
+ &str,
+ Utf8View,
+ StringViewArray
+ );
+
+ // Unicode indexing case
+ let input = "joé楽s𐀀so↓j";
+ for n in 1..=input.chars().count() {
+ let expected = input
+ .chars()
+ .take(input.chars().count() - n)
+ .collect::<String>();
+ test_function!(
+ LeftFunc::new(),
+ vec![
+ ColumnarValue::Scalar(ScalarValue::from(input)),
+ ColumnarValue::Scalar(ScalarValue::from(-(n as i64))),
+ ],
+ Ok(Some(expected.as_str())),
+ &str,
+ Utf8,
+ StringArray
+ );
+ }
+
Ok(())
}
}
diff --git a/datafusion/sqllogictest/test_files/scalar.slt b/datafusion/sqllogictest/test_files/scalar.slt
index 3e03ab00c8..4206d4c65e 100644
--- a/datafusion/sqllogictest/test_files/scalar.slt
+++ b/datafusion/sqllogictest/test_files/scalar.slt
@@ -1993,10 +1993,10 @@ query TT
EXPLAIN SELECT letter, letter = LEFT(letter2, 1) FROM simple_string;
----
logical_plan
-01)Projection: simple_string.letter, simple_string.letter = CAST(left(simple_string.letter2, Int64(1)) AS Utf8View)
+01)Projection: simple_string.letter, simple_string.letter = left(simple_string.letter2, Int64(1))
02)--TableScan: simple_string projection=[letter, letter2]
physical_plan
-01)ProjectionExec: expr=[letter@0 as letter, letter@0 = CAST(left(letter2@1, 1) AS Utf8View) as simple_string.letter = left(simple_string.letter2,Int64(1))]
+01)ProjectionExec: expr=[letter@0 as letter, letter@0 = left(letter2@1, 1) as simple_string.letter = left(simple_string.letter2,Int64(1))]
02)--DataSourceExec: partitions=1, partition_sizes=[1]
query TB