From 2cb8ddb785f70d0e84cfe0efe8094dce5dbe58a3 Mon Sep 17 00:00:00 2001 From: Connor Tsui Date: Wed, 26 Aug 2026 11:42:14 -0400 Subject: [PATCH] Add filter-and-scatter RowFn execution Signed-off-by: Connor Tsui --- .../unstable/row/batch/execute/dense.rs | 12 +- .../row/batch/execute/filter_scatter.rs | 95 ++++++++ .../unstable/row/batch/execute/mod.rs | 8 +- .../unstable/row/batch/execute/valid_only.rs | 19 +- .../src/scalar_fn/unstable/row/batch/mod.rs | 2 +- .../src/scalar_fn/unstable/row/batch/tests.rs | 227 +++++++++++++++++- .../scalar_fn/unstable/row/types/sink/mod.rs | 3 +- .../scalar_fn/unstable/row/visitor/plan.rs | 2 +- 8 files changed, 335 insertions(+), 33 deletions(-) create mode 100644 vortex-array/src/scalar_fn/unstable/row/batch/execute/filter_scatter.rs diff --git a/vortex-array/src/scalar_fn/unstable/row/batch/execute/dense.rs b/vortex-array/src/scalar_fn/unstable/row/batch/execute/dense.rs index a0ba7e1e72a..099f0cfd135 100644 --- a/vortex-array/src/scalar_fn/unstable/row/batch/execute/dense.rs +++ b/vortex-array/src/scalar_fn/unstable/row/batch/execute/dense.rs @@ -3,7 +3,6 @@ use vortex_error::VortexError; use vortex_error::VortexResult; -use vortex_error::vortex_panic; use vortex_mask::Mask; use vortex_mask::MaskValuesRef; @@ -34,6 +33,7 @@ impl RowFnExecutionArgs { /// recompute the error. pub(super) fn execute_dense_with_retry( &self, + kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult, execute_dense_attempt: impl FnOnce( BorrowedRowFnArgs<'_>, &mut ExecutionCtx, @@ -51,7 +51,7 @@ impl RowFnExecutionArgs { match attempt { DenseAttempt::Values(values) => self.finalize_dense_output(values, ctx), DenseAttempt::DeferredError(error) => { - self.resolve_deferred_error(error, try_valid_rows, ctx) + self.resolve_deferred_error(error, kernel, try_valid_rows, ctx) } } } @@ -59,6 +59,7 @@ impl RowFnExecutionArgs { fn resolve_deferred_error( &self, deferred_error: VortexError, + kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult, try_valid_rows: impl FnOnce( BorrowedRowFnArgs<'_>, MaskValuesRef, @@ -80,14 +81,11 @@ impl RowFnExecutionArgs { // retrying only observable rows. drop(deferred_error); - if let Some(result) = self.try_execute_valid_rows(try_valid_rows, valid_rows, ctx)? { + if let Some(result) = self.try_execute_valid_rows(try_valid_rows, &valid_rows, ctx)? { return Ok(result); } - vortex_panic!( - "dense retry requires direct valid-row support after a deferred error, but {} declined it", - self.id, - ) + self.filter_and_scatter(kernel, &valid_rows, ctx) } fn finalize_dense_output( diff --git a/vortex-array/src/scalar_fn/unstable/row/batch/execute/filter_scatter.rs b/vortex-array/src/scalar_fn/unstable/row/batch/execute/filter_scatter.rs new file mode 100644 index 00000000000..988b59105e9 --- /dev/null +++ b/vortex-array/src/scalar_fn/unstable/row/batch/execute/filter_scatter.rs @@ -0,0 +1,95 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +//! Fallback execution for row kernels that cannot operate on the original partially valid inputs. +//! +//! Direct skip-invalid execution retains the original row domain: it decodes every input column, +//! initializes a full-length output, and visits only valid rows. Some input representations cannot +//! decode unspecified payloads behind nulls, and some output sinks cannot initialize rows that the +//! kernel skips. In either case, there is no safe row loop to enter over the original columns. +//! +//! This fallback filters every input to the valid row domain before decoding it. The ordinary +//! kernel then produces a compact, all-valid output. A take with nullable indices scatters those +//! values back to the original row domain and restores its nulls. +//! +//! Filtering and scattering add columnar work around the row loop. Filtering nested or compressed +//! inputs can also materialize their selected representation. Batch execution therefore tries +//! direct skip-invalid execution first and uses this path only when a required capability is +//! unavailable. +//! +//! A prepared, type-specific view can provide selected-row decoding without filtering. That is an +//! optional direct-execution capability rather than a replacement for this fallback: it requires a +//! representation with safe selected access, and it does not initialize an output sink that cannot +//! represent skipped rows. Calling the general scalar-extraction API once per valid row is also not +//! equivalent because it repeats array execution and scalar construction inside the row loop. + +use smallvec::SmallVec; +use vortex_error::VortexResult; +use vortex_mask::Mask; +use vortex_mask::MaskValuesRef; + +use super::super::RowFnExecutionArgs; +use super::super::args::BorrowedRowFnArgs; +use crate::ArrayRef; +use crate::ExecutionCtx; +use crate::IntoArray; +use crate::arrays::PrimitiveArray; +use crate::dtype::Nullability; +use crate::validity::Validity; + +impl RowFnExecutionArgs { + /// Filter the original batch to valid rows, run the kernel, then restore its row count. + pub(super) fn filter_and_scatter( + &self, + kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult, + original_validity: &MaskValuesRef, + ctx: &mut ExecutionCtx, + ) -> VortexResult { + let original_len = original_validity.len(); + let filtered_len = original_validity.true_count(); + let filter_mask = Mask::Values(MaskValuesRef::clone(original_validity)); + + let filtered_inputs: SmallVec<[ArrayRef; 4]> = self + .inputs + .iter() + .map(|input| input.filter(filter_mask.clone())) + .collect::>()?; + + let filtered_args = self.execution_args(&filtered_inputs, filtered_len); + let filtered = kernel(filtered_args, ctx)?; + let filtered = self.validate_kernel_output(filtered, filtered_len, ctx)?; + + let output = Self::scatter_to_original_rows(filtered, original_validity)?; + + self.finalize_output(output, original_len) + } + + /// Scatter `filtered` back to the rows selected by `original_validity`. + fn scatter_to_original_rows( + filtered: ArrayRef, + original_validity: &MaskValuesRef, + ) -> VortexResult { + let original_len = original_validity.len(); + let mut take_indices = vec![0u64; original_len]; + + let valid_rows = original_validity + .slices() + .iter() + .flat_map(|&(start, end)| start..end); + for (filtered_index, original_index) in valid_rows.enumerate() { + take_indices[original_index] = u64::try_from(filtered_index)?; + } + + // Null indices restore invalid rows without selecting a value from the compact output. + let take_indices = PrimitiveArray::new( + take_indices, + Validity::from_mask( + Mask::Values(MaskValuesRef::clone(original_validity)), + Nullability::Nullable, + ), + ) + .into_array(); + + filtered.take(take_indices) + } +} diff --git a/vortex-array/src/scalar_fn/unstable/row/batch/execute/mod.rs b/vortex-array/src/scalar_fn/unstable/row/batch/execute/mod.rs index 32cdee5ed0a..322cd497ac2 100644 --- a/vortex-array/src/scalar_fn/unstable/row/batch/execute/mod.rs +++ b/vortex-array/src/scalar_fn/unstable/row/batch/execute/mod.rs @@ -21,6 +21,7 @@ use crate::validity::Validity; mod constant; mod dense; +mod filter_scatter; mod valid_only; mod output; @@ -29,8 +30,9 @@ pub(crate) use output::finalize_kernel_output; impl RowFnExecutionArgs { /// Apply constant folding and null handling around `kernel`. /// - /// For a partially valid batch, `try_valid_rows` executes only valid rows over the original - /// inputs. Every result is checked against the planned shape and dtype. + /// For a partially valid batch, `try_valid_rows` can avoid filtering. `Ok(None)` filters the + /// valid rows and scatters the output back. Every result is checked against the planned shape + /// and dtype. pub(crate) fn execute( &self, kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult, @@ -76,7 +78,7 @@ impl RowFnExecutionArgs { match self.plan.policy() { RowPolicy::Dense => self.execute_dense(kernel, ctx), RowPolicy::DenseWithRetry => { - self.execute_dense_with_retry(execute_dense_attempt, try_valid_rows, ctx) + self.execute_dense_with_retry(kernel, execute_dense_attempt, try_valid_rows, ctx) } RowPolicy::ValidOnly => self.execute_valid_only(kernel, try_valid_rows, ctx), } diff --git a/vortex-array/src/scalar_fn/unstable/row/batch/execute/valid_only.rs b/vortex-array/src/scalar_fn/unstable/row/batch/execute/valid_only.rs index ea1324c2ee7..a05a476a838 100644 --- a/vortex-array/src/scalar_fn/unstable/row/batch/execute/valid_only.rs +++ b/vortex-array/src/scalar_fn/unstable/row/batch/execute/valid_only.rs @@ -2,7 +2,6 @@ // SPDX-FileCopyrightText: Copyright the Vortex contributors use vortex_error::VortexResult; -use vortex_error::vortex_panic; use vortex_mask::Mask; use vortex_mask::MaskValuesRef; @@ -14,12 +13,7 @@ use crate::IntoArray; use crate::builtins::ArrayBuiltins; impl RowFnExecutionArgs { - /// Resolve validity, then execute valid rows over the original inputs. - /// - /// # Panics - /// - /// Panics if the concrete row signature cannot use direct valid-row execution. Inputs must - /// support null-tolerant decoding, and output sinks must initialize skipped rows. + /// Resolve validity and try direct valid-row execution before filter-and-scatter. pub(super) fn execute_valid_only( &self, kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult, @@ -44,14 +38,11 @@ impl RowFnExecutionArgs { Mask::Values(valid_rows) => valid_rows, }; - if let Some(result) = self.try_execute_valid_rows(try_valid_rows, valid_rows, ctx)? { + if let Some(result) = self.try_execute_valid_rows(try_valid_rows, &valid_rows, ctx)? { return Ok(result); } - vortex_panic!( - "valid-only execution requires direct valid-row support; {} selected an unsupported signature", - self.id, - ) + self.filter_and_scatter(kernel, &valid_rows, ctx) } /// Try execution against the original inputs, then mask a returned full-length result. @@ -62,12 +53,12 @@ impl RowFnExecutionArgs { MaskValuesRef, &mut ExecutionCtx, ) -> VortexResult>, - valid: MaskValuesRef, + valid: &MaskValuesRef, ctx: &mut ExecutionCtx, ) -> VortexResult> { let Some(values) = try_valid_rows( self.execution_args(&self.inputs, self.row_count), - MaskValuesRef::clone(&valid), + MaskValuesRef::clone(valid), ctx, )? else { diff --git a/vortex-array/src/scalar_fn/unstable/row/batch/mod.rs b/vortex-array/src/scalar_fn/unstable/row/batch/mod.rs index 36b6c246a27..26e5815bb68 100644 --- a/vortex-array/src/scalar_fn/unstable/row/batch/mod.rs +++ b/vortex-array/src/scalar_fn/unstable/row/batch/mod.rs @@ -39,7 +39,7 @@ pub(crate) struct RowFnExecutionArgs { /// The number of rows in the original execution scope. row_count: usize, - /// The input columns, collected once for validity, constant handling, and execution. + /// The input columns, collected once for validity, constant folding, filtering, and execution. inputs: SmallVec<[ArrayRef; 4]>, /// The input dtypes, collected with the columns and reused by both planning and execution. diff --git a/vortex-array/src/scalar_fn/unstable/row/batch/tests.rs b/vortex-array/src/scalar_fn/unstable/row/batch/tests.rs index 99e2c074373..196bc37cbe1 100644 --- a/vortex-array/src/scalar_fn/unstable/row/batch/tests.rs +++ b/vortex-array/src/scalar_fn/unstable/row/batch/tests.rs @@ -62,6 +62,15 @@ impl DeferredAdd { #[derive(Clone)] struct ValidOnlyIdentity; +#[derive(Clone)] +struct FilterAndScatterIdentity; + +#[derive(Clone)] +struct DenseRetryIncrement; + +#[derive(Clone)] +struct FilterAndScatterRepeat; + #[derive(Clone)] struct InvalidKernelOutput; @@ -76,6 +85,10 @@ struct NullaryTrue; struct ValidOnlyI64; +struct FilterOnlyI64; + +struct DenseRetryI64; + // SAFETY: the view is a slice, and its reported length is the buffer length. unsafe impl InputElement for ValidOnlyI64 { type Column = Buffer; @@ -110,6 +123,72 @@ unsafe impl InputElement for ValidOnlyI64 { } } +// SAFETY: the view is a slice, and its reported length is the buffer length. +unsafe impl InputElement for FilterOnlyI64 { + type Column = Buffer; + type View<'a> = &'a [i64]; + type Elem<'a> = i64; + + const DENSE_SAFE: bool = false; + const DECODE_INFALLIBLE: bool = false; + + fn validate(dtype: &DType) -> VortexResult<()> { + ::validate(dtype) + } + + fn decode(array: ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult { + let values = ::decode(array, ctx)?; + vortex_ensure!( + !values.as_slice().contains(&i64::MIN), + "test input contains an invalid payload", + ); + + Ok(values) + } + + fn get(column: &Self::Column, index: usize) -> Self::Elem<'_> { + column[index] + } + + fn view(column: &Self::Column) -> Self::View<'_> { + column.as_slice() + } + + fn get_from_view<'a>(view: &Self::View<'a>, index: usize) -> Self::Elem<'a> { + view[index] + } +} + +// SAFETY: the view is a slice, and its reported length is the buffer length. +unsafe impl InputElement for DenseRetryI64 { + type Column = Buffer; + type View<'a> = &'a [i64]; + type Elem<'a> = i64; + + const DENSE_SAFE: bool = true; + const DECODE_INFALLIBLE: bool = true; + + fn validate(dtype: &DType) -> VortexResult<()> { + ::validate(dtype) + } + + fn decode(array: ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult { + ::decode(array, ctx) + } + + fn get(column: &Self::Column, index: usize) -> Self::Elem<'_> { + column[index] + } + + fn view(column: &Self::Column) -> Self::View<'_> { + column.as_slice() + } + + fn get_from_view<'a>(view: &Self::View<'a>, index: usize) -> Self::Elem<'a> { + view[index] + } +} + /// Produces a null row to exercise output validation at the row-function boundary. #[derive(Default)] struct NullProducingI64(i64); @@ -250,6 +329,87 @@ impl RowFn for ValidOnlyIdentity { } } +impl RowFn for FilterAndScatterIdentity { + type Options = EmptyOptions; + + const ARG_NAMES: &'static [&'static str] = &["value"]; + const INFALLIBLE: bool = false; + + fn id(&self) -> ScalarFnId { + static ID: CachedId = CachedId::new("test.filter_and_scatter_identity"); + *ID + } + + fn dispatch( + &self, + _options: &Self::Options, + _args: &[DType], + visitor: V, + ) -> VortexResult { + visitor.visit::<(FilterOnlyI64,), i64>(|(value,)| value) + } +} + +impl RowFn for DenseRetryIncrement { + type Options = EmptyOptions; + + const ARG_NAMES: &'static [&'static str] = &["value"]; + const INFALLIBLE: bool = false; + + fn id(&self) -> ScalarFnId { + static ID: CachedId = CachedId::new("test.dense_retry_increment"); + *ID + } + + fn dispatch( + &self, + _options: &Self::Options, + _args: &[DType], + visitor: V, + ) -> VortexResult { + visitor.visit_deferred::<(DenseRetryI64,), i64, bool>( + |(value,)| value.overflowing_add(1), + |overflowed| { + if overflowed { + vortex_bail!(InvalidArgument: "deferred increment overflowed"); + } + + Ok(()) + }, + ) + } +} + +impl RowFn for FilterAndScatterRepeat { + type Options = usize; + + const ARG_NAMES: &'static [&'static str] = &["value"]; + const INFALLIBLE: bool = true; + + fn id(&self) -> ScalarFnId { + static ID: CachedId = CachedId::new("test.filter_and_scatter_repeat"); + *ID + } + + fn dispatch( + &self, + width: &Self::Options, + _args: &[DType], + visitor: V, + ) -> VortexResult { + vortex_ensure!( + u32::try_from(*width).is_ok(), + InvalidArgument: + "test.filter_and_scatter_repeat width must fit in u32, got {width}", + ); + + visitor + .visit_into::<(FilterOnlyI64,), FixedSizeListSink, _>(*width, |(value,), row| { + InitializedRow::fill(row, |_| value) + }) + } +} + impl RowFn for InvalidKernelOutput { type Options = EmptyOptions; @@ -502,6 +662,47 @@ fn test_valid_only_bool_output_skips_invalid_rows() -> VortexResult<()> { Ok(()) } +#[test] +fn test_filter_and_scatter_skips_invalid_decode_payloads() -> VortexResult<()> { + let validity = Validity::from_iter([false, true, false, true]); + let input = + PrimitiveArray::new(vec![i64::MIN, 10, i64::MIN, 30], validity.clone()).into_array(); + let args = VecExecutionArgs::new(vec![input], 4); + let mut ctx = array_session().create_execution_ctx(); + + let actual = execute_rows(&FilterAndScatterIdentity, &EmptyOptions, &args, &mut ctx)?; + let expected = PrimitiveArray::new(vec![0_i64, 10, 0, 30], validity).into_array(); + + assert_arrays_eq!(&actual, &expected, &mut ctx); + Ok(()) +} + +#[rstest] +#[case::width_two(2, vec![0_i64, 0, 7, 7])] +#[case::zero_width(0, vec![])] +fn test_filter_and_scatter_preserves_runtime_sink_params( + #[case] width: usize, + #[case] expected_elements: Vec, +) -> VortexResult<()> { + let validity = Validity::from_iter([false, true]); + let input = PrimitiveArray::new(vec![i64::MIN, 7], validity.clone()).into_array(); + let args = VecExecutionArgs::new(vec![input], 2); + let mut ctx = array_session().create_execution_ctx(); + + let actual = execute_rows(&FilterAndScatterRepeat, &width, &args, &mut ctx)?; + let expected = FixedSizeListArray::new( + PrimitiveArray::from_iter(expected_elements).into_array(), + u32::try_from(width) + .map_err(|_| vortex_err!(InvalidArgument: "test width must fit in u32, got {width}"))?, + validity, + 2, + ) + .into_array(); + + assert_arrays_eq!(&actual, &expected, &mut ctx); + Ok(()) +} + #[test] fn test_deferred_owned_execution_retries_null_row_failure() -> VortexResult<()> { let function = DeferredAdd::default(); @@ -519,6 +720,20 @@ fn test_deferred_owned_execution_retries_null_row_failure() -> VortexResult<()> Ok(()) } +#[test] +fn test_dense_retry_filters_when_direct_valid_rows_are_unavailable() -> VortexResult<()> { + let validity = Validity::from_iter([true, false, true]); + let input = PrimitiveArray::new(vec![1_i64, i64::MAX, 3], validity.clone()).into_array(); + let args = VecExecutionArgs::new(vec![input], 3); + let mut ctx = array_session().create_execution_ctx(); + + let actual = execute_rows(&DenseRetryIncrement, &EmptyOptions, &args, &mut ctx)?; + let expected = PrimitiveArray::new(vec![2_i64, 0, 4], validity).into_array(); + + assert_arrays_eq!(&actual, &expected, &mut ctx); + Ok(()) +} + #[test] fn test_deferred_owned_execution_does_not_retry_partially_valid_success() -> VortexResult<()> { let function = DeferredAdd::default(); @@ -737,17 +952,17 @@ fn test_declared_output_dtype_labels_batch(#[case] validity: Validity) -> Vortex Ok(()) } -#[test] -fn test_declared_output_dtype_labels_sink_output() -> VortexResult<()> { - // `I64Sink` declines skip-invalid execution, so this batch stays all-valid. The masked path is - // covered by the owned-output cases above. +#[rstest] +#[case::all_valid(Validity::NonNullable)] +#[case::partially_valid(Validity::from_iter([true, false, true]))] +fn test_declared_output_dtype_labels_sink_output(#[case] validity: Validity) -> VortexResult<()> { let values = vec![1_i64, 2, 3]; - let input = PrimitiveArray::new(values.clone(), Validity::NonNullable).into_array(); + let input = PrimitiveArray::new(values.clone(), validity.clone()).into_array(); let args = VecExecutionArgs::new(vec![input], 3); let mut ctx = array_session().create_execution_ctx(); let actual = execute_rows(&DeclaredSinkOutput, &EmptyOptions, &args, &mut ctx)?; - let expected = expected_timestamps(values, Validity::NonNullable)?; + let expected = expected_timestamps(values, validity)?; assert_arrays_eq!(&actual, &expected, &mut ctx); Ok(()) diff --git a/vortex-array/src/scalar_fn/unstable/row/types/sink/mod.rs b/vortex-array/src/scalar_fn/unstable/row/types/sink/mod.rs index 12cc1db7e5d..df13ca18e88 100644 --- a/vortex-array/src/scalar_fn/unstable/row/types/sink/mod.rs +++ b/vortex-array/src/scalar_fn/unstable/row/types/sink/mod.rs @@ -100,7 +100,8 @@ pub unsafe trait OutputSink: 'static + Sized { /// `Some` enables this strategy. The initializer **must** make every row safe to finish. /// Callbacks overwrite valid rows, and batch execution masks skipped rows. /// - /// `None` makes skip-invalid execution unavailable for this sink. + /// `None` makes direct skip-invalid execution unavailable. Batch execution can instead filter + /// its inputs and run the ordinary dense sink over only valid rows. fn skipped_rows_initializer() -> Option fn(&mut Self::Rows<'a>)> { None } diff --git a/vortex-array/src/scalar_fn/unstable/row/visitor/plan.rs b/vortex-array/src/scalar_fn/unstable/row/visitor/plan.rs index 0ebe1a9ad6d..d7c72ea4561 100644 --- a/vortex-array/src/scalar_fn/unstable/row/visitor/plan.rs +++ b/vortex-array/src/scalar_fn/unstable/row/visitor/plan.rs @@ -285,7 +285,7 @@ pub(crate) enum RowPolicy { /// error. DenseWithRetry, - /// Execute only valid rows over the original inputs. + /// Execute only valid rows, filtering inputs if direct execution is unavailable. ValidOnly, }