Skip to content

Commit cb77d9a

Browse files
authored
Implement RowFn batch execution (#9450)
## Rationale for this change - Stacked on: #9496 - Tracking issue: #9130 - API tracking: #9129 - Epic: #9128 Connects the row execution layer to the scalar-function adapter. ## What changes are included in this PR? Adds constant handling, strict validity propagation, dense execution, direct valid-row execution for supporting sinks, and output validation. A partially valid signature that cannot execute directly on valid rows panics in this layer. Encoding-aware reductions remain in #9347. Filter-and-scatter remains in #9349. Owned valid-row execution and its `Default` bound are in #9500. Nullary execution is in #9469. ## What APIs are changed? Are there any user-facing changes? Adds execution internals within the existing `unstable_row_fns` boundary. There are no stable API changes. --------- Signed-off-by: Connor Tsui <[email protected]> Signed-off-by: Connor Tsui <[email protected]>
1 parent ae156bf commit cb77d9a

20 files changed

Lines changed: 972 additions & 19 deletions

File tree

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
//! Execution arguments paired with the metadata selected during planning.
5+
//!
6+
//! [`BorrowedRowFnArgs`] can point at original or sliced arrays while retaining the dtypes,
7+
//! output dtype, and execution policy of the original batch plan.
8+
9+
use vortex_error::VortexResult;
10+
use vortex_error::vortex_err;
11+
12+
use super::RowPolicy;
13+
use crate::ArrayRef;
14+
use crate::dtype::DType;
15+
use crate::scalar_fn::ExecutionArgs;
16+
17+
/// A borrowed [`ExecutionArgs`] view with the metadata selected for its row function.
18+
///
19+
/// `arrays` can be sliced, while `dtypes` and `output_dtype` always describe the original planned
20+
/// batch. Keeping them together prevents an execution path from pairing an input view with
21+
/// unrelated planning metadata.
22+
#[derive(Clone, Copy)]
23+
pub(crate) struct BorrowedRowFnArgs<'a> {
24+
/// The input arrays for this row-function invocation.
25+
arrays: &'a [ArrayRef],
26+
27+
/// The number of rows in this row-function invocation.
28+
row_count: usize,
29+
30+
/// The original input dtypes used to select the row implementation.
31+
dtypes: &'a [DType],
32+
33+
/// The non-nullable dtype built by the selected output capability.
34+
output_dtype: &'a DType,
35+
36+
/// The nullable execution policy selected during planning.
37+
policy: RowPolicy,
38+
}
39+
40+
impl<'a> BorrowedRowFnArgs<'a> {
41+
/// Pair one input view with the planning metadata selected for its batch.
42+
pub(crate) fn new(
43+
arrays: &'a [ArrayRef],
44+
row_count: usize,
45+
dtypes: &'a [DType],
46+
output_dtype: &'a DType,
47+
policy: RowPolicy,
48+
) -> Self {
49+
Self {
50+
arrays,
51+
row_count,
52+
dtypes,
53+
output_dtype,
54+
policy,
55+
}
56+
}
57+
58+
/// Return the original input dtypes used to select the row implementation.
59+
pub(crate) fn dtypes(&self) -> &'a [DType] {
60+
self.dtypes
61+
}
62+
63+
/// Return the non-nullable dtype built by the selected output capability.
64+
pub(crate) fn output_dtype(&self) -> &'a DType {
65+
self.output_dtype
66+
}
67+
68+
/// Return the nullable execution policy selected during planning.
69+
pub(crate) fn policy(&self) -> RowPolicy {
70+
self.policy
71+
}
72+
}
73+
74+
impl ExecutionArgs for BorrowedRowFnArgs<'_> {
75+
fn get(&self, index: usize) -> VortexResult<ArrayRef> {
76+
self.arrays.get(index).cloned().ok_or_else(|| {
77+
vortex_err!(
78+
"row-function input index must be less than {}, got {index}",
79+
self.arrays.len(),
80+
)
81+
})
82+
}
83+
84+
fn num_inputs(&self) -> usize {
85+
self.arrays.len()
86+
}
87+
88+
fn row_count(&self) -> usize {
89+
self.row_count
90+
}
91+
}
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
use smallvec::SmallVec;
5+
use vortex_error::VortexResult;
6+
7+
use super::super::RowFnExecutionArgs;
8+
use super::super::args::BorrowedRowFnArgs;
9+
use crate::ArrayRef;
10+
use crate::ExecutionCtx;
11+
use crate::IntoArray;
12+
use crate::arrays::ConstantArray;
13+
14+
impl RowFnExecutionArgs {
15+
/// Execute all-constant inputs by evaluating one row and broadcasting the validated result.
16+
pub(super) fn execute_all_constant(
17+
&self,
18+
kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult<ArrayRef>,
19+
ctx: &mut ExecutionCtx,
20+
) -> VortexResult<ArrayRef> {
21+
let one_row: SmallVec<[ArrayRef; 4]> = self
22+
.inputs
23+
.iter()
24+
.map(|input| input.slice(0..1))
25+
.collect::<VortexResult<_>>()?;
26+
27+
let result =
28+
self.validate_kernel_output(kernel(self.execution_args(&one_row, 1), ctx)?, 1, ctx)?;
29+
let result = self.finalize_output(result, 1)?;
30+
let scalar = result.execute_scalar(0, ctx)?;
31+
32+
Ok(ConstantArray::new(scalar, self.row_count).into_array())
33+
}
34+
}
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
use vortex_error::VortexResult;
5+
6+
use super::super::RowFnExecutionArgs;
7+
use super::super::args::BorrowedRowFnArgs;
8+
use crate::ArrayRef;
9+
use crate::ExecutionCtx;
10+
use crate::builtins::ArrayBuiltins;
11+
use crate::validity::Validity;
12+
13+
impl RowFnExecutionArgs {
14+
/// Run every stored payload, then attach the input validity without materializing its mask.
15+
pub(super) fn execute_dense(
16+
&self,
17+
kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult<ArrayRef>,
18+
ctx: &mut ExecutionCtx,
19+
) -> VortexResult<ArrayRef> {
20+
let values = kernel(self.execution_args(&self.inputs, self.row_count), ctx)?;
21+
let values = self.validate_kernel_output(values, self.row_count, ctx)?;
22+
23+
match self.validity.clone() {
24+
Validity::NonNullable | Validity::AllValid => {
25+
self.finalize_output(values, self.row_count)
26+
}
27+
Validity::Array(valid) => self.finalize_output(values.mask(valid)?, self.row_count),
28+
// Handled by the guard in `RowFnExecutionArgs::execute`, before the kernel ran.
29+
Validity::AllInvalid => Ok(self.all_null()),
30+
}
31+
}
32+
}
Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
//! Selects a batch execution strategy.
5+
//!
6+
//! [`RowFnExecutionArgs::execute`] handles universal fast paths, then delegates to dense or
7+
//! valid-only execution.
8+
9+
use vortex_error::VortexResult;
10+
use vortex_mask::Mask;
11+
12+
use super::RowFnExecutionArgs;
13+
use super::RowPolicy;
14+
use super::args::BorrowedRowFnArgs;
15+
use crate::ArrayRef;
16+
use crate::ExecutionCtx;
17+
use crate::arrays::Constant;
18+
use crate::scalar_fn::unstable::row::types::batch_const;
19+
use crate::validity::Validity;
20+
21+
mod constant;
22+
mod dense;
23+
mod valid_only;
24+
25+
mod output;
26+
#[cfg(test)]
27+
pub(crate) use output::finalize_kernel_output;
28+
29+
impl RowFnExecutionArgs {
30+
/// Apply constant folding and null handling around `kernel`.
31+
///
32+
/// For a partially valid batch, `try_valid_rows` executes only valid rows over the original
33+
/// inputs. Every result is checked against the planned shape and dtype.
34+
pub(crate) fn execute(
35+
&self,
36+
kernel: impl Fn(BorrowedRowFnArgs<'_>, &mut ExecutionCtx) -> VortexResult<ArrayRef>,
37+
try_valid_rows: impl FnOnce(
38+
BorrowedRowFnArgs<'_>,
39+
&Mask,
40+
&mut ExecutionCtx,
41+
) -> VortexResult<Option<ArrayRef>>,
42+
ctx: &mut ExecutionCtx,
43+
) -> VortexResult<ArrayRef> {
44+
// Strictness: an all-null batch has no observable row work. Keep the literal-constant
45+
// check explicit alongside the conjoined validity invariant.
46+
if matches!(self.validity, Validity::AllInvalid)
47+
|| self.inputs.iter().any(|input| {
48+
input
49+
.as_opt::<Constant>()
50+
.is_some_and(|constant| constant.scalar().is_null())
51+
})
52+
{
53+
return Ok(self.all_null());
54+
}
55+
56+
// All inputs are constant, and their conjoined validity proves that every row is non-null.
57+
// The constant check sees through extension and masked wrappers, just like argument
58+
// decoding.
59+
if self.row_count > 0
60+
&& self.validity.definitely_no_nulls()
61+
&& self.inputs.iter().all(|input| batch_const(input).is_some())
62+
{
63+
return self.execute_all_constant(kernel, ctx);
64+
}
65+
66+
// A known all-valid batch does not need to materialize validity, even when its row policy
67+
// only permits valid rows.
68+
if self.validity.definitely_no_nulls() {
69+
return self.execute_dense(kernel, ctx);
70+
}
71+
72+
match self.policy {
73+
RowPolicy::Dense => self.execute_dense(kernel, ctx),
74+
RowPolicy::ValidOnly => self.execute_valid_only(kernel, try_valid_rows, ctx),
75+
}
76+
}
77+
}
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
use vortex_error::VortexResult;
5+
use vortex_error::vortex_ensure;
6+
use vortex_error::vortex_ensure_eq;
7+
8+
use super::super::RowFnExecutionArgs;
9+
use crate::ArrayRef;
10+
use crate::ExecutionCtx;
11+
use crate::IntoArray;
12+
use crate::arrays::ConstantArray;
13+
use crate::builtins::ArrayBuiltins;
14+
use crate::dtype::DType;
15+
use crate::scalar::Scalar;
16+
use crate::scalar_fn::ScalarFnId;
17+
18+
impl RowFnExecutionArgs {
19+
pub(super) fn all_null(&self) -> ArrayRef {
20+
ConstantArray::new(Scalar::null(self.result_dtype.clone()), self.row_count).into_array()
21+
}
22+
23+
/// Validate the finished output and apply the row function's logical outer nullability.
24+
pub(super) fn finalize_output(
25+
&self,
26+
values: ArrayRef,
27+
expected_len: usize,
28+
) -> VortexResult<ArrayRef> {
29+
validate_output(self.id, &self.result_dtype, expected_len, &values)?;
30+
31+
cast_output_nullability(&self.result_dtype, values)
32+
}
33+
34+
/// Validate the output from a row function before batch validity is attached.
35+
pub(super) fn validate_kernel_output(
36+
&self,
37+
values: ArrayRef,
38+
expected_len: usize,
39+
ctx: &mut ExecutionCtx,
40+
) -> VortexResult<ArrayRef> {
41+
finalize_kernel_output(self.id, &self.output_dtype, expected_len, values, ctx)
42+
}
43+
}
44+
45+
/// Validate the output produced directly by a row function.
46+
///
47+
/// `values` **must** contain `expected_len` rows. Its dtype must match `result_dtype` except for
48+
/// outer nullability, and every produced row **must** be valid. Batch execution owns strict null
49+
/// propagation and attaches input-derived validity only after this boundary.
50+
pub(crate) fn finalize_kernel_output(
51+
id: ScalarFnId,
52+
result_dtype: &DType,
53+
expected_len: usize,
54+
values: ArrayRef,
55+
ctx: &mut ExecutionCtx,
56+
) -> VortexResult<ArrayRef> {
57+
validate_output(id, result_dtype, expected_len, &values)?;
58+
vortex_ensure!(
59+
values.all_valid(ctx)?,
60+
"the {id} row kernel must produce only valid rows, got at least one null row",
61+
);
62+
63+
cast_output_nullability(result_dtype, values)
64+
}
65+
66+
/// Validate an output's shape and logical dtype without executing an outer-nullability cast.
67+
fn validate_output(
68+
id: ScalarFnId,
69+
result_dtype: &DType,
70+
expected_len: usize,
71+
values: &ArrayRef,
72+
) -> VortexResult<()> {
73+
vortex_ensure_eq!(
74+
values.len(),
75+
expected_len,
76+
"the {id} kernel output must contain {expected_len} rows, got {}",
77+
values.len(),
78+
);
79+
let values_with_result_nullability =
80+
values.dtype().with_nullability(result_dtype.nullability());
81+
vortex_ensure!(
82+
values_with_result_nullability == *result_dtype,
83+
"the {id} output dtype must match {result_dtype} except for outer nullability, got {}",
84+
values.dtype(),
85+
);
86+
87+
Ok(())
88+
}
89+
90+
/// Cast only the outer output nullability after validation accepts every other dtype component.
91+
///
92+
/// This changes no logical dtype component other than outer nullability. An encoding that cannot
93+
/// rewrite its nullability directly can still retain a lazy cast until execution.
94+
fn cast_output_nullability(result_dtype: &DType, values: ArrayRef) -> VortexResult<ArrayRef> {
95+
if values.dtype() == result_dtype {
96+
Ok(values)
97+
} else {
98+
values.cast(result_dtype.clone())
99+
}
100+
}

0 commit comments

Comments
 (0)