diff --git a/vortex-duckdb/src/exporter/mod.rs b/vortex-duckdb/src/exporter/mod.rs index 59a0e7fe728..fe0333ef1cf 100644 --- a/vortex-duckdb/src/exporter/mod.rs +++ b/vortex-duckdb/src/exporter/mod.rs @@ -157,7 +157,7 @@ impl ArrayExporter { /// the offset, len and `WritableVector` as options. Not sure what it should return though? /// This would allow Vortex extension authors to plug into the DuckDB exporter system. pub trait ColumnExporter: 'static { - /// The dictionary parts of this exporter, if it exports DuckDB dictionary vectors. + /// The dictionary parts of this exporter, if it can export DuckDB dictionary vectors. /// /// A chunked exporter uses them to export a range across chunks as one dictionary vector. fn as_dictionary(&self) -> Option<&dyn DictionaryParts> { @@ -175,6 +175,9 @@ pub trait ColumnExporter: 'static { } /// The values and codes of an exporter that emits DuckDB dictionary vectors. +/// +/// Codes can be generated per request rather than stored for the whole array. This capability also +/// applies when the exporter uses a constant vector for a request contained in one run. pub trait DictionaryParts { /// The DuckDB vector of the dictionary values. fn values(&self) -> &ReusableDict; @@ -183,6 +186,9 @@ pub trait DictionaryParts { fn values_key(&self) -> usize; /// Write the codes of rows `offset..offset + codes.len()` into `codes`. + /// + /// The offset is relative to the exported array, including any slice. The range must lie within + /// that array, and every code must index [`Self::values`], including codes for null rows. fn write_codes(&self, offset: usize, codes: &mut [u32]); } diff --git a/vortex-duckdb/src/exporter/run_end.rs b/vortex-duckdb/src/exporter/run_end.rs index fbe0120850a..d455dc3cc1e 100644 --- a/vortex-duckdb/src/exporter/run_end.rs +++ b/vortex-duckdb/src/exporter/run_end.rs @@ -1,15 +1,20 @@ // SPDX-License-Identifier: Apache-2.0 // SPDX-FileCopyrightText: Copyright the Vortex contributors +//! Batch-sized run selections over a cached DuckDB values dictionary. +//! +//! [`DictionaryParts`] lets the chunked exporter join run-end and dictionary chunks that share +//! values without flattening them. Codes are expanded only for the requested batch. Routing through +//! [`RunEndArray::to_dict`] would make the generic dictionary exporter materialize all codes at setup. + use std::marker::PhantomData; use vortex::array::ArrayRef; +use vortex::array::Canonical; use vortex::array::ExecutionCtx; use vortex::array::IntoArray; use vortex::array::arrays::PrimitiveArray; use vortex::array::match_each_integer_ptype; -use vortex::array::search_sorted::SearchSorted; -use vortex::array::search_sorted::SearchSortedSide; use vortex::dtype::IntegerPType; use vortex::encodings::runend::RunEndArray; use vortex::encodings::runend::RunEndArrayExt; @@ -22,17 +27,18 @@ use crate::duckdb::ReusableDict; use crate::duckdb::SelectionVector; use crate::duckdb::VectorRef; use crate::exporter::ColumnExporter; +use crate::exporter::DictionaryParts; use crate::exporter::cache::ConversionCache; use crate::exporter::cached_values_dict; use crate::exporter::canonical; -/// We export run-end arrays to a DuckDB dictionary vector. Values are exported -/// into a ReusableDict with SelectionVector applied in export(). +/// Keeps the values dictionary cached while generating selections for each requested batch. struct RunEndExporter { ends: PrimitiveArray, ends_type: PhantomData, values: ArrayRef, values_dict: ReusableDict, + /// Added to request offsets because sliced run ends retain their source coordinates. run_end_offset: usize, } @@ -42,8 +48,11 @@ pub(crate) fn new_exporter_with_flatten( ctx: &mut ExecutionCtx, flatten: bool, ) -> VortexResult> { - // Our canonicalization is faster than creating a dictionary vector and - // letting duckdb flatten it for us. + if array.is_empty() { + return canonical::new_exporter(Canonical::empty(array.dtype()).into_array(), cache, ctx); + } + + // Canonicalize directly to avoid building a dictionary that DuckDB would immediately flatten. if flatten { return canonical::new_exporter(array.into_array(), cache, ctx); } @@ -65,7 +74,73 @@ pub(crate) fn new_exporter_with_flatten( }) } +impl RunEndExporter { + /// Finds the run containing an absolute row offset. Run ends are exclusive. + /// + /// The offset must refer to an existing row, rather than the end of an empty request. + fn first_run(&self, offset: usize) -> usize { + let offset = + E::from_usize(offset).vortex_expect("the request offset fits the run-end type"); + self.ends + .as_slice::() + .partition_point(|&end| end <= offset) + } + + /// Fills a non-empty request with indices into the original values child. + /// + /// `offset` is absolute, and `first_run` must be the index returned by [`Self::first_run`]. + fn write_run_codes(&self, offset: usize, first_run: usize, codes: &mut [u32]) { + let mut position = + E::from_usize(offset).vortex_expect("the request offset fits the run-end type"); + let end_offset = position + + E::from_usize(codes.len()).vortex_expect("the request length fits the run-end type"); + let mut remaining = codes; + + for (index, &end) in self.ends.as_slice::()[first_run..].iter().enumerate() { + let next_end = end.min(end_offset); + let run_len = (next_end - position) + .to_usize() + .vortex_expect("run length fits usize"); + let code = u32::try_from(first_run + index).vortex_expect("run index exceeds u32"); + remaining[..run_len].fill(code); + remaining = &mut remaining[run_len..]; + if remaining.is_empty() { + return; + } + position = next_end; + } + + assert!( + remaining.is_empty(), + "run ends must cover the requested range" + ); + } +} + +impl DictionaryParts for RunEndExporter { + fn values(&self) -> &ReusableDict { + &self.values_dict + } + + fn values_key(&self) -> usize { + self.values.addr() + } + + fn write_codes(&self, offset: usize, codes: &mut [u32]) { + if codes.is_empty() { + return; + } + + let offset = self.run_end_offset + offset; + self.write_run_codes(offset, self.first_run(offset), codes); + } +} + impl ColumnExporter for RunEndExporter { + fn as_dictionary(&self) -> Option<&dyn DictionaryParts> { + Some(self) + } + fn export( &self, offset: usize, @@ -73,76 +148,75 @@ impl ColumnExporter for RunEndExporter { vector: &mut VectorRef, ctx: &mut ExecutionCtx, ) -> VortexResult<()> { - let ends_slice = self.ends.as_slice::(); - - // Adjust offset to account for the run-end offset. - let mut offset = E::from_usize(self.run_end_offset + offset) - .vortex_expect("RunEndExporter::export: offset is not a valid value"); - // Compute the final end offset. - let end_offset = offset + E::from_usize(len).vortex_expect("len is not end type"); - - // Find the run that contains the start offset. - let start_run_idx = ends_slice - .search_sorted(&offset, SearchSortedSide::Right)? - .to_ends_index(ends_slice.len()); - - // Find the final run in case we can short-circuit and return a constant vector. - let end_run_idx = ends_slice - .search_sorted(&end_offset, SearchSortedSide::Right)? - .to_ends_index(ends_slice.len()); - - if start_run_idx == end_run_idx { - // NOTE(ngates): would be great if we could just export and set type == CONSTANT - // self.values_exporter.export(start_run_idx, 1, vector, cache); - let constant = self.values.execute_scalar(start_run_idx, ctx)?; - let value = constant.try_to_duckdb_scalar()?; - vector.reference_value(&value); + if len == 0 { return Ok(()); } - // Build up a selection vector - let mut sel_vec = SelectionVector::with_capacity(len); - let mut sel_vec_slice = unsafe { sel_vec.as_slice_mut(len) }; - - for (run_idx, &next_end) in ends_slice[start_run_idx..=end_run_idx].iter().enumerate() { - let next_end = next_end.min(end_offset); - let run_len = (next_end - offset) - .to_usize() - .vortex_expect("run_len is usize"); - - let global_run_idx = - u32::try_from(start_run_idx + run_idx).vortex_expect("run index exceeds u32"); - sel_vec_slice[..run_len].fill(global_run_idx); - sel_vec_slice = &mut sel_vec_slice[run_len..]; + let offset = self.run_end_offset + offset; + let first_run = self.first_run(offset); + let end = + E::from_usize(offset + len).vortex_expect("the request end fits the run-end type"); - offset = next_end; + // The request end is exclusive, so equality still leaves every row inside this run. + if end <= self.ends.as_slice::()[first_run] { + let constant = self.values.execute_scalar(first_run, ctx)?; + let value = constant.try_to_duckdb_scalar()?; + vector.reference_value(&value); + return Ok(()); } - debug_assert!(sel_vec_slice.is_empty()); - vector.reuse_dictionary(&self.values_dict, &sel_vec, len); + let mut selection = SelectionVector::with_capacity(len); + // SAFETY: the selection has capacity for `len` entries. The validated run ends cover the + // requested range, and write_run_codes fills every entry before DuckDB reads the selection. + let codes = unsafe { selection.as_slice_mut(len) }; + self.write_run_codes(offset, first_run, codes); + vector.reuse_dictionary(&self.values_dict, &selection, len); + Ok(()) } } #[cfg(test)] mod tests { + use rstest::rstest; + use vortex::array::ArrayRef; use vortex::array::IntoArray; use vortex::array::VortexSessionExecute; use vortex::array::arrays::ChunkedArray; + use vortex::array::arrays::DictArray; use vortex::array::arrays::PrimitiveArray; use vortex::array::arrays::StructArray; + use vortex::buffer::Buffer; use vortex::buffer::buffer; use vortex::encodings::runend::RunEnd; use vortex::error::VortexResult; use crate::SESSION; - use crate::cpp::duckdb_type::DUCKDB_TYPE_INTEGER; use crate::duckdb::DataChunk; use crate::duckdb::LogicalType; use crate::exporter::ArrayExporter; use crate::exporter::ConversionCache; use crate::exporter::new_array_exporter; + #[track_caller] + fn check_exports(array: ArrayRef, requests: &[(usize, usize, &str)]) -> VortexResult<()> { + let mut ctx = SESSION.create_execution_ctx(); + let exporter = new_array_exporter(array, &ConversionCache::default(), &mut ctx)?; + let mut chunk = DataChunk::new([LogicalType::int32()]); + + for &(offset, len, expected) in requests { + chunk.reset(); + exporter.export(offset, len, chunk.get_vector_mut(0), &mut ctx)?; + chunk.set_len(len); + assert_eq!( + String::try_from(&*chunk)?, + format!("Chunk - [1 Columns]\n{expected}\n") + ); + } + + Ok(()) + } + #[test] fn test_one_chunk_null() -> VortexResult<()> { let mut ctx = SESSION.create_execution_ctx(); @@ -150,22 +224,10 @@ mod tests { let array = PrimitiveArray::from_option_iter(source); let array = RunEnd::encode(array.into_array(), &mut ctx)?; - let mut chunk = DataChunk::new([LogicalType::new(DUCKDB_TYPE_INTEGER)]); - new_array_exporter(array.into_array(), &ConversionCache::default(), &mut ctx)?.export( - 0, - 5, - chunk.get_vector_mut(0), - &mut ctx, - )?; - chunk.set_len(5); - let chunk_str = String::try_from(&*chunk)?; - assert_eq!( - chunk_str, - r#"Chunk - [1 Columns] -- DICTIONARY INTEGER: 5 = [ 0, 1, NULL, 3, NULL] -"# - ); - Ok(()) + check_exports( + array.into_array(), + &[(0, 5, "- DICTIONARY INTEGER: 5 = [ 0, 1, NULL, 3, NULL]")], + ) } #[test] @@ -191,4 +253,85 @@ mod tests { assert!(!exporter.export(&mut chunk, None)?); Ok(()) } + + #[test] + fn sliced_batches_keep_run_boundaries() -> VortexResult<()> { + let mut ctx = SESSION.create_execution_ctx(); + let array = RunEnd::try_new_offset_length( + buffer![3u32, 5, 8].into_array(), + PrimitiveArray::from_option_iter([Some(10i32), None, Some(30)]).into_array(), + 2, + 5, + &mut ctx, + )?; + + check_exports( + array.into_array(), + &[ + (0, 1, "- CONSTANT INTEGER: 1 = [ 10]"), // Exact first run end. + (1, 2, "- CONSTANT INTEGER: 2 = [ NULL]"), // Exact null run. + (2, 3, "- DICTIONARY INTEGER: 3 = [ NULL, 30, 30]"), // Clipped batch. + (5, 0, "- FLAT INTEGER: 0 = [ ]"), // Empty request at the end. + ], + ) + } + + #[test] + fn empty_arrays_do_not_cache_values() -> VortexResult<()> { + let mut ctx = SESSION.create_execution_ctx(); + let values = buffer![10i32].into_array(); + let retained = + RunEnd::try_new_offset_length(buffer![3u32].into_array(), values, 3, 0, &mut ctx)?; + let empty = RunEnd::try_new( + Buffer::::empty().into_array(), + Buffer::::empty().into_array(), + &mut ctx, + )?; + + for array in [empty, retained] { + let cache = ConversionCache::default(); + let exporter = new_array_exporter(array.into_array(), &cache, &mut ctx)?; + let mut chunk = DataChunk::new([LogicalType::int32()]); + exporter.export(0, 0, chunk.get_vector_mut(0), &mut ctx)?; + assert!(cache.dict_cache.is_empty()); + } + + Ok(()) + } + + #[rstest] + #[case::runend(false, true)] + #[case::dictionary(true, true)] + #[case::different_values(false, false)] + fn chunk_boundaries(#[case] dictionary: bool, #[case] shared: bool) -> VortexResult<()> { + let mut ctx = SESSION.create_execution_ctx(); + let values = PrimitiveArray::from_option_iter([Some(10i32), None, Some(30)]).into_array(); + let first = RunEnd::try_new_offset_length( + buffer![2u32, 4, 6].into_array(), + values.clone(), + 2, + 4, + &mut ctx, + )? + .into_array(); + let next_values = if shared { + values + } else { + PrimitiveArray::from_option_iter([Some(10i32), None, Some(30)]).into_array() + }; + let second = if dictionary { + DictArray::try_new(buffer![0u32, 1, 1, 2].into_array(), next_values)?.into_array() + } else { + RunEnd::try_new(buffer![1u32, 3, 4].into_array(), next_values, &mut ctx)?.into_array() + }; + let dtype = first.dtype().clone(); + let array = ChunkedArray::try_new(vec![first, second], dtype)?.into_array(); + let crossing = if shared { + "- DICTIONARY INTEGER: 6 = [ NULL, 30, 30, 10, NULL, NULL]" + } else { + "- FLAT INTEGER: 6 = [ NULL, 30, 30, 10, NULL, NULL]" + }; + + check_exports(array, &[(1, 6, crossing)]) + } }