Skip to main content

vortex_array/scalar_fn/fns/binary/compare/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Native comparison kernels.
5//!
6//! [`execute_compare`] dispatches on the logical [`DType`] of its operands and evaluates every
7//! comparison directly over Vortex canonical arrays: bit buffers for booleans, lane kernels from
8//! `vortex-compute` for primitives and decimals, binary views for strings/bytes, and a row-wise
9//! comparator for nested types. There is no Arrow fallback.
10//!
11//! Floating point values compare with Vortex's total ordering (`NaN` is the largest value,
12//! `-0.0 < +0.0`, and equality is bitwise), matching [`Scalar`] comparison semantics.
13//!
14//! Binary scalar functions can execute through encoding-specific kernels before reaching the native
15//! dispatcher. [`CompareExecuteAdaptor`] connects these execution paths to [`CompareKernel`], which
16//! lets an encoding compare values without first converting them to canonical arrays.
17
18use std::cmp::Ordering;
19
20use vortex_error::VortexResult;
21use vortex_error::vortex_bail;
22use vortex_error::vortex_ensure;
23use vortex_error::vortex_err;
24
25use crate::ArrayRef;
26use crate::Canonical;
27use crate::ExecutionCtx;
28use crate::IntoArray;
29use crate::array::ArrayView;
30use crate::array::VTable;
31use crate::arrays::Constant;
32use crate::arrays::ConstantArray;
33use crate::arrays::ExtensionArray;
34use crate::arrays::ScalarFn;
35use crate::arrays::extension::ExtensionArrayExt;
36use crate::arrays::scalar_fn::ExactScalarFn;
37use crate::arrays::scalar_fn::ScalarFnArrayExt;
38use crate::arrays::scalar_fn::ScalarFnArrayView;
39use crate::dtype::DType;
40use crate::dtype::Nullability;
41use crate::kernel::ExecuteParentKernel;
42use crate::scalar::Scalar;
43use crate::scalar_fn::fns::binary::Binary;
44use crate::scalar_fn::fns::operators::CompareOperator;
45use crate::validity::Validity;
46
47mod boolean;
48mod bytes;
49mod decimal;
50
51mod nested;
52pub(crate) use nested::build_comparator as build_row_comparator;
53
54mod primitive;
55
56/// Trait for encoding-specific comparison kernels that operate in encoded space.
57///
58/// Implementations can compare an encoded array against another array (typically a constant)
59/// without first decompressing. The adaptor normalizes operand order so `array` is always
60/// the left-hand side, swapping the operator when necessary.
61pub trait CompareKernel: VTable {
62    /// Compares `lhs` with `rhs`, or returns `None` to use the default comparison path.
63    ///
64    /// Operand dtypes must match, ignoring nullability. [`CompareExecuteAdaptor`] checks this before
65    /// dispatch; direct callers must satisfy the same requirement.
66    fn compare(
67        lhs: ArrayView<'_, Self>,
68        rhs: &ArrayRef,
69        operator: CompareOperator,
70        ctx: &mut ExecutionCtx,
71    ) -> VortexResult<Option<ArrayRef>>;
72}
73
74/// Adaptor that bridges [`CompareKernel`] implementations to [`ExecuteParentKernel`].
75///
76/// When a `ScalarFnArray(Binary, cmp_op)` wraps a child that implements `CompareKernel`,
77/// this adaptor extracts the comparison operator and other operand, normalizes operand order
78/// (swapping the operator if the encoded array is on the RHS), and delegates to the kernel.
79#[derive(Default, Debug)]
80pub struct CompareExecuteAdaptor<V>(
81    /// The encoding whose comparison kernel handles the normalized operands.
82    pub V,
83);
84
85impl<V> ExecuteParentKernel<V> for CompareExecuteAdaptor<V>
86where
87    V: CompareKernel,
88{
89    type Parent = ExactScalarFn<Binary>;
90
91    fn execute_parent(
92        &self,
93        array: ArrayView<'_, V>,
94        parent: ScalarFnArrayView<'_, Binary>,
95        child_idx: usize,
96        ctx: &mut ExecutionCtx,
97    ) -> VortexResult<Option<ArrayRef>> {
98        // Non-comparison operators are normal kernel misses, so decline them without constructing
99        // an error (which would capture a backtrace, or panic under `VORTEX_PANIC_ON_ERR`).
100        let Some(cmp_op) = parent.options.to_compare_operator() else {
101            return Ok(None);
102        };
103
104        // Get the ScalarFnArray to access children
105        let Some(scalar_fn_array) = parent.as_opt::<ScalarFn>() else {
106            return Ok(None);
107        };
108        // Normalize so `array` is always LHS, swapping the operator if needed
109        // TODO(joe): should be go this here or in the Rule/Kernel
110        let (cmp_op, other) = match child_idx {
111            0 => (cmp_op, scalar_fn_array.get_child(1)),
112            1 => (cmp_op.swap(), scalar_fn_array.get_child(0)),
113            _ => return Ok(None),
114        };
115
116        validate_comparison_dtypes(array.dtype(), other.dtype())?;
117
118        let len = array.len();
119        let nullable = array.dtype().is_nullable() || other.dtype().is_nullable();
120
121        // Empty array → empty bool result
122        if len == 0 {
123            return Ok(Some(
124                Canonical::empty(&DType::Bool(nullable.into())).into_array(),
125            ));
126        }
127
128        // Null constant on either side → all-null bool result
129        if other.as_constant().is_some_and(|s| s.is_null()) {
130            return Ok(Some(
131                ConstantArray::new(Scalar::null(DType::Bool(nullable.into())), len).into_array(),
132            ));
133        }
134
135        V::compare(array, other, cmp_op, ctx)
136    }
137}
138
139/// Execute a compare operation between two arrays.
140///
141/// This is the entry point for compare operations from the binary expression.
142/// Handles empty, constant-null, and constant-constant directly, otherwise dispatches to a
143/// native per-dtype kernel.
144pub(crate) fn execute_compare(
145    lhs: &ArrayRef,
146    rhs: &ArrayRef,
147    op: CompareOperator,
148    ctx: &mut ExecutionCtx,
149) -> VortexResult<ArrayRef> {
150    validate_comparison_dtypes(lhs.dtype(), rhs.dtype())?;
151
152    let nullable = lhs.dtype().is_nullable() || rhs.dtype().is_nullable();
153
154    if lhs.len() != rhs.len() {
155        vortex_bail!(
156            "compare operator requires equal lengths, got {} and {}",
157            lhs.len(),
158            rhs.len()
159        );
160    }
161
162    if lhs.is_empty() {
163        return Ok(Canonical::empty(&DType::Bool(nullable.into())).into_array());
164    }
165
166    let left_constant_null = lhs.as_constant().map(|l| l.is_null()).unwrap_or(false);
167    let right_constant_null = rhs.as_constant().map(|r| r.is_null()).unwrap_or(false);
168    if left_constant_null || right_constant_null {
169        return Ok(
170            ConstantArray::new(Scalar::null(DType::Bool(nullable.into())), lhs.len()).into_array(),
171        );
172    }
173
174    // Constant-constant fast path
175    if let (Some(lhs_const), Some(rhs_const)) = (lhs.as_opt::<Constant>(), rhs.as_opt::<Constant>())
176    {
177        let result = scalar_cmp(lhs_const.scalar(), rhs_const.scalar(), op)?;
178        return Ok(ConstantArray::new(result, lhs.len()).into_array());
179    }
180
181    compare_arrays(lhs, rhs, op, ctx)
182}
183
184/// Dispatches operands with matching logical dtypes to their native comparison kernel.
185///
186/// Extension operands are unwrapped before dispatch to the storage kernel.
187fn compare_arrays(
188    lhs: &ArrayRef,
189    rhs: &ArrayRef,
190    op: CompareOperator,
191    ctx: &mut ExecutionCtx,
192) -> VortexResult<ArrayRef> {
193    let nullability = Nullability::from(lhs.dtype().is_nullable() || rhs.dtype().is_nullable());
194
195    if lhs.dtype().is_extension() {
196        let lhs = extension_storage(lhs, ctx)?;
197        let rhs = extension_storage(rhs, ctx)?;
198
199        return compare_arrays(&lhs, &rhs, op, ctx);
200    }
201
202    validate_comparison_dtypes(lhs.dtype(), rhs.dtype())?;
203
204    match lhs.dtype() {
205        // Every value of the null dtype is null, so every comparison result is null.
206        DType::Null => Ok(ConstantArray::new(
207            Scalar::null(DType::Bool(Nullability::Nullable)),
208            lhs.len(),
209        )
210        .into_array()),
211        DType::Bool(_) => boolean::compare_bool(lhs, rhs, op, nullability, ctx),
212        DType::Primitive(..) => primitive::compare_primitive(lhs, rhs, op, nullability, ctx),
213        DType::Decimal(..) => decimal::compare_decimal(lhs, rhs, op, nullability, ctx),
214        DType::Utf8(_) | DType::Binary(_) => bytes::compare_bytes(lhs, rhs, op, nullability, ctx),
215        DType::Struct(..) | DType::List(..) | DType::FixedSizeList(..) | DType::Map(..) => {
216            nested::compare_nested(lhs, rhs, op, nullability, ctx)
217        }
218        DType::Union(..) | DType::Variant(_) | DType::Extension(_) => {
219            vortex_bail!("compare is not supported for dtype {}", lhs.dtype())
220        }
221    }
222}
223
224/// Returns the storage of an extension array or constant.
225///
226/// Extension constants retain their constant encoding. Other extension arrays execute to their
227/// canonical representation so that the caller can access their storage.
228fn extension_storage(array: &ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<ArrayRef> {
229    if let Some(constant) = array.as_opt::<Constant>() {
230        return Ok(ConstantArray::new(
231            constant.scalar().as_extension().to_storage_scalar(),
232            constant.len(),
233        )
234        .into_array());
235    }
236
237    let ext = array.clone().execute::<ExtensionArray>(ctx)?;
238
239    Ok(ext.storage_array().clone())
240}
241
242/// Compares scalars with matching dtypes, ignoring nullability.
243///
244/// Returns null if either operand is null, and an error if the operand dtypes differ.
245pub fn scalar_cmp(lhs: &Scalar, rhs: &Scalar, operator: CompareOperator) -> VortexResult<Scalar> {
246    validate_comparison_dtypes(lhs.dtype(), rhs.dtype())?;
247
248    if lhs.is_null() | rhs.is_null() {
249        return Ok(Scalar::null(DType::Bool(Nullability::Nullable)));
250    }
251
252    let nullability = lhs.dtype().nullability() | rhs.dtype().nullability();
253
254    // Some values, such as variants, have no scalar ordering even when their dtypes match.
255    let ordering = lhs.partial_cmp(rhs).ok_or_else(|| {
256        vortex_err!(
257            "Scalar comparison requires comparable values, got {} and {}",
258            lhs.dtype(),
259            rhs.dtype()
260        )
261    })?;
262
263    let result = match operator {
264        CompareOperator::Eq => ordering.is_eq(),
265        CompareOperator::NotEq => ordering.is_ne(),
266        CompareOperator::Gt => ordering.is_gt(),
267        CompareOperator::Gte => ordering.is_ge(),
268        CompareOperator::Lt => ordering.is_lt(),
269        CompareOperator::Lte => ordering.is_le(),
270    };
271
272    Ok(Scalar::bool(result, nullability))
273}
274
275/// Checks the shared dtype requirement before comparison fast paths or encoding kernels run.
276pub(super) fn validate_comparison_dtypes(lhs: &DType, rhs: &DType) -> VortexResult<()> {
277    vortex_ensure!(
278        lhs.eq_ignore_nullability(rhs),
279        "Comparison requires equal dtypes ignoring nullability, got {lhs} and {rhs}"
280    );
281
282    Ok(())
283}
284
285/// Returns the predicate `Ordering -> bool` for a comparison operator.
286#[inline]
287pub(super) fn ordering_predicate(op: CompareOperator) -> fn(Ordering) -> bool {
288    match op {
289        CompareOperator::Eq => Ordering::is_eq,
290        CompareOperator::NotEq => Ordering::is_ne,
291        CompareOperator::Gt => Ordering::is_gt,
292        CompareOperator::Gte => Ordering::is_ge,
293        CompareOperator::Lt => Ordering::is_lt,
294        CompareOperator::Lte => Ordering::is_le,
295    }
296}
297
298/// Combine operand validities into the validity of a comparison result with the given result
299/// nullability.
300pub(super) fn compare_validity(
301    lhs: Validity,
302    rhs: Validity,
303    nullability: Nullability,
304) -> VortexResult<Validity> {
305    Ok(lhs.and(rhs)?.union_nullability(nullability))
306}
307
308#[cfg(test)]
309mod tests;