|
| 1 | +// SPDX-License-Identifier: Apache-2.0 |
| 2 | +// SPDX-FileCopyrightText: Copyright the Vortex contributors |
| 3 | + |
| 4 | +//! Fallback execution for row kernels that cannot operate on the original partially valid inputs. |
| 5 | +//! |
| 6 | +//! Direct skip-invalid execution retains the original row domain: it decodes every input column, |
| 7 | +//! initializes a full-length output, and visits only valid rows. Some input representations cannot |
| 8 | +//! decode unspecified payloads behind nulls, and some output sinks cannot initialize rows that the |
| 9 | +//! kernel skips. In either case, there is no safe row loop to enter over the original columns. |
| 10 | +//! |
| 11 | +//! This fallback filters every input to the valid row domain before decoding it. The ordinary |
| 12 | +//! kernel then produces a compact, all-valid output. A take with nullable indices scatters those |
| 13 | +//! values back to the original row domain and restores its nulls. |
| 14 | +//! |
| 15 | +//! Filtering and scattering add columnar work around the row loop. Filtering nested or compressed |
| 16 | +//! inputs can also materialize their selected representation. Batch execution therefore tries |
| 17 | +//! direct skip-invalid execution first and uses this path only when a required capability is |
| 18 | +//! unavailable. |
| 19 | +//! |
| 20 | +//! A prepared, type-specific view can provide selected-row decoding without filtering. That is an |
| 21 | +//! optional direct-execution capability rather than a replacement for this fallback: it requires a |
| 22 | +//! representation with safe selected access, and it does not initialize an output sink that cannot |
| 23 | +//! represent skipped rows. Calling the general scalar-extraction API once per valid row is also not |
| 24 | +//! equivalent because it repeats array execution and scalar construction inside the row loop. |
| 25 | +
|
| 26 | +use smallvec::SmallVec; |
| 27 | +use vortex_error::VortexResult; |
| 28 | +use vortex_mask::Mask; |
| 29 | +use vortex_mask::MaskValuesRef; |
| 30 | + |
| 31 | +use super::super::RowFnExecutionArgs; |
| 32 | +use super::super::args::BorrowedRowFnArgs; |
| 33 | +use crate::ArrayRef; |
| 34 | +use crate::ExecutionCtx; |
| 35 | +use crate::IntoArray; |
| 36 | +use crate::arrays::PrimitiveArray; |
| 37 | +use crate::dtype::Nullability; |
| 38 | +use crate::validity::Validity; |
| 39 | + |
| 40 | +impl RowFnExecutionArgs { |
| 41 | + /// Filter the original batch to valid rows, run the kernel, then restore its row count. |
| 42 | + pub(super) fn filter_and_scatter( |
| 43 | + &self, |
| 44 | + kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult<ArrayRef>, |
| 45 | + original_validity: &MaskValuesRef, |
| 46 | + ctx: &mut ExecutionCtx, |
| 47 | + ) -> VortexResult<ArrayRef> { |
| 48 | + let original_len = original_validity.len(); |
| 49 | + let filtered_len = original_validity.true_count(); |
| 50 | + let filter_mask = Mask::Values(MaskValuesRef::clone(original_validity)); |
| 51 | + |
| 52 | + let filtered_inputs: SmallVec<[ArrayRef; 4]> = self |
| 53 | + .inputs |
| 54 | + .iter() |
| 55 | + .map(|input| input.filter(filter_mask.clone())) |
| 56 | + .collect::<VortexResult<_>>()?; |
| 57 | + |
| 58 | + let filtered_args = self.execution_args(&filtered_inputs, filtered_len); |
| 59 | + let filtered = kernel(filtered_args, ctx)?; |
| 60 | + let filtered = self.validate_kernel_output(filtered, filtered_len, ctx)?; |
| 61 | + |
| 62 | + let output = Self::scatter_to_original_rows(filtered, original_validity)?; |
| 63 | + |
| 64 | + self.finalize_output(output, original_len) |
| 65 | + } |
| 66 | + |
| 67 | + /// Scatter `filtered` back to the rows selected by `original_validity`. |
| 68 | + fn scatter_to_original_rows( |
| 69 | + filtered: ArrayRef, |
| 70 | + original_validity: &MaskValuesRef, |
| 71 | + ) -> VortexResult<ArrayRef> { |
| 72 | + let original_len = original_validity.len(); |
| 73 | + let mut take_indices = vec![0u64; original_len]; |
| 74 | + |
| 75 | + let valid_rows = original_validity |
| 76 | + .slices() |
| 77 | + .iter() |
| 78 | + .flat_map(|&(start, end)| start..end); |
| 79 | + for (filtered_index, original_index) in valid_rows.enumerate() { |
| 80 | + take_indices[original_index] = u64::try_from(filtered_index)?; |
| 81 | + } |
| 82 | + |
| 83 | + // Null indices restore invalid rows without selecting a value from the compact output. |
| 84 | + let take_indices = PrimitiveArray::new( |
| 85 | + take_indices, |
| 86 | + Validity::from_mask( |
| 87 | + Mask::Values(MaskValuesRef::clone(original_validity)), |
| 88 | + Nullability::Nullable, |
| 89 | + ), |
| 90 | + ) |
| 91 | + .into_array(); |
| 92 | + |
| 93 | + filtered.take(take_indices) |
| 94 | + } |
| 95 | +} |
0 commit comments