Skip to main content

vortex_array/scalar_fn/fns/
case_when.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! SQL-style CASE WHEN: evaluates `(condition, value)` pairs in order and returns
5//! the value from the first matching condition (first-match-wins). NULL conditions
6//! are treated as false. If no ELSE clause is provided, unmatched rows produce NULL;
7//! otherwise they get the ELSE value.
8//!
9//! Unlike SQL which coerces all branches to a common supertype, all THEN/ELSE
10//! branches must share the same base dtype (ignoring nullability). The result
11//! nullability is the union of all branches (forced nullable if no ELSE).
12//!
13//! The serialized expression format is not part of a Vortex edition and is not
14//! guaranteed to remain compatible across Vortex versions.
15
16use std::fmt;
17use std::fmt::Formatter;
18use std::hash::Hash;
19use std::sync::Arc;
20
21use prost::Message;
22use vortex_buffer::BufferMut;
23use vortex_error::VortexResult;
24use vortex_error::vortex_bail;
25use vortex_error::vortex_ensure;
26use vortex_mask::AllOr;
27use vortex_mask::Mask;
28use vortex_session::VortexSession;
29use vortex_session::registry::CachedId;
30
31use crate::ArrayRef;
32use crate::ExecutionCtx;
33use crate::IntoArray;
34use crate::arrays::BoolArray;
35use crate::arrays::ConstantArray;
36use crate::arrays::bool::BoolArrayExt;
37use crate::builders::builder_with_capacity_in;
38use crate::builtins::ArrayBuiltins;
39use crate::dtype::DType;
40use crate::expr::BoundExpression;
41use crate::expr::display::ExprDisplay;
42use crate::proto::expr as pb;
43use crate::scalar::Scalar;
44use crate::scalar_fn::Arity;
45use crate::scalar_fn::ChildName;
46use crate::scalar_fn::EmptyOptions;
47use crate::scalar_fn::ExecutionArgs;
48use crate::scalar_fn::ScalarFnId;
49use crate::scalar_fn::ScalarFnVTable;
50use crate::scalar_fn::ScalarFnVTableExt;
51use crate::scalar_fn::fns::fill_null::FillNull;
52use crate::scalar_fn::fns::is_not_null::IsNotNull;
53use crate::scalar_fn::fns::is_null::IsNull;
54use crate::scalar_fn::fns::literal::Literal;
55use crate::scalar_fn::fns::zip::zip_nullability_union;
56
57/// Options for the n-ary CaseWhen expression.
58#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
59pub struct CaseWhenOptions {
60    /// Number of WHEN/THEN pairs.
61    pub num_when_then_pairs: u32,
62    /// Whether an ELSE clause is present.
63    /// If false, unmatched rows return NULL.
64    pub has_else: bool,
65}
66
67impl CaseWhenOptions {
68    /// Total number of child expressions: 2 per WHEN/THEN pair, plus 1 if ELSE is present.
69    pub fn num_children(&self) -> usize {
70        self.num_when_then_pairs as usize * 2 + usize::from(self.has_else)
71    }
72}
73
74impl fmt::Display for CaseWhenOptions {
75    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
76        write!(
77            f,
78            "case_when(pairs={}, else={})",
79            self.num_when_then_pairs, self.has_else
80        )
81    }
82}
83
84/// An n-ary CASE WHEN expression.
85///
86/// Children are in order: `[when_0, then_0, when_1, then_1, ..., else?]`.
87#[derive(Clone)]
88pub struct CaseWhen;
89
90impl ScalarFnVTable for CaseWhen {
91    type Options = CaseWhenOptions;
92
93    fn id(&self) -> ScalarFnId {
94        static ID: CachedId = CachedId::new("vortex.case_when");
95        *ID
96    }
97
98    fn serialize(&self, options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
99        vortex_ensure!(
100            options.num_when_then_pairs > 0,
101            "CaseWhen must have at least one WHEN/THEN pair"
102        );
103        let Some(num_children) = options
104            .num_when_then_pairs
105            .checked_mul(2)
106            .and_then(|count| count.checked_add(u32::from(options.has_else)))
107        else {
108            vortex_bail!("CaseWhen has too many children to serialize");
109        };
110        Ok(Some(pb::CaseWhenOpts { num_children }.encode_to_vec()))
111    }
112
113    fn deserialize(
114        &self,
115        metadata: &[u8],
116        _session: &VortexSession,
117    ) -> VortexResult<Self::Options> {
118        let opts = pb::CaseWhenOpts::decode(metadata)?;
119        if opts.num_children < 2 {
120            vortex_bail!(
121                "CaseWhen expects at least 2 children, got {}",
122                opts.num_children
123            );
124        }
125        Ok(CaseWhenOptions {
126            num_when_then_pairs: opts.num_children / 2,
127            has_else: opts.num_children % 2 == 1,
128        })
129    }
130
131    fn arity(&self, options: &Self::Options) -> Arity {
132        Arity::Exact(options.num_children())
133    }
134
135    fn child_name(&self, options: &Self::Options, child_idx: usize) -> ChildName {
136        let num_pair_children = options.num_when_then_pairs as usize * 2;
137        if child_idx < num_pair_children {
138            let pair_idx = child_idx / 2;
139            if child_idx.is_multiple_of(2) {
140                ChildName::from(Arc::from(format!("when_{pair_idx}")))
141            } else {
142                ChildName::from(Arc::from(format!("then_{pair_idx}")))
143            }
144        } else if options.has_else && child_idx == num_pair_children {
145            ChildName::from("else")
146        } else {
147            unreachable!("Invalid child index {} for CaseWhen", child_idx)
148        }
149    }
150
151    fn fmt_sql(
152        &self,
153        options: &Self::Options,
154        expr: &dyn ExprDisplay,
155        f: &mut Formatter<'_>,
156    ) -> fmt::Result {
157        write!(f, "CASE")?;
158        for i in 0..options.num_when_then_pairs as usize {
159            write!(
160                f,
161                " WHEN {} THEN {}",
162                expr.display_child(i * 2),
163                expr.display_child(i * 2 + 1)
164            )?;
165        }
166        if options.has_else {
167            let else_idx = options.num_when_then_pairs as usize * 2;
168            write!(f, " ELSE {}", expr.display_child(else_idx))?;
169        }
170        write!(f, " END")
171    }
172
173    fn return_dtype(&self, options: &Self::Options, arg_dtypes: &[DType]) -> VortexResult<DType> {
174        if options.num_when_then_pairs == 0 {
175            vortex_bail!("CaseWhen must have at least one WHEN/THEN pair");
176        }
177
178        let expected_len = options.num_children();
179        if arg_dtypes.len() != expected_len {
180            vortex_bail!(
181                "CaseWhen expects {expected_len} argument dtypes, got {}",
182                arg_dtypes.len()
183            );
184        }
185
186        // Unlike SQL which coerces all branches to a common supertype, we require
187        // all THEN/ELSE branches to have the same base dtype (ignoring nullability).
188        // The result nullability is the union of all branches, at every nesting level.
189        let first_then = &arg_dtypes[1];
190        let mut result_dtype = first_then.clone();
191
192        for i in 1..options.num_when_then_pairs as usize {
193            let then_i = &arg_dtypes[i * 2 + 1];
194            let Some(union) = zip_nullability_union(&result_dtype, then_i) else {
195                vortex_bail!(
196                    "CaseWhen THEN dtypes must match (ignoring nullability), got {} and {}",
197                    first_then,
198                    then_i
199                );
200            };
201            result_dtype = union;
202        }
203
204        if options.has_else {
205            let else_dtype = &arg_dtypes[options.num_when_then_pairs as usize * 2];
206            let Some(union) = zip_nullability_union(&result_dtype, else_dtype) else {
207                vortex_bail!(
208                    "CaseWhen THEN and ELSE dtypes must match (ignoring nullability), got {} and {}",
209                    first_then,
210                    else_dtype
211                );
212            };
213            result_dtype = union;
214        } else {
215            // No ELSE means unmatched rows are NULL
216            result_dtype = result_dtype.as_nullable();
217        }
218
219        Ok(result_dtype)
220    }
221
222    fn execute(
223        &self,
224        options: &Self::Options,
225        args: &dyn ExecutionArgs,
226        ctx: &mut ExecutionCtx,
227    ) -> VortexResult<ArrayRef> {
228        let row_count = args.row_count();
229        let num_pairs = options.num_when_then_pairs as usize;
230        let dtypes = (0..args.num_inputs())
231            .map(|index| Ok(args.get(index)?.dtype().clone()))
232            .collect::<VortexResult<Vec<_>>>()?;
233        let output_dtype = self.return_dtype(options, &dtypes)?;
234
235        let mut remaining = Mask::new_true(row_count);
236        let mut branches: Vec<(Mask, ArrayRef)> = Vec::with_capacity(num_pairs);
237
238        for i in 0..num_pairs {
239            if remaining.all_false() {
240                break;
241            }
242
243            let condition = args.get(i * 2)?.filter(remaining.clone())?;
244            let cond_bool = condition.execute::<BoolArray>(ctx)?;
245            let cond_mask = cond_bool.to_mask_fill_null_false(ctx);
246            let effective_mask = remaining.intersect_by_rank(&cond_mask);
247
248            if effective_mask.all_false() {
249                continue;
250            }
251
252            let then_value = args.get(i * 2 + 1)?;
253            remaining = remaining.bitand_not(&effective_mask);
254            branches.push((effective_mask, then_value));
255        }
256
257        let else_value: ArrayRef = if options.has_else {
258            args.get(num_pairs * 2)?
259        } else {
260            let then_dtype = args.get(1)?.dtype().as_nullable();
261            ConstantArray::new(Scalar::null(then_dtype), row_count).into_array()
262        };
263
264        if branches.is_empty() {
265            return else_value.cast(output_dtype);
266        }
267
268        // `remaining` now selects the rows that no branch matched.
269        merge_case_branches(&branches, &remaining, &else_value, &output_dtype, ctx)
270    }
271
272    fn simplify(
273        &self,
274        options: &Self::Options,
275        expr: &BoundExpression,
276    ) -> VortexResult<Option<BoundExpression>> {
277        // Rewrite the COALESCE-shaped CASE WHEN into `fill_null`, which references `x`
278        // once and lowers to a single fill kernel instead of a `zip`/merge that resolves
279        // `x` twice (once for the `is_null` predicate, once for the value branch).
280        //
281        //   CASE WHEN is_null(x)     THEN c ELSE x END  ==>  fill_null(x, c)
282        //   CASE WHEN is_not_null(x) THEN x ELSE c END  ==>  fill_null(x, c)
283        //
284        // The fill `c` must be a `Literal`: `fill_null`'s kernel reads the fill value via
285        // `as_constant()`, so a non-constant fill would produce an unexecutable expression.
286        if options.num_when_then_pairs != 1 || !options.has_else {
287            return Ok(None);
288        }
289
290        let when = expr.child(0);
291        let then = expr.child(1);
292        let els = expr.child(2);
293
294        // `is_null(x) ? c : x` — predicate operand and ELSE are the same `x`, fill is THEN.
295        let (x, fill) = if when.is::<IsNull>() && when.child(0) == els {
296            (els, then)
297        // `is_not_null(x) ? x : c` — predicate operand and THEN are the same `x`, fill is ELSE.
298        } else if when.is::<IsNotNull>() && when.child(0) == then {
299            (then, els)
300        } else {
301            return Ok(None);
302        };
303
304        let Some(scalar) = fill.as_opt::<Literal>() else {
305            return Ok(None);
306        };
307
308        if scalar.is_null() {
309            // Filling the nulls of `x` with NULL is a no-op
310            return Ok(Some(x.clone()));
311        }
312
313        if !FillNull::supports_dtype(x.dtype()) {
314            return Ok(None);
315        }
316
317        Ok(Some(FillNull.try_new_bound_expr(
318            EmptyOptions,
319            [x.clone(), fill.clone()],
320        )?))
321    }
322
323    fn is_strict(&self, _options: &Self::Options) -> bool {
324        // A null in an unselected branch does not force a null output.
325        false
326    }
327
328    fn is_infallible(&self, _options: &Self::Options) -> bool {
329        true
330    }
331}
332
333/// Assemble coarse runs directly; compact fragmented branches before restoring row positions.
334///
335/// `else_mask` selects the rows that no branch matched. Every branch and the ELSE value
336/// are cast to `output_dtype`, the dtype that `return_dtype` reports.
337fn merge_case_branches(
338    branches: &[(Mask, ArrayRef)],
339    else_mask: &Mask,
340    else_value: &ArrayRef,
341    output_dtype: &DType,
342    ctx: &mut ExecutionCtx,
343) -> VortexResult<ArrayRef> {
344    if let Some((_, value)) = branches.iter().find(|(mask, _)| mask.all_true()) {
345        return value.cast(output_dtype.clone());
346    }
347
348    if prefer_runs(branches, else_value.len()) {
349        return merge_runs(branches, else_value, output_dtype, ctx);
350    }
351
352    merge_compact(branches, else_mask, else_value, output_dtype, ctx)
353}
354
355fn prefer_runs(branches: &[(Mask, ArrayRef)], len: usize) -> bool {
356    // A span may add an ELSE run. Coarse runs amortize slicing without the
357    // extra compact-output buffer and gather; isolated branch selections do too.
358    const MIN_ROWS_PER_RUN: usize = 128;
359
360    let mut remaining_spans = branches.len().max(len / (2 * MIN_ROWS_PER_RUN));
361    for (mask, _) in branches {
362        let count = match mask {
363            Mask::AllTrue(_) => 1,
364            Mask::AllFalse(_) => 0,
365            Mask::Values(values) => values.cached_slices().map_or_else(
366                || {
367                    values
368                        .bit_buffer()
369                        .set_slices()
370                        .take(remaining_spans.saturating_add(1))
371                        .count()
372                },
373                |slices| slices.len(),
374            ),
375        };
376
377        if count > remaining_spans {
378            return false;
379        }
380        remaining_spans -= count;
381    }
382
383    true
384}
385
386fn merge_compact(
387    branches: &[(Mask, ArrayRef)],
388    else_mask: &Mask,
389    else_value: &ArrayRef,
390    output_dtype: &DType,
391    ctx: &mut ExecutionCtx,
392) -> VortexResult<ArrayRef> {
393    let len = else_value.len();
394    let mut builder = builder_with_capacity_in(output_dtype, len, ctx.allocator());
395    let mut indices = BufferMut::<u64>::zeroed_in(len, ctx.allocator().clone());
396
397    let else_branch = (!else_mask.all_false()).then_some((else_mask, else_value));
398    let selections = branches
399        .iter()
400        .map(|(mask, value)| (mask, value))
401        .chain(else_branch);
402
403    for (mask, value) in selections {
404        let offset = builder.len();
405        value
406            .filter(mask.clone())?
407            .cast(output_dtype.clone())?
408            .append_to_builder(builder.as_mut(), ctx)?;
409        assign_positions(&mut indices, mask, offset);
410    }
411
412    builder.finish().take(indices.freeze().into_array())
413}
414
415fn merge_runs(
416    branches: &[(Mask, ArrayRef)],
417    else_value: &ArrayRef,
418    output_dtype: &DType,
419    ctx: &mut ExecutionCtx,
420) -> VortexResult<ArrayRef> {
421    let mut spans = Vec::new();
422    for (index, (mask, _)) in branches.iter().enumerate() {
423        if let AllOr::Some(slices) = mask.slices() {
424            spans.extend(slices.iter().map(|&(start, end)| (start, end, index)));
425        }
426    }
427    spans.sort_unstable_by_key(|&(start, ..)| start);
428
429    // Cast once up front: every span below is a slice of these arrays.
430    let values = branches
431        .iter()
432        .map(|(_, value)| value.cast(output_dtype.clone()))
433        .collect::<VortexResult<Vec<_>>>()?;
434    let else_value = else_value.cast(output_dtype.clone())?;
435    let len = else_value.len();
436
437    let mut builder = builder_with_capacity_in(output_dtype, len, ctx.allocator());
438    for (start, end, branch) in spans {
439        if builder.len() < start {
440            else_value
441                .slice(builder.len()..start)?
442                .append_to_builder(builder.as_mut(), ctx)?;
443        }
444
445        values[branch]
446            .slice(start..end)?
447            .append_to_builder(builder.as_mut(), ctx)?;
448    }
449
450    if builder.len() < len {
451        else_value
452            .slice(builder.len()..len)?
453            .append_to_builder(builder.as_mut(), ctx)?;
454    }
455
456    Ok(builder.finish())
457}
458
459fn assign_positions(indices: &mut [u64], mask: &Mask, offset: usize) {
460    match mask.indices() {
461        AllOr::All => {
462            for (position, index) in indices.iter_mut().enumerate() {
463                *index = (offset + position) as u64;
464            }
465        }
466        AllOr::None => {}
467        AllOr::Some(selected) => {
468            for (position, &row) in selected.iter().enumerate() {
469                indices[row] = (offset + position) as u64;
470            }
471        }
472    }
473}
474
475#[cfg(test)]
476mod tests {
477    use std::sync::LazyLock;
478
479    use rstest::rstest;
480    use vortex_buffer::Buffer;
481    use vortex_buffer::buffer;
482    use vortex_error::VortexExpect as _;
483    use vortex_session::VortexSession;
484
485    use super::*;
486    use crate::Canonical;
487    use crate::IntoArray;
488    use crate::VortexSessionExecute;
489    use crate::arrays::BoolArray;
490    use crate::arrays::DecimalArray;
491    use crate::arrays::PrimitiveArray;
492    use crate::arrays::ScalarFnArray;
493    use crate::arrays::StructArray;
494    use crate::arrays::VarBinViewArray;
495    use crate::assert_arrays_eq;
496    use crate::dtype::DType;
497    use crate::dtype::DecimalDType;
498    use crate::dtype::Nullability;
499    use crate::dtype::PType;
500    use crate::dtype::StructFields;
501    use crate::expr::Expression;
502    use crate::expr::case_when;
503    use crate::expr::case_when_no_else;
504    use crate::expr::col;
505    use crate::expr::eq;
506    use crate::expr::get_item;
507    use crate::expr::gt;
508    use crate::expr::is_not_null;
509    use crate::expr::is_null;
510    use crate::expr::lit;
511    use crate::expr::nested_case_when;
512    use crate::expr::proto::ExprSerializeProtoExt;
513    use crate::expr::root;
514    use crate::expr::test_harness;
515    use crate::scalar::Scalar;
516    use crate::scalar_fn::ScalarFnVTableExt;
517    use crate::scalar_fn::VecExecutionArgs;
518    use crate::scalar_fn::fns::operators::Operator;
519    use crate::validity::Validity;
520
521    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
522
523    #[test]
524    fn compact_and_run_merges_agree_for_nested_and_nullable_values() -> VortexResult<()> {
525        let primitive =
526            PrimitiveArray::from_option_iter([Some(1i64), None, Some(3), Some(4)]).into_array();
527        let fixtures = vec![
528            primitive.clone(),
529            DecimalArray::new(
530                buffer![100i64, -200, 300, 400],
531                DecimalDType::new(15, 2),
532                Validity::from_iter([true, false, true, true]),
533            )
534            .into_array(),
535            DecimalArray::new(
536                buffer![1i128 << 100, -2, 3, 4],
537                DecimalDType::new(38, 0),
538                Validity::NonNullable,
539            )
540            .into_array(),
541            VarBinViewArray::from_iter(
542                [
543                    Some("long out-of-line value"),
544                    None,
545                    Some("short"),
546                    Some(""),
547                ],
548                DType::Utf8(Nullability::Nullable),
549            )
550            .into_array(),
551            StructArray::try_from_iter([("nested", primitive)])?.into_array(),
552        ];
553        // Each case lists the branch selections in branch order. Rows that no branch
554        // selects come from ELSE.
555        let cases: [&[[bool; 4]]; 5] = [
556            &[[true, false, true, false]],
557            &[[true, true, false, false]],
558            &[[false, true, false, false]],
559            &[[true, false, false, false], [false, false, true, false]],
560            &[[false, false, false, true], [false, true, false, false]],
561        ];
562
563        let mut ctx = SESSION.create_execution_ctx();
564        for value in fixtures {
565            let reorder =
566                |indices: Buffer<u32>, ctx: &mut ExecutionCtx| -> VortexResult<ArrayRef> {
567                    Ok(value
568                        .take(indices.into_array())?
569                        .execute::<Canonical>(ctx)?
570                        .into_array())
571                };
572            let branch_values = [value.clone(), reorder(buffer![1u32, 0, 3, 2], &mut ctx)?];
573            let otherwise = reorder(buffer![3u32, 2, 1, 0], &mut ctx)?;
574
575            for selections in cases {
576                let branches: Vec<_> = selections
577                    .iter()
578                    .zip(&branch_values)
579                    .map(|(selection, value)| (Mask::from_iter(*selection), value.clone()))
580                    .collect();
581                let else_mask = Mask::from_iter(
582                    (0..4).map(|row| !selections.iter().any(|selection| selection[row])),
583                );
584
585                assert_arrays_eq!(
586                    merge_runs(&branches, &otherwise, value.dtype(), &mut ctx)?,
587                    merge_compact(&branches, &else_mask, &otherwise, value.dtype(), &mut ctx)?,
588                    &mut ctx
589                );
590            }
591        }
592
593        Ok(())
594    }
595
596    fn nested_struct(values: [Option<i32>; 4], nullable: bool) -> VortexResult<ArrayRef> {
597        let field = if nullable {
598            PrimitiveArray::from_option_iter(values).into_array()
599        } else {
600            PrimitiveArray::from_iter(values.map(|value| value.vortex_expect("non-null value")))
601                .into_array()
602        };
603
604        Ok(StructArray::try_from_iter([("a", field)])?.into_array())
605    }
606
607    /// THEN and ELSE may differ in nested nullability. The output must keep nested nulls from
608    /// either side, on the run merge, the compact merge and when no branch matches.
609    #[rstest]
610    #[case::compact_nullable_then([true, false, true, false], true)]
611    #[case::compact_nullable_else([true, false, true, false], false)]
612    #[case::runs_nullable_then([true, true, false, false], true)]
613    #[case::runs_nullable_else([true, true, false, false], false)]
614    #[case::no_match_nullable_else([false, false, false, false], false)]
615    fn nested_nullability_is_merged_across_branches(
616        #[case] selection: [bool; 4],
617        #[case] nullable_then: bool,
618    ) -> VortexResult<()> {
619        let nullable = [None, Some(2), None, Some(4)];
620        let non_nullable = [Some(10), Some(20), Some(30), Some(40)];
621        let (then_values, else_values) = if nullable_then {
622            (nullable, non_nullable)
623        } else {
624            (non_nullable, nullable)
625        };
626
627        let array = ScalarFnArray::try_new(
628            CaseWhen.bind(CaseWhenOptions {
629                num_when_then_pairs: 1,
630                has_else: true,
631            }),
632            vec![
633                BoolArray::from_iter(selection).into_array(),
634                nested_struct(then_values, nullable_then)?,
635                nested_struct(else_values, !nullable_then)?,
636            ],
637        )?
638        .into_array();
639
640        let expected = (0..4).map(|row| {
641            if selection[row] {
642                then_values[row]
643            } else {
644                else_values[row]
645            }
646        });
647        let expected = StructArray::try_from_iter([(
648            "a",
649            PrimitiveArray::from_option_iter(expected).into_array(),
650        )])?
651        .into_array();
652
653        let mut ctx = SESSION.create_execution_ctx();
654        assert_arrays_eq!(array, expected, &mut ctx);
655
656        Ok(())
657    }
658
659    #[test]
660    fn test_return_dtype_merges_nested_nullability() -> VortexResult<()> {
661        let field = |nullability| {
662            DType::Struct(
663                StructFields::new(
664                    ["a"].into(),
665                    vec![DType::Primitive(PType::I32, nullability)],
666                ),
667                Nullability::NonNullable,
668            )
669        };
670        let options = CaseWhenOptions {
671            num_when_then_pairs: 1,
672            has_else: true,
673        };
674        let condition = DType::Bool(Nullability::NonNullable);
675
676        for (then_dtype, else_dtype) in [
677            (
678                field(Nullability::Nullable),
679                field(Nullability::NonNullable),
680            ),
681            (
682                field(Nullability::NonNullable),
683                field(Nullability::Nullable),
684            ),
685        ] {
686            assert_eq!(
687                CaseWhen.return_dtype(&options, &[condition.clone(), then_dtype, else_dtype])?,
688                field(Nullability::Nullable)
689            );
690        }
691
692        Ok(())
693    }
694
695    #[test]
696    fn selected_rows_do_not_execute_erroring_branches_or_later_conditions() -> VortexResult<()> {
697        let mut ctx = SESSION.create_execution_ctx();
698        let condition =
699            BoolArray::from_iter([Some(true), Some(false), Some(true), None]).into_array();
700        let division = buffer![20i32, 30, 40, 50]
701            .into_array()
702            .binary(buffer![2i32, 0, 4, 0].into_array(), Operator::Div)?;
703        assert!(division.clone().execute::<Canonical>(&mut ctx).is_err());
704        let options = CaseWhenOptions {
705            num_when_then_pairs: 1,
706            has_else: true,
707        };
708        let result = CaseWhen.execute(
709            &options,
710            &VecExecutionArgs::new(
711                vec![
712                    condition.clone(),
713                    division.clone(),
714                    ConstantArray::new(7i32, 4).into_array(),
715                ],
716                4,
717            ),
718            &mut ctx,
719        )?;
720        assert_arrays_eq!(result, buffer![10i32, 7, 10, 7].into_array(), &mut ctx);
721
722        let result = CaseWhen.execute(
723            &options,
724            &VecExecutionArgs::new(
725                vec![
726                    condition.clone(),
727                    StructArray::try_from_iter([("value", division.clone())])?.into_array(),
728                    StructArray::try_from_iter([(
729                        "value",
730                        ConstantArray::new(7i32, 4).into_array(),
731                    )])?
732                    .into_array(),
733                ],
734                4,
735            ),
736            &mut ctx,
737        )?;
738        assert_arrays_eq!(
739            result,
740            StructArray::try_from_iter([("value", buffer![10i32, 7, 10, 7].into_array())])?
741                .into_array(),
742            &mut ctx
743        );
744
745        let later_condition = buffer![20i32, 30, 40, 50]
746            .into_array()
747            .binary(buffer![0i32, 3, 0, 5].into_array(), Operator::Div)?
748            .binary(ConstantArray::new(0i32, 4).into_array(), Operator::Gt)?;
749        let result = CaseWhen.execute(
750            &CaseWhenOptions {
751                num_when_then_pairs: 2,
752                has_else: true,
753            },
754            &VecExecutionArgs::new(
755                vec![
756                    condition,
757                    ConstantArray::new(2i32, 4).into_array(),
758                    later_condition,
759                    ConstantArray::new(3i32, 4).into_array(),
760                    division,
761                ],
762                4,
763            ),
764            &mut ctx,
765        )?;
766        assert_arrays_eq!(result, buffer![2i32, 3, 2, 3].into_array(), &mut ctx);
767
768        let selected_error = ScalarFnArray::try_new(
769            CaseWhen.bind(options),
770            vec![
771                ConstantArray::new(true, 4).into_array(),
772                buffer![20i32, 30, 40, 50]
773                    .into_array()
774                    .binary(buffer![2i32, 0, 4, 0].into_array(), Operator::Div)?,
775                ConstantArray::new(7i32, 4).into_array(),
776            ],
777        )?
778        .into_array();
779        assert!(selected_error.execute::<Canonical>(&mut ctx).is_err());
780        Ok(())
781    }
782
783    fn apply_expr(expr: &Expression, array: &ArrayRef) -> ArrayRef {
784        array.clone().apply(expr).unwrap()
785    }
786
787    fn apply_bound_expr(expr: &BoundExpression, array: &ArrayRef) -> ArrayRef {
788        array.clone().apply_bound(expr).unwrap()
789    }
790
791    // ==================== Serialization Tests ====================
792
793    #[rstest]
794    #[case(1, true, 3)]
795    #[case(1, false, 2)]
796    #[case(3, true, 7)]
797    #[case(4, false, 8)]
798    #[case(u32::MAX / 2, true, u32::MAX)]
799    #[case(u32::MAX / 2, false, u32::MAX - 1)]
800    fn test_serialization_roundtrip(
801        #[case] num_when_then_pairs: u32,
802        #[case] has_else: bool,
803        #[case] num_children: u32,
804    ) -> VortexResult<()> {
805        let options = CaseWhenOptions {
806            num_when_then_pairs,
807            has_else,
808        };
809        let serialized = CaseWhen.serialize(&options)?.expect("serializable options");
810        assert_eq!(
811            pb::CaseWhenOpts::decode(serialized.as_slice())?.num_children,
812            num_children
813        );
814        assert_eq!(CaseWhen.deserialize(&serialized, &SESSION)?, options);
815        Ok(())
816    }
817
818    #[rstest]
819    #[case(0, "at least one WHEN/THEN pair")]
820    #[case(u32::MAX / 2 + 1, "too many children")]
821    fn test_serialization_invalid_options(
822        #[case] num_when_then_pairs: u32,
823        #[case] expected_error: &str,
824        #[values(false, true)] has_else: bool,
825    ) {
826        let options = CaseWhenOptions {
827            num_when_then_pairs,
828            has_else,
829        };
830        let error = CaseWhen.serialize(&options).unwrap_err();
831        assert!(error.to_string().contains(expected_error));
832    }
833
834    #[rstest]
835    #[case::missing(&[])]
836    #[case::zero_children(&[0x08, 0])]
837    #[case::one_child(&[0x08, 1])]
838    #[case::truncated(&[0x08, 0x80])]
839    fn test_deserialization_invalid_metadata(#[case] metadata: &[u8]) {
840        assert!(CaseWhen.deserialize(metadata, &SESSION).is_err());
841    }
842
843    #[rstest]
844    fn test_expression_serialization_roundtrip(
845        #[values(1, 3)] num_when_then_pairs: u32,
846        #[values(false, true)] has_else: bool,
847    ) -> VortexResult<()> {
848        let branches = (0..num_when_then_pairs)
849            .map(|value| (eq(col("value"), lit(value)), lit(value)))
850            .collect();
851        let expression = nested_case_when(branches, has_else.then(|| lit(42u32)));
852        let bytes = expression.serialize_proto()?.encode_to_vec();
853        let proto = pb::Expr::decode(bytes.as_slice())?;
854        assert_eq!(proto.id, "vortex.case_when");
855        assert_eq!(Expression::from_proto(&proto, &SESSION)?, expression);
856        Ok(())
857    }
858
859    // ==================== Display Tests ====================
860
861    #[test]
862    fn test_display_with_else() {
863        let expr = case_when(gt(col("value"), lit(0i32)), lit(100i32), lit(0i32));
864        let display = format!("{}", expr);
865        assert!(display.contains("CASE"));
866        assert!(display.contains("WHEN"));
867        assert!(display.contains("THEN"));
868        assert!(display.contains("ELSE"));
869        assert!(display.contains("END"));
870    }
871
872    #[test]
873    fn test_display_no_else() {
874        let expr = case_when_no_else(gt(col("value"), lit(0i32)), lit(100i32));
875        let display = format!("{}", expr);
876        assert!(display.contains("CASE"));
877        assert!(display.contains("WHEN"));
878        assert!(display.contains("THEN"));
879        assert!(!display.contains("ELSE"));
880        assert!(display.contains("END"));
881    }
882
883    #[test]
884    fn test_display_nested_nary() {
885        // CASE WHEN x > 10 THEN 'high' WHEN x > 5 THEN 'medium' ELSE 'low' END
886        let expr = nested_case_when(
887            vec![
888                (gt(col("x"), lit(10i32)), lit("high")),
889                (gt(col("x"), lit(5i32)), lit("medium")),
890            ],
891            Some(lit("low")),
892        );
893        let display = format!("{}", expr);
894        assert_eq!(display.matches("CASE").count(), 1);
895        assert_eq!(display.matches("WHEN").count(), 2);
896        assert_eq!(display.matches("THEN").count(), 2);
897    }
898
899    // ==================== DType Tests ====================
900
901    #[test]
902    fn test_return_dtype_with_else() {
903        let expr = case_when(lit(true), lit(100i32), lit(0i32));
904        let input_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
905        let result_dtype = expr.return_dtype(&input_dtype).unwrap();
906        assert_eq!(
907            result_dtype,
908            DType::Primitive(PType::I32, Nullability::NonNullable)
909        );
910    }
911
912    #[test]
913    fn test_return_dtype_with_nullable_else() {
914        let expr = case_when(
915            lit(true),
916            lit(100i32),
917            lit(Scalar::null(DType::Primitive(
918                PType::I32,
919                Nullability::Nullable,
920            ))),
921        );
922        let input_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
923        let result_dtype = expr.return_dtype(&input_dtype).unwrap();
924        assert_eq!(
925            result_dtype,
926            DType::Primitive(PType::I32, Nullability::Nullable)
927        );
928    }
929
930    #[test]
931    fn test_return_dtype_without_else_is_nullable() {
932        let expr = case_when_no_else(lit(true), lit(100i32));
933        let input_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
934        let result_dtype = expr.return_dtype(&input_dtype).unwrap();
935        assert_eq!(
936            result_dtype,
937            DType::Primitive(PType::I32, Nullability::Nullable)
938        );
939    }
940
941    #[test]
942    fn test_return_dtype_with_struct_input() {
943        let dtype = test_harness::struct_dtype();
944        let expr = case_when(
945            gt(get_item("col1", root()), lit(10u16)),
946            lit(100i32),
947            lit(0i32),
948        );
949        let result_dtype = expr.return_dtype(&dtype).unwrap();
950        assert_eq!(
951            result_dtype,
952            DType::Primitive(PType::I32, Nullability::NonNullable)
953        );
954    }
955
956    #[test]
957    fn test_return_dtype_mismatched_then_else_errors() {
958        let expr = case_when(lit(true), lit(100i32), lit("zero"));
959        let input_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
960        let err = expr.return_dtype(&input_dtype).unwrap_err();
961        assert!(
962            err.to_string()
963                .contains("THEN and ELSE dtypes must match (ignoring nullability)")
964        );
965    }
966
967    // ==================== Arity Tests ====================
968
969    #[test]
970    fn test_arity_with_else() {
971        let options = CaseWhenOptions {
972            num_when_then_pairs: 1,
973            has_else: true,
974        };
975        assert_eq!(CaseWhen.arity(&options), Arity::Exact(3));
976    }
977
978    #[test]
979    fn test_arity_without_else() {
980        let options = CaseWhenOptions {
981            num_when_then_pairs: 1,
982            has_else: false,
983        };
984        assert_eq!(CaseWhen.arity(&options), Arity::Exact(2));
985    }
986
987    // ==================== Child Name Tests ====================
988
989    #[test]
990    fn test_child_names() {
991        let options = CaseWhenOptions {
992            num_when_then_pairs: 1,
993            has_else: true,
994        };
995        assert_eq!(CaseWhen.child_name(&options, 0).to_string(), "when_0");
996        assert_eq!(CaseWhen.child_name(&options, 1).to_string(), "then_0");
997        assert_eq!(CaseWhen.child_name(&options, 2).to_string(), "else");
998    }
999
1000    // ==================== N-ary Arity Tests ====================
1001
1002    #[test]
1003    fn test_arity_nary_with_else() {
1004        let options = CaseWhenOptions {
1005            num_when_then_pairs: 3,
1006            has_else: true,
1007        };
1008        // 3 pairs * 2 children + 1 else = 7
1009        assert_eq!(CaseWhen.arity(&options), Arity::Exact(7));
1010    }
1011
1012    #[test]
1013    fn test_arity_nary_without_else() {
1014        let options = CaseWhenOptions {
1015            num_when_then_pairs: 3,
1016            has_else: false,
1017        };
1018        // 3 pairs * 2 children = 6
1019        assert_eq!(CaseWhen.arity(&options), Arity::Exact(6));
1020    }
1021
1022    // ==================== N-ary Child Name Tests ====================
1023
1024    #[test]
1025    fn test_child_names_nary() {
1026        let options = CaseWhenOptions {
1027            num_when_then_pairs: 3,
1028            has_else: true,
1029        };
1030        assert_eq!(CaseWhen.child_name(&options, 0).to_string(), "when_0");
1031        assert_eq!(CaseWhen.child_name(&options, 1).to_string(), "then_0");
1032        assert_eq!(CaseWhen.child_name(&options, 2).to_string(), "when_1");
1033        assert_eq!(CaseWhen.child_name(&options, 3).to_string(), "then_1");
1034        assert_eq!(CaseWhen.child_name(&options, 4).to_string(), "when_2");
1035        assert_eq!(CaseWhen.child_name(&options, 5).to_string(), "then_2");
1036        assert_eq!(CaseWhen.child_name(&options, 6).to_string(), "else");
1037    }
1038
1039    // ==================== N-ary DType Tests ====================
1040
1041    #[test]
1042    fn test_return_dtype_nary_mismatched_then_types_errors() {
1043        let expr = nested_case_when(
1044            vec![(lit(true), lit(100i32)), (lit(false), lit("oops"))],
1045            Some(lit(0i32)),
1046        );
1047        let input_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
1048        let err = expr.return_dtype(&input_dtype).unwrap_err();
1049        assert!(err.to_string().contains("THEN dtypes must match"));
1050    }
1051
1052    #[test]
1053    fn test_return_dtype_nary_mixed_nullability() {
1054        // When some THEN branches are nullable and others are not,
1055        // the result should be nullable (union of nullabilities).
1056        let non_null_then = lit(100i32);
1057        let nullable_then = lit(Scalar::null(DType::Primitive(
1058            PType::I32,
1059            Nullability::Nullable,
1060        )));
1061        let expr = nested_case_when(
1062            vec![(lit(true), non_null_then), (lit(false), nullable_then)],
1063            Some(lit(0i32)),
1064        );
1065        let input_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
1066        let result = expr.return_dtype(&input_dtype).unwrap();
1067        assert_eq!(result, DType::Primitive(PType::I32, Nullability::Nullable));
1068    }
1069
1070    #[test]
1071    fn test_return_dtype_nary_no_else_is_nullable() {
1072        let expr = nested_case_when(
1073            vec![(lit(true), lit(10i32)), (lit(false), lit(20i32))],
1074            None,
1075        );
1076        let input_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
1077        let result = expr.return_dtype(&input_dtype).unwrap();
1078        assert_eq!(result, DType::Primitive(PType::I32, Nullability::Nullable));
1079    }
1080
1081    // ==================== Expression Manipulation Tests ====================
1082
1083    #[test]
1084    fn test_replace_children() {
1085        let expr = case_when(lit(true), lit(1i32), lit(0i32));
1086        let replaced = expr
1087            .with_children([lit(false), lit(2i32), lit(3i32)])
1088            .vortex_expect("operation should succeed in test");
1089        assert_eq!(replaced, case_when(lit(false), lit(2i32), lit(3i32)));
1090    }
1091
1092    // ==================== Evaluate Tests ====================
1093
1094    #[test]
1095    fn test_evaluate_simple_condition() {
1096        let mut ctx = SESSION.create_execution_ctx();
1097        let test_array =
1098            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1099                .unwrap()
1100                .into_array();
1101
1102        let expr = case_when(
1103            gt(get_item("value", root()), lit(2i32)),
1104            lit(100i32),
1105            lit(0i32),
1106        );
1107
1108        let result = apply_expr(&expr, &test_array);
1109        assert_arrays_eq!(
1110            result,
1111            buffer![0i32, 0, 100, 100, 100].into_array(),
1112            &mut ctx
1113        );
1114    }
1115
1116    #[test]
1117    fn test_evaluate_nary_multiple_conditions() {
1118        let mut ctx = SESSION.create_execution_ctx();
1119        // Test n-ary via nested_case_when
1120        let test_array =
1121            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1122                .unwrap()
1123                .into_array();
1124
1125        let expr = nested_case_when(
1126            vec![
1127                (eq(get_item("value", root()), lit(1i32)), lit(10i32)),
1128                (eq(get_item("value", root()), lit(3i32)), lit(30i32)),
1129            ],
1130            Some(lit(0i32)),
1131        );
1132
1133        let result = apply_expr(&expr, &test_array);
1134        assert_arrays_eq!(result, buffer![10i32, 0, 30, 0, 0].into_array(), &mut ctx);
1135    }
1136
1137    #[test]
1138    fn test_evaluate_nary_first_match_wins() {
1139        let mut ctx = SESSION.create_execution_ctx();
1140        let test_array =
1141            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1142                .unwrap()
1143                .into_array();
1144
1145        // Both conditions match for values > 3, but first one wins
1146        let expr = nested_case_when(
1147            vec![
1148                (gt(get_item("value", root()), lit(2i32)), lit(100i32)),
1149                (gt(get_item("value", root()), lit(3i32)), lit(200i32)),
1150            ],
1151            Some(lit(0i32)),
1152        );
1153
1154        let result = apply_expr(&expr, &test_array);
1155        assert_arrays_eq!(
1156            result,
1157            buffer![0i32, 0, 100, 100, 100].into_array(),
1158            &mut ctx
1159        );
1160    }
1161
1162    #[test]
1163    fn test_evaluate_no_else_returns_null() {
1164        let mut ctx = SESSION.create_execution_ctx();
1165        let test_array =
1166            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1167                .unwrap()
1168                .into_array();
1169
1170        let expr = case_when_no_else(gt(get_item("value", root()), lit(3i32)), lit(100i32));
1171
1172        let result = apply_expr(&expr, &test_array);
1173        assert!(result.dtype().is_nullable());
1174        assert_arrays_eq!(
1175            result,
1176            PrimitiveArray::from_option_iter([None::<i32>, None, None, Some(100), Some(100)])
1177                .into_array(),
1178            &mut ctx
1179        );
1180    }
1181
1182    #[test]
1183    fn test_evaluate_all_conditions_false() {
1184        let mut ctx = SESSION.create_execution_ctx();
1185        let test_array =
1186            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1187                .unwrap()
1188                .into_array();
1189
1190        let expr = case_when(
1191            gt(get_item("value", root()), lit(100i32)),
1192            lit(1i32),
1193            lit(0i32),
1194        );
1195
1196        let result = apply_expr(&expr, &test_array);
1197        assert_arrays_eq!(result, buffer![0i32, 0, 0, 0, 0].into_array(), &mut ctx);
1198    }
1199
1200    #[test]
1201    fn test_evaluate_all_conditions_true() {
1202        let mut ctx = SESSION.create_execution_ctx();
1203        let test_array =
1204            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1205                .unwrap()
1206                .into_array();
1207
1208        let expr = case_when(
1209            gt(get_item("value", root()), lit(0i32)),
1210            lit(100i32),
1211            lit(0i32),
1212        );
1213
1214        let result = apply_expr(&expr, &test_array);
1215        assert_arrays_eq!(
1216            result,
1217            buffer![100i32, 100, 100, 100, 100].into_array(),
1218            &mut ctx
1219        );
1220    }
1221
1222    #[test]
1223    fn test_evaluate_all_true_no_else_returns_correct_dtype() {
1224        let mut ctx = SESSION.create_execution_ctx();
1225        // CASE WHEN value > 0 THEN 100 END — condition is always true, no ELSE.
1226        // Result must be Nullable because the implicit ELSE is NULL.
1227        let test_array = StructArray::from_fields(&[("value", buffer![1i32, 2, 3].into_array())])
1228            .unwrap()
1229            .into_array();
1230
1231        let expr = case_when_no_else(gt(get_item("value", root()), lit(0i32)), lit(100i32));
1232
1233        let result = apply_expr(&expr, &test_array);
1234        assert!(
1235            result.dtype().is_nullable(),
1236            "result dtype must be Nullable, got {:?}",
1237            result.dtype()
1238        );
1239        assert_arrays_eq!(
1240            result,
1241            PrimitiveArray::from_option_iter([Some(100i32), Some(100), Some(100)]).into_array(),
1242            &mut ctx
1243        );
1244    }
1245
1246    #[test]
1247    fn test_merge_case_branches_widens_nullability_of_later_branch() -> VortexResult<()> {
1248        let mut ctx = SESSION.create_execution_ctx();
1249        // When a later THEN branch is Nullable and branches[0] and ELSE are NonNullable,
1250        // the result dtype must still be Nullable.
1251        //
1252        // CASE WHEN value = 0 THEN 10          -- NonNullable
1253        //      WHEN value = 1 THEN nullable(20) -- Nullable
1254        //      ELSE 0                           -- NonNullable
1255        // → result must be Nullable(i32)
1256        let test_array =
1257            StructArray::from_fields(&[("value", buffer![0i32, 1, 2].into_array())])?.into_array();
1258
1259        let nullable_20 =
1260            Scalar::from(20i32).cast(&DType::Primitive(PType::I32, Nullability::Nullable))?;
1261
1262        let expr = nested_case_when(
1263            vec![
1264                (eq(get_item("value", root()), lit(0i32)), lit(10i32)),
1265                (eq(get_item("value", root()), lit(1i32)), lit(nullable_20)),
1266            ],
1267            Some(lit(0i32)),
1268        );
1269
1270        let result = apply_expr(&expr, &test_array);
1271        assert!(
1272            result.dtype().is_nullable(),
1273            "result dtype must be Nullable, got {:?}",
1274            result.dtype()
1275        );
1276        assert_arrays_eq!(
1277            result,
1278            PrimitiveArray::from_option_iter([Some(10), Some(20), Some(0)]).into_array(),
1279            &mut ctx
1280        );
1281        Ok(())
1282    }
1283
1284    #[test]
1285    fn test_evaluate_with_literal_condition() {
1286        let mut ctx = SESSION.create_execution_ctx();
1287        let test_array = buffer![1i32, 2, 3].into_array();
1288        let expr = case_when(lit(true), lit(100i32), lit(0i32));
1289        let result = apply_expr(&expr, &test_array);
1290
1291        assert_arrays_eq!(result, buffer![100i32, 100, 100].into_array(), &mut ctx);
1292    }
1293
1294    #[test]
1295    fn test_evaluate_with_bool_column_result() {
1296        let mut ctx = SESSION.create_execution_ctx();
1297        let test_array =
1298            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1299                .unwrap()
1300                .into_array();
1301
1302        let expr = case_when(
1303            gt(get_item("value", root()), lit(2i32)),
1304            lit(true),
1305            lit(false),
1306        );
1307
1308        let result = apply_expr(&expr, &test_array);
1309        assert_arrays_eq!(
1310            result,
1311            BoolArray::from_iter([false, false, true, true, true]).into_array(),
1312            &mut ctx
1313        );
1314    }
1315
1316    #[test]
1317    fn test_evaluate_with_nullable_condition() {
1318        let mut ctx = SESSION.create_execution_ctx();
1319        let test_array = StructArray::from_fields(&[(
1320            "cond",
1321            BoolArray::from_iter([Some(true), None, Some(false), None, Some(true)]).into_array(),
1322        )])
1323        .unwrap()
1324        .into_array();
1325
1326        let expr = case_when(get_item("cond", root()), lit(100i32), lit(0i32));
1327
1328        let result = apply_expr(&expr, &test_array);
1329        assert_arrays_eq!(result, buffer![100i32, 0, 0, 0, 100].into_array(), &mut ctx);
1330    }
1331
1332    #[test]
1333    fn test_evaluate_with_nullable_result_values() {
1334        let mut ctx = SESSION.create_execution_ctx();
1335        let test_array = StructArray::from_fields(&[
1336            ("value", buffer![1i32, 2, 3, 4, 5].into_array()),
1337            (
1338                "result",
1339                PrimitiveArray::from_option_iter([Some(10), None, Some(30), None, Some(50)])
1340                    .into_array(),
1341            ),
1342        ])
1343        .unwrap()
1344        .into_array();
1345
1346        let expr = case_when(
1347            gt(get_item("value", root()), lit(2i32)),
1348            get_item("result", root()),
1349            lit(0i32),
1350        );
1351
1352        let result = apply_expr(&expr, &test_array);
1353        assert_arrays_eq!(
1354            result,
1355            PrimitiveArray::from_option_iter([Some(0i32), Some(0), Some(30), None, Some(50)])
1356                .into_array(),
1357            &mut ctx
1358        );
1359    }
1360
1361    #[test]
1362    fn test_evaluate_with_all_null_condition() {
1363        let mut ctx = SESSION.create_execution_ctx();
1364        let test_array = StructArray::from_fields(&[(
1365            "cond",
1366            BoolArray::from_iter([None, None, None]).into_array(),
1367        )])
1368        .unwrap()
1369        .into_array();
1370
1371        let expr = case_when(get_item("cond", root()), lit(100i32), lit(0i32));
1372
1373        let result = apply_expr(&expr, &test_array);
1374        assert_arrays_eq!(result, buffer![0i32, 0, 0].into_array(), &mut ctx);
1375    }
1376
1377    // ==================== N-ary Evaluate Tests ====================
1378
1379    #[test]
1380    fn test_evaluate_nary_no_else_returns_null() {
1381        let mut ctx = SESSION.create_execution_ctx();
1382        let test_array =
1383            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1384                .unwrap()
1385                .into_array();
1386
1387        // Two conditions, no ELSE — unmatched rows should be NULL
1388        let expr = nested_case_when(
1389            vec![
1390                (eq(get_item("value", root()), lit(1i32)), lit(10i32)),
1391                (eq(get_item("value", root()), lit(3i32)), lit(30i32)),
1392            ],
1393            None,
1394        );
1395
1396        let result = apply_expr(&expr, &test_array);
1397        assert!(result.dtype().is_nullable());
1398        assert_arrays_eq!(
1399            result,
1400            PrimitiveArray::from_option_iter([Some(10i32), None, Some(30), None, None])
1401                .into_array(),
1402            &mut ctx
1403        );
1404    }
1405
1406    #[test]
1407    fn test_evaluate_nary_many_conditions() {
1408        let mut ctx = SESSION.create_execution_ctx();
1409        let test_array =
1410            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4, 5].into_array())])
1411                .unwrap()
1412                .into_array();
1413
1414        // 5 WHEN/THEN pairs: each value maps to its value * 10
1415        let expr = nested_case_when(
1416            vec![
1417                (eq(get_item("value", root()), lit(1i32)), lit(10i32)),
1418                (eq(get_item("value", root()), lit(2i32)), lit(20i32)),
1419                (eq(get_item("value", root()), lit(3i32)), lit(30i32)),
1420                (eq(get_item("value", root()), lit(4i32)), lit(40i32)),
1421                (eq(get_item("value", root()), lit(5i32)), lit(50i32)),
1422            ],
1423            Some(lit(0i32)),
1424        );
1425
1426        let result = apply_expr(&expr, &test_array);
1427        assert_arrays_eq!(
1428            result,
1429            buffer![10i32, 20, 30, 40, 50].into_array(),
1430            &mut ctx
1431        );
1432    }
1433
1434    #[test]
1435    fn test_evaluate_nary_all_false_no_else() {
1436        let mut ctx = SESSION.create_execution_ctx();
1437        let test_array = StructArray::from_fields(&[("value", buffer![1i32, 2, 3].into_array())])
1438            .unwrap()
1439            .into_array();
1440
1441        // All conditions are false, no ELSE — everything should be NULL
1442        let expr = nested_case_when(
1443            vec![
1444                (gt(get_item("value", root()), lit(100i32)), lit(10i32)),
1445                (gt(get_item("value", root()), lit(200i32)), lit(20i32)),
1446            ],
1447            None,
1448        );
1449
1450        let result = apply_expr(&expr, &test_array);
1451        assert!(result.dtype().is_nullable());
1452        assert_arrays_eq!(
1453            result,
1454            PrimitiveArray::from_option_iter([None::<i32>, None, None]).into_array(),
1455            &mut ctx
1456        );
1457    }
1458
1459    #[test]
1460    fn test_evaluate_nary_overlapping_conditions_first_wins() {
1461        let mut ctx = SESSION.create_execution_ctx();
1462        let test_array =
1463            StructArray::from_fields(&[("value", buffer![10i32, 20, 30].into_array())])
1464                .unwrap()
1465                .into_array();
1466
1467        // value=10: matches cond1 (>5) and cond2 (>0), first should win
1468        // value=20: matches all three, first should win
1469        // value=30: matches all three, first should win
1470        let expr = nested_case_when(
1471            vec![
1472                (gt(get_item("value", root()), lit(5i32)), lit(1i32)),
1473                (gt(get_item("value", root()), lit(0i32)), lit(2i32)),
1474                (gt(get_item("value", root()), lit(15i32)), lit(3i32)),
1475            ],
1476            Some(lit(0i32)),
1477        );
1478
1479        let result = apply_expr(&expr, &test_array);
1480        // First matching condition always wins
1481        assert_arrays_eq!(result, buffer![1i32, 1, 1].into_array(), &mut ctx);
1482    }
1483
1484    #[test]
1485    fn test_evaluate_nary_early_exit_when_remaining_empty() {
1486        let mut ctx = SESSION.create_execution_ctx();
1487        // After branch 0 claims all rows, remaining becomes all_false.
1488        // The loop breaks before evaluating branch 1's condition.
1489        let test_array = StructArray::from_fields(&[("value", buffer![1i32, 2, 3].into_array())])
1490            .unwrap()
1491            .into_array();
1492
1493        let expr = nested_case_when(
1494            vec![
1495                (gt(get_item("value", root()), lit(0i32)), lit(100i32)),
1496                // Never evaluated due to early exit; 999 must never appear in output.
1497                (gt(get_item("value", root()), lit(0i32)), lit(999i32)),
1498            ],
1499            Some(lit(0i32)),
1500        );
1501
1502        let result = apply_expr(&expr, &test_array);
1503        assert_arrays_eq!(result, buffer![100i32, 100, 100].into_array(), &mut ctx);
1504    }
1505
1506    #[test]
1507    fn test_evaluate_nary_skips_branch_with_empty_effective_mask() {
1508        let mut ctx = SESSION.create_execution_ctx();
1509        // Branch 0 claims value=1. Branch 1 targets the same rows but they are already
1510        // matched → effective_mask is all_false → branch 1 is skipped (THEN not used).
1511        let test_array = StructArray::from_fields(&[("value", buffer![1i32, 2, 3].into_array())])
1512            .unwrap()
1513            .into_array();
1514
1515        let expr = nested_case_when(
1516            vec![
1517                (eq(get_item("value", root()), lit(1i32)), lit(10i32)),
1518                // Same condition as branch 0 — all matching rows already claimed → skipped.
1519                // 999 must never appear in output.
1520                (eq(get_item("value", root()), lit(1i32)), lit(999i32)),
1521                (eq(get_item("value", root()), lit(2i32)), lit(20i32)),
1522            ],
1523            Some(lit(0i32)),
1524        );
1525
1526        let result = apply_expr(&expr, &test_array);
1527        assert_arrays_eq!(result, buffer![10i32, 20, 0].into_array(), &mut ctx);
1528    }
1529
1530    #[test]
1531    fn test_evaluate_nary_string_output() -> VortexResult<()> {
1532        // Exercises merge_case_branches with a non-primitive (Utf8) builder.
1533        let test_array =
1534            StructArray::from_fields(&[("value", buffer![1i32, 2, 3, 4].into_array())])?
1535                .into_array();
1536
1537        // CASE WHEN value > 2 THEN 'high' WHEN value > 0 THEN 'low' ELSE 'none' END
1538        // value=1,2 → 'low' (branch 1 after branch 0 claims 3,4)
1539        // value=3,4 → 'high' (branch 0)
1540        let expr = nested_case_when(
1541            vec![
1542                (gt(get_item("value", root()), lit(2i32)), lit("high")),
1543                (gt(get_item("value", root()), lit(0i32)), lit("low")),
1544            ],
1545            Some(lit("none")),
1546        );
1547
1548        let result = apply_expr(&expr, &test_array);
1549        assert_arrays_eq!(
1550            result,
1551            VarBinViewArray::from_iter_str(["low", "low", "high", "high"]),
1552            &mut SESSION.create_execution_ctx()
1553        );
1554        Ok(())
1555    }
1556
1557    #[test]
1558    fn test_evaluate_nary_with_nullable_conditions() {
1559        let mut ctx = SESSION.create_execution_ctx();
1560        let test_array = StructArray::from_fields(&[
1561            (
1562                "cond1",
1563                BoolArray::from_iter([Some(true), None, Some(false)]).into_array(),
1564            ),
1565            (
1566                "cond2",
1567                BoolArray::from_iter([Some(false), Some(true), None]).into_array(),
1568            ),
1569        ])
1570        .unwrap()
1571        .into_array();
1572
1573        let expr = nested_case_when(
1574            vec![
1575                (get_item("cond1", root()), lit(10i32)),
1576                (get_item("cond2", root()), lit(20i32)),
1577            ],
1578            Some(lit(0i32)),
1579        );
1580
1581        let result = apply_expr(&expr, &test_array);
1582        // row 0: cond1=true → 10
1583        // row 1: cond1=NULL(→false), cond2=true → 20
1584        // row 2: cond1=false, cond2=NULL(→false) → else=0
1585        assert_arrays_eq!(result, buffer![10i32, 20, 0].into_array(), &mut ctx);
1586    }
1587
1588    // ==================== Simplify: COALESCE -> fill_null ====================
1589
1590    /// Builds a non-nullable struct scope whose named fields are all `Nullable(I64)`.
1591    fn nullable_i64_scope(fields: &[&str]) -> DType {
1592        DType::Struct(
1593            StructFields::new(
1594                fields.to_vec().into(),
1595                vec![DType::Primitive(PType::I64, Nullability::Nullable); fields.len()],
1596            ),
1597            Nullability::NonNullable,
1598        )
1599    }
1600
1601    #[test]
1602    fn test_simplify_coalesce_is_null_rewrites_to_fill_null() -> VortexResult<()> {
1603        // CASE WHEN is_null(x) THEN 0 ELSE x END  ==>  fill_null(x, 0)
1604        let expr = case_when(is_null(col("x")), lit(0i64), col("x"));
1605        let optimized = expr
1606            .bind(&nullable_i64_scope(&["x"]))?
1607            .optimize_recursive()?;
1608        assert!(
1609            optimized.to_string().starts_with("vortex.fill_null"),
1610            "expected fill_null, got {optimized}"
1611        );
1612        Ok(())
1613    }
1614
1615    #[test]
1616    fn test_simplify_coalesce_is_not_null_rewrites_to_fill_null() -> VortexResult<()> {
1617        // CASE WHEN is_not_null(x) THEN x ELSE 0 END  ==>  fill_null(x, 0)
1618        let expr = case_when(is_not_null(col("x")), col("x"), lit(0i64));
1619        let optimized = expr
1620            .bind(&nullable_i64_scope(&["x"]))?
1621            .optimize_recursive()?;
1622        assert!(
1623            optimized.to_string().starts_with("vortex.fill_null"),
1624            "expected fill_null, got {optimized}"
1625        );
1626        Ok(())
1627    }
1628
1629    #[test]
1630    fn test_simplify_does_not_fire_when_operands_differ() -> VortexResult<()> {
1631        // The is_null operand (x) and the ELSE (y) are different columns: not a COALESCE.
1632        let expr = case_when(is_null(col("x")), lit(0i64), col("y"));
1633        let optimized = expr
1634            .bind(&nullable_i64_scope(&["x", "y"]))?
1635            .optimize_recursive()?;
1636        let s = optimized.to_string();
1637        assert!(s.contains("CASE"), "expected CASE WHEN to remain, got {s}");
1638        assert!(!s.contains("fill_null"), "must not rewrite, got {s}");
1639        Ok(())
1640    }
1641
1642    #[test]
1643    fn test_simplify_does_not_fire_for_non_constant_fill() -> VortexResult<()> {
1644        // COALESCE(x, c) with a *column* fill: fill_null cannot consume a non-constant
1645        // fill value, so the rewrite must not fire.
1646        let expr = case_when(is_null(col("x")), col("c"), col("x"));
1647        let optimized = expr
1648            .bind(&nullable_i64_scope(&["x", "c"]))?
1649            .optimize_recursive()?;
1650        let s = optimized.to_string();
1651        assert!(s.contains("CASE"), "expected CASE WHEN to remain, got {s}");
1652        assert!(!s.contains("fill_null"), "must not rewrite, got {s}");
1653        Ok(())
1654    }
1655
1656    #[test]
1657    fn test_simplify_null_fill_collapses_to_input() -> VortexResult<()> {
1658        // Filling the nulls of x with NULL is a no-op, so both forms collapse to just `x`.
1659        //   CASE WHEN is_null(x)     THEN null ELSE x    END  ==>  x
1660        //   CASE WHEN is_not_null(x) THEN x    ELSE null END  ==>  x
1661        let null_fill = || {
1662            lit(Scalar::null(DType::Primitive(
1663                PType::I64,
1664                Nullability::Nullable,
1665            )))
1666        };
1667
1668        for expr in [
1669            case_when(is_null(col("x")), null_fill(), col("x")),
1670            case_when(is_not_null(col("x")), col("x"), null_fill()),
1671        ] {
1672            let optimized = expr
1673                .bind(&nullable_i64_scope(&["x"]))?
1674                .optimize_recursive()?;
1675            assert_eq!(
1676                optimized.to_string(),
1677                "$.x",
1678                "expected collapse to input column, got {optimized}"
1679            );
1680        }
1681        Ok(())
1682    }
1683
1684    #[test]
1685    fn test_simplify_null_fill_semantic_equivalence() -> VortexResult<()> {
1686        let mut ctx = SESSION.create_execution_ctx();
1687        // The collapse-to-input rewrite must preserve values (and `x`'s nullability).
1688        let array = PrimitiveArray::from_option_iter([Some(1i64), None, Some(3)]).into_array();
1689        let scope = DType::Primitive(PType::I64, Nullability::Nullable);
1690        let null_fill = lit(Scalar::null(DType::Primitive(
1691            PType::I64,
1692            Nullability::Nullable,
1693        )));
1694
1695        let original = case_when(is_null(root()), null_fill, root());
1696        let optimized = original.bind(&scope)?.optimize_recursive()?;
1697        assert_eq!(
1698            optimized.to_string(),
1699            "$",
1700            "expected collapse to root, got {optimized}"
1701        );
1702
1703        let expected = PrimitiveArray::from_option_iter([Some(1i64), None, Some(3)]).into_array();
1704        assert_arrays_eq!(apply_expr(&original, &array), expected, &mut ctx);
1705        assert_arrays_eq!(apply_bound_expr(&optimized, &array), expected, &mut ctx);
1706        Ok(())
1707    }
1708
1709    #[test]
1710    fn test_simplify_does_not_fire_without_else() -> VortexResult<()> {
1711        let expr = case_when_no_else(is_null(col("x")), lit(0i64));
1712        let optimized = expr
1713            .bind(&nullable_i64_scope(&["x"]))?
1714            .optimize_recursive()?;
1715        assert!(
1716            !optimized.to_string().contains("fill_null"),
1717            "must not rewrite a no-ELSE case_when, got {optimized}"
1718        );
1719        Ok(())
1720    }
1721
1722    #[test]
1723    fn test_simplify_does_not_fire_for_multi_pair() -> VortexResult<()> {
1724        let expr = nested_case_when(
1725            vec![
1726                (is_null(col("x")), lit(0i64)),
1727                (gt(col("x"), lit(5i64)), lit(1i64)),
1728            ],
1729            Some(col("x")),
1730        );
1731        let optimized = expr
1732            .bind(&nullable_i64_scope(&["x"]))?
1733            .optimize_recursive()?;
1734        assert!(
1735            !optimized.to_string().contains("fill_null"),
1736            "must not rewrite a multi-pair case_when, got {optimized}"
1737        );
1738        Ok(())
1739    }
1740
1741    #[test]
1742    fn test_simplify_semantic_equivalence() -> VortexResult<()> {
1743        let mut ctx = SESSION.create_execution_ctx();
1744        // The optimized expression must produce the same values as the original CASE WHEN.
1745        let array = PrimitiveArray::from_option_iter([Some(1i64), None, Some(3)]).into_array();
1746        let scope = DType::Primitive(PType::I64, Nullability::Nullable);
1747
1748        let original = case_when(is_null(root()), lit(0i64), root());
1749        let optimized = original.bind(&scope)?.optimize_recursive()?;
1750        assert!(
1751            optimized.to_string().starts_with("vortex.fill_null"),
1752            "expected fill_null, got {optimized}"
1753        );
1754
1755        // Original keeps CASE WHEN's nullable result dtype; the rewrite tightens it to
1756        // NonNullable because a non-null fill cannot leave any nulls behind. Values match.
1757        assert_arrays_eq!(
1758            apply_expr(&original, &array),
1759            PrimitiveArray::from_option_iter([Some(1i64), Some(0), Some(3)]).into_array(),
1760            &mut ctx
1761        );
1762        assert_arrays_eq!(
1763            apply_bound_expr(&optimized, &array),
1764            buffer![1i64, 0, 3].into_array(),
1765            &mut ctx
1766        );
1767        Ok(())
1768    }
1769
1770    #[test]
1771    fn test_simplify_utf8_coalesce_remains_executable() -> VortexResult<()> {
1772        let mut ctx = SESSION.create_execution_ctx();
1773        let input = VarBinViewArray::from_iter_nullable_str([Some("a"), None]).into_array();
1774
1775        for expr in [
1776            case_when(is_null(root()), lit("fallback"), root()),
1777            case_when(is_not_null(root()), root(), lit("fallback")),
1778        ] {
1779            let optimized = expr.bind(input.dtype())?.optimize_recursive()?;
1780            assert!(optimized.is::<FillNull>(), "{optimized}");
1781            let result = input.clone().apply_bound(&optimized)?;
1782            assert_arrays_eq!(
1783                result,
1784                VarBinViewArray::from_iter_str(["a", "fallback"]),
1785                &mut ctx
1786            );
1787        }
1788        Ok(())
1789    }
1790
1791    #[test]
1792    fn test_simplify_list_coalesce_keeps_case_when() -> VortexResult<()> {
1793        // Lists have no fill_null kernel, so the COALESCE shape must stay a CASE WHEN.
1794        let mut ctx = SESSION.create_execution_ctx();
1795        let element_dtype = Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable));
1796        let input_dtype = DType::List(Arc::clone(&element_dtype), Nullability::Nullable);
1797        let mut builder = builder_with_capacity_in(&input_dtype, 2, ctx.allocator());
1798        builder.append_scalar(&Scalar::list(
1799            Arc::clone(&element_dtype),
1800            vec![Scalar::from(1i32)],
1801            Nullability::Nullable,
1802        ))?;
1803        builder.append_scalar(&Scalar::null(input_dtype))?;
1804        let input = builder.finish();
1805        let fill = Scalar::list(
1806            element_dtype,
1807            vec![Scalar::from(2i32)],
1808            Nullability::NonNullable,
1809        );
1810
1811        let optimized = case_when(is_null(root()), lit(fill.clone()), root())
1812            .bind(input.dtype())?
1813            .optimize_recursive()?;
1814        assert!(optimized.is::<CaseWhen>(), "{optimized}");
1815        let result = input
1816            .clone()
1817            .apply_bound(&optimized)?
1818            .execute::<Canonical>(&mut ctx)?
1819            .into_array();
1820        assert_eq!(
1821            result.execute_scalar(0, &mut ctx)?,
1822            input.execute_scalar(0, &mut ctx)?
1823        );
1824        assert_eq!(
1825            result.execute_scalar(1, &mut ctx)?,
1826            fill.cast(result.dtype())?
1827        );
1828        Ok(())
1829    }
1830
1831    #[test]
1832    fn test_merge_case_branches_alternating_mask() -> VortexResult<()> {
1833        let mut ctx = SESSION.create_execution_ctx();
1834        // Alternating rows exercise compact branch assembly.
1835        let n = 100usize;
1836
1837        // Branch 0: even rows → 0, Branch 1: odd rows → 1, Else: never reached.
1838        let branch0_mask = Mask::from_indices(n, (0..n).step_by(2));
1839        let branch1_mask = Mask::from_indices(n, (1..n).step_by(2));
1840
1841        let else_value = PrimitiveArray::from_option_iter(vec![Some(99i32); n]).into_array();
1842        let output_dtype = else_value.dtype().clone();
1843        let result = merge_case_branches(
1844            &[
1845                (
1846                    branch0_mask,
1847                    PrimitiveArray::from_option_iter(vec![Some(0i32); n]).into_array(),
1848                ),
1849                (
1850                    branch1_mask,
1851                    PrimitiveArray::from_option_iter(vec![Some(1i32); n]).into_array(),
1852                ),
1853            ],
1854            &Mask::new_false(n),
1855            &else_value,
1856            &output_dtype,
1857            &mut SESSION.create_execution_ctx(),
1858        )?;
1859
1860        // Even rows → 0, odd rows → 1.
1861        let expected: Vec<Option<i32>> = (0..n)
1862            .map(|v| if v % 2 == 0 { Some(0) } else { Some(1) })
1863            .collect();
1864        assert_arrays_eq!(
1865            result,
1866            PrimitiveArray::from_option_iter(expected).into_array(),
1867            &mut ctx
1868        );
1869        Ok(())
1870    }
1871}