Skip to main content

vortex_array/expr/
exprs.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Factory functions for creating [`Expression`]s from scalar function vtables.
5
6use std::sync::Arc;
7
8use vortex_error::VortexExpect;
9use vortex_error::VortexResult;
10use vortex_error::vortex_ensure;
11use vortex_error::vortex_panic;
12use vortex_utils::iter::ReduceBalancedIterExt;
13
14use crate::aggregate_fn::NumericalAggregateOpts;
15use crate::dtype::DType;
16use crate::dtype::FieldName;
17use crate::dtype::FieldNames;
18use crate::dtype::Nullability;
19use crate::expr::BoundExpression;
20use crate::expr::Expression;
21use crate::expr::Lambda;
22use crate::scalar::Scalar;
23use crate::scalar::ScalarValue;
24use crate::scalar_fn::EmptyOptions;
25use crate::scalar_fn::ScalarFnVTableExt;
26use crate::scalar_fn::fns::between::Between;
27use crate::scalar_fn::fns::between::BetweenOptions;
28use crate::scalar_fn::fns::between::StrictComparison;
29use crate::scalar_fn::fns::binary::Binary;
30use crate::scalar_fn::fns::byte_length::ByteLength;
31use crate::scalar_fn::fns::case_when::CaseWhen;
32use crate::scalar_fn::fns::case_when::CaseWhenOptions;
33use crate::scalar_fn::fns::cast::Cast;
34use crate::scalar_fn::fns::dynamic::DynamicComparison;
35use crate::scalar_fn::fns::dynamic::DynamicComparisonExpr;
36use crate::scalar_fn::fns::dynamic::Rhs;
37use crate::scalar_fn::fns::dynamic_expression::DynamicExpression;
38use crate::scalar_fn::fns::dynamic_expression::DynamicExpressionOptions;
39use crate::scalar_fn::fns::dynamic_expression::DynamicExpressionSource;
40use crate::scalar_fn::fns::ext_storage::ExtStorage;
41use crate::scalar_fn::fns::fill_null::FillNull;
42use crate::scalar_fn::fns::get_item::GetItem;
43use crate::scalar_fn::fns::is_nan::IsNan;
44use crate::scalar_fn::fns::is_not_null::IsNotNull;
45use crate::scalar_fn::fns::is_null::IsNull;
46use crate::scalar_fn::fns::like::Like;
47use crate::scalar_fn::fns::like::LikeOptions;
48use crate::scalar_fn::fns::list_contains::ListContains;
49use crate::scalar_fn::fns::list_contains::ListContainsOptions;
50use crate::scalar_fn::fns::list_length::ListLength;
51use crate::scalar_fn::fns::list_sum::ListSum;
52use crate::scalar_fn::fns::list_transform::ListTransform;
53use crate::scalar_fn::fns::list_transform::ListTransformOptions;
54use crate::scalar_fn::fns::literal::Literal;
55use crate::scalar_fn::fns::mask::Mask;
56use crate::scalar_fn::fns::merge::DuplicateHandling;
57use crate::scalar_fn::fns::merge::Merge;
58use crate::scalar_fn::fns::not::Not;
59use crate::scalar_fn::fns::operators::CompareOperator;
60use crate::scalar_fn::fns::operators::Operator;
61use crate::scalar_fn::fns::pack::Pack;
62use crate::scalar_fn::fns::pack::PackOptions;
63use crate::scalar_fn::fns::replace_time_zone::ReplaceTimeZone;
64use crate::scalar_fn::fns::replace_time_zone::ReplaceTimeZoneOptions;
65use crate::scalar_fn::fns::select::FieldSelection;
66use crate::scalar_fn::fns::select::Select;
67use crate::scalar_fn::fns::variant_get::VariantGet;
68use crate::scalar_fn::fns::variant_get::VariantGetOptions;
69use crate::scalar_fn::fns::variant_get::VariantPath;
70use crate::scalar_fn::fns::zip::Zip;
71
72/// Creates an expression that references the root scope.
73///
74/// Returns the entire input array as passed to the expression evaluator.
75/// This is commonly used as the starting point for field access and other operations.
76pub fn root() -> Expression {
77    Expression::Root
78}
79
80/// Creates a bound expression that references a root scope with the given dtype.
81pub fn bound_root(dtype: DType) -> BoundExpression {
82    BoundExpression::new_root(dtype)
83}
84
85/// Return whether the expression is a root expression.
86pub fn is_root(expr: &Expression) -> bool {
87    expr.is_root()
88}
89
90// ---- Literal ----
91
92/// Create a new `Literal` expression from a type that coerces to `Scalar`.
93///
94///
95/// ## Example usage
96///
97/// ```
98/// use vortex_array::arrays::PrimitiveArray;
99/// use vortex_array::dtype::Nullability;
100/// use vortex_array::expr::lit;
101/// use vortex_array::scalar_fn::fns::literal::Literal;
102/// use vortex_array::scalar::Scalar;
103///
104/// let number = lit(34i32);
105///
106/// let scalar = number.as_::<Literal>();
107/// assert_eq!(scalar, &Scalar::primitive(34i32, Nullability::NonNullable));
108/// ```
109pub fn lit(value: impl Into<Scalar>) -> Expression {
110    Literal.new_expr(value.into(), [])
111}
112
113/// Creates a bound literal expression.
114pub fn bound_lit(value: impl Into<Scalar>) -> BoundExpression {
115    Literal
116        .try_new_bound_expr(value.into(), [])
117        .vortex_expect("literal expressions are always well-typed")
118}
119
120// ---- GetItem / Col ----
121
122/// Creates an expression that accesses a field from the root array.
123///
124/// Equivalent to `get_item(field, root())` - extracts a named field from the input array.
125///
126/// ```rust
127/// # use vortex_array::expr::col;
128/// let expr = col("name");
129/// ```
130pub fn col(field: impl Into<FieldName>) -> Expression {
131    GetItem.new_expr(field.into(), vec![root()])
132}
133
134/// Creates a bound expression that accesses a field from a root scope with the given dtype.
135pub fn bound_col(field: impl Into<FieldName>, scope: DType) -> BoundExpression {
136    bound_get_item(field, bound_root(scope))
137}
138
139/// Creates an expression that extracts a named field from a struct expression.
140///
141/// Accesses the specified field from the result of the child expression.
142///
143/// ```rust
144/// # use vortex_array::expr::{get_item, root};
145/// let expr = get_item("user_id", root());
146/// ```
147pub fn get_item(field: impl Into<FieldName>, child: Expression) -> Expression {
148    GetItem.new_expr(field.into(), vec![child])
149}
150
151/// Creates a bound expression that extracts a named field from a struct expression.
152pub fn bound_get_item(field: impl Into<FieldName>, child: BoundExpression) -> BoundExpression {
153    GetItem
154        .try_new_bound_expr(field.into(), [child])
155        .vortex_expect("get-item expressions must reference a field in the child dtype")
156}
157
158// ---- Variable ----
159
160/// Creates an expression that reads the parameter `name` of the enclosing lambda.
161///
162/// It is only meaningful in the body of a [`Lambda`]. Anywhere else it fails to bind.
163///
164/// ```rust
165/// # use vortex_array::dtype::{DType, Nullability, PType};
166/// # use vortex_array::expr::{checked_add, lit, var};
167/// let expr = checked_add(var("x"), lit(1_i32));
168/// assert_eq!(expr.to_string(), "(@x + 1i32)");
169/// // Outside a lambda body, nothing gives `x` a value.
170/// assert!(expr.bind(&DType::Primitive(PType::I32, Nullability::NonNullable)).is_err());
171/// ```
172pub fn var(name: impl Into<FieldName>) -> Expression {
173    Expression::Variable(name.into())
174}
175
176// ---- VariantGet ----
177
178/// Creates an expression that extracts a path from a Variant expression.
179///
180/// Missing paths, traversal mismatches, and failed casts return null. When `dtype` is `None`,
181/// results are nullable Variant values; otherwise results are nullable values of `dtype`.
182pub fn variant_get(
183    child: Expression,
184    path: impl Into<VariantPath>,
185    dtype: Option<DType>,
186) -> Expression {
187    VariantGet.new_expr(VariantGetOptions::new(path.into(), dtype), vec![child])
188}
189
190/// Creates a bound expression that extracts a path from a Variant expression.
191pub fn bound_variant_get(
192    child: BoundExpression,
193    path: impl Into<VariantPath>,
194    dtype: Option<DType>,
195) -> BoundExpression {
196    VariantGet
197        .try_new_bound_expr(VariantGetOptions::new(path.into(), dtype), [child])
198        .vortex_expect("variant-get expressions require a Variant child")
199}
200
201// ---- CaseWhen ----
202
203/// Creates a CASE WHEN expression with one WHEN/THEN pair and an ELSE value.
204pub fn case_when(
205    condition: Expression,
206    then_value: Expression,
207    else_value: Expression,
208) -> Expression {
209    let options = CaseWhenOptions {
210        num_when_then_pairs: 1,
211        has_else: true,
212    };
213    CaseWhen.new_expr(options, [condition, then_value, else_value])
214}
215
216/// Creates a bound CASE WHEN expression with one WHEN/THEN pair and an ELSE value.
217pub fn bound_case_when(
218    condition: BoundExpression,
219    then_value: BoundExpression,
220    else_value: BoundExpression,
221) -> BoundExpression {
222    let options = CaseWhenOptions {
223        num_when_then_pairs: 1,
224        has_else: true,
225    };
226    CaseWhen
227        .try_new_bound_expr(options, [condition, then_value, else_value])
228        .vortex_expect("case expressions must have boolean conditions and matching branch dtypes")
229}
230
231/// Creates a CASE WHEN expression with one WHEN/THEN pair and no ELSE value.
232pub fn case_when_no_else(condition: Expression, then_value: Expression) -> Expression {
233    let options = CaseWhenOptions {
234        num_when_then_pairs: 1,
235        has_else: false,
236    };
237    CaseWhen.new_expr(options, [condition, then_value])
238}
239
240/// Creates a bound CASE WHEN expression with one WHEN/THEN pair and no ELSE value.
241pub fn bound_case_when_no_else(
242    condition: BoundExpression,
243    then_value: BoundExpression,
244) -> BoundExpression {
245    let options = CaseWhenOptions {
246        num_when_then_pairs: 1,
247        has_else: false,
248    };
249    CaseWhen
250        .try_new_bound_expr(options, [condition, then_value])
251        .vortex_expect("case expressions must have boolean conditions")
252}
253
254/// Creates an n-ary CASE WHEN expression from WHEN/THEN pairs and an optional ELSE value.
255pub fn nested_case_when(
256    when_then_pairs: Vec<(Expression, Expression)>,
257    else_value: Option<Expression>,
258) -> Expression {
259    assert!(
260        !when_then_pairs.is_empty(),
261        "nested_case_when requires at least one when/then pair"
262    );
263
264    let has_else = else_value.is_some();
265    let mut children = Vec::with_capacity(when_then_pairs.len() * 2 + usize::from(has_else));
266    for (condition, then_value) in &when_then_pairs {
267        children.push(condition.clone());
268        children.push(then_value.clone());
269    }
270    if let Some(else_expr) = else_value {
271        children.push(else_expr);
272    }
273
274    let Ok(num_when_then_pairs) = u32::try_from(when_then_pairs.len()) else {
275        vortex_panic!("nested_case_when has too many when/then pairs");
276    };
277    let options = CaseWhenOptions {
278        num_when_then_pairs,
279        has_else,
280    };
281    CaseWhen.new_expr(options, children)
282}
283
284/// Creates a bound n-ary CASE WHEN expression from WHEN/THEN pairs and an optional ELSE value.
285pub fn bound_nested_case_when(
286    when_then_pairs: Vec<(BoundExpression, BoundExpression)>,
287    else_value: Option<BoundExpression>,
288) -> BoundExpression {
289    assert!(
290        !when_then_pairs.is_empty(),
291        "nested_case_when requires at least one when/then pair"
292    );
293
294    let Ok(num_when_then_pairs) = u32::try_from(when_then_pairs.len()) else {
295        vortex_panic!("nested_case_when has too many when/then pairs");
296    };
297    let has_else = else_value.is_some();
298    let mut children = Vec::with_capacity(when_then_pairs.len() * 2 + usize::from(has_else));
299    for (condition, then_value) in when_then_pairs {
300        children.push(condition);
301        children.push(then_value);
302    }
303    if let Some(else_expr) = else_value {
304        children.push(else_expr);
305    }
306
307    let options = CaseWhenOptions {
308        num_when_then_pairs,
309        has_else,
310    };
311    CaseWhen
312        .try_new_bound_expr(options, children)
313        .vortex_expect("case expressions must have boolean conditions and matching branch dtypes")
314}
315
316// ---- Binary operators ----
317
318/// Creates a binary expression with the given operator.
319pub fn binary(operator: Operator, lhs: Expression, rhs: Expression) -> Expression {
320    Binary
321        .try_new_expr(operator, [lhs, rhs])
322        .vortex_expect("Failed to create binary expression")
323}
324
325/// Creates a bound binary expression with the given operator.
326pub fn bound_binary(
327    operator: Operator,
328    lhs: BoundExpression,
329    rhs: BoundExpression,
330) -> BoundExpression {
331    Binary
332        .try_new_bound_expr(operator, [lhs, rhs])
333        .vortex_expect("binary expressions must have compatible operand dtypes")
334}
335
336/// Create a new [`Binary`] using the [`Eq`](Operator::Eq) operator.
337///
338/// ## Example usage
339///
340/// ```
341/// # use vortex_array::arrays::{BoolArray, PrimitiveArray};
342/// # use vortex_array::arrays::bool::BoolArrayExt;
343/// # use vortex_array::IntoArray;
344/// # use vortex_array::{VortexSessionExecute};
345/// # use vortex_session::VortexSession;
346/// # use vortex_array::validity::Validity;
347/// # use vortex_buffer::buffer;
348/// # use vortex_array::expr::{eq, root, lit};
349/// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
350/// let result = xs.into_array().apply(&eq(root(), lit(3))).unwrap();
351/// let mut ctx = VortexSession::empty().create_execution_ctx();
352///
353/// assert_eq!(
354///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
355///     BoolArray::from_iter(vec![false, false, true]).to_bit_buffer(),
356/// );
357/// ```
358pub fn eq(lhs: Expression, rhs: Expression) -> Expression {
359    Binary
360        .try_new_expr(Operator::Eq, [lhs, rhs])
361        .vortex_expect("Failed to create Eq binary expression")
362}
363
364/// Creates a bound equality expression.
365pub fn bound_eq(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
366    bound_binary(Operator::Eq, lhs, rhs)
367}
368
369/// Create a new [`Binary`] using the [`NotEq`](Operator::NotEq) operator.
370///
371/// ## Example usage
372///
373/// ```
374/// # use vortex_array::arrays::{BoolArray, PrimitiveArray};
375/// # use vortex_array::arrays::bool::BoolArrayExt;
376/// # use vortex_array::IntoArray;
377/// # use vortex_array::{VortexSessionExecute};
378/// # use vortex_session::VortexSession;
379/// # use vortex_array::validity::Validity;
380/// # use vortex_buffer::buffer;
381/// # use vortex_array::expr::{root, lit, not_eq};
382/// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
383/// let result = xs.into_array().apply(&not_eq(root(), lit(3))).unwrap();
384/// let mut ctx = VortexSession::empty().create_execution_ctx();
385///
386/// assert_eq!(
387///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
388///     BoolArray::from_iter(vec![true, true, false]).to_bit_buffer(),
389/// );
390/// ```
391pub fn not_eq(lhs: Expression, rhs: Expression) -> Expression {
392    Binary
393        .try_new_expr(Operator::NotEq, [lhs, rhs])
394        .vortex_expect("Failed to create NotEq binary expression")
395}
396
397/// Creates a bound inequality expression.
398pub fn bound_not_eq(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
399    bound_binary(Operator::NotEq, lhs, rhs)
400}
401
402/// Create a new [`Binary`] using the [`Gte`](Operator::Gte) operator.
403///
404/// ## Example usage
405///
406/// ```
407/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
408/// # use vortex_array::arrays::bool::BoolArrayExt;
409/// # use vortex_array::IntoArray;
410/// # use vortex_array::{VortexSessionExecute};
411/// # use vortex_session::VortexSession;
412/// # use vortex_array::validity::Validity;
413/// # use vortex_buffer::buffer;
414/// # use vortex_array::expr::{gt_eq, root, lit};
415/// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
416/// let result = xs.into_array().apply(&gt_eq(root(), lit(3))).unwrap();
417/// let mut ctx = VortexSession::empty().create_execution_ctx();
418///
419/// assert_eq!(
420///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
421///     BoolArray::from_iter(vec![false, false, true]).to_bit_buffer(),
422/// );
423/// ```
424pub fn gt_eq(lhs: Expression, rhs: Expression) -> Expression {
425    Binary
426        .try_new_expr(Operator::Gte, [lhs, rhs])
427        .vortex_expect("Failed to create Gte binary expression")
428}
429
430/// Creates a bound greater-than-or-equal expression.
431pub fn bound_gt_eq(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
432    bound_binary(Operator::Gte, lhs, rhs)
433}
434
435/// Create a new [`Binary`] using the [`Gt`](Operator::Gt) operator.
436///
437/// ## Example usage
438///
439/// ```
440/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
441/// # use vortex_array::arrays::bool::BoolArrayExt;
442/// # use vortex_array::IntoArray;
443/// # use vortex_array::{VortexSessionExecute};
444/// # use vortex_session::VortexSession;
445/// # use vortex_array::validity::Validity;
446/// # use vortex_buffer::buffer;
447/// # use vortex_array::expr::{gt, root, lit};
448/// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
449/// let result = xs.into_array().apply(&gt(root(), lit(2))).unwrap();
450/// let mut ctx = VortexSession::empty().create_execution_ctx();
451///
452/// assert_eq!(
453///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
454///     BoolArray::from_iter(vec![false, false, true]).to_bit_buffer(),
455/// );
456/// ```
457pub fn gt(lhs: Expression, rhs: Expression) -> Expression {
458    Binary
459        .try_new_expr(Operator::Gt, [lhs, rhs])
460        .vortex_expect("Failed to create Gt binary expression")
461}
462
463/// Creates a bound greater-than expression.
464pub fn bound_gt(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
465    bound_binary(Operator::Gt, lhs, rhs)
466}
467
468/// Create a new [`Binary`] using the [`Lte`](Operator::Lte) operator.
469///
470/// ## Example usage
471///
472/// ```
473/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
474/// # use vortex_array::arrays::bool::BoolArrayExt;
475/// # use vortex_array::IntoArray;
476/// # use vortex_array::{VortexSessionExecute};
477/// # use vortex_session::VortexSession;
478/// # use vortex_array::validity::Validity;
479/// # use vortex_buffer::buffer;
480/// # use vortex_array::expr::{root, lit, lt_eq};
481/// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
482/// let result = xs.into_array().apply(&lt_eq(root(), lit(2))).unwrap();
483/// let mut ctx = VortexSession::empty().create_execution_ctx();
484///
485/// assert_eq!(
486///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
487///     BoolArray::from_iter(vec![true, true, false]).to_bit_buffer(),
488/// );
489/// ```
490pub fn lt_eq(lhs: Expression, rhs: Expression) -> Expression {
491    Binary
492        .try_new_expr(Operator::Lte, [lhs, rhs])
493        .vortex_expect("Failed to create Lte binary expression")
494}
495
496/// Creates a bound less-than-or-equal expression.
497pub fn bound_lt_eq(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
498    bound_binary(Operator::Lte, lhs, rhs)
499}
500
501/// Create a new [`Binary`] using the [`Lt`](Operator::Lt) operator.
502///
503/// ## Example usage
504///
505/// ```
506/// # use vortex_array::arrays::{BoolArray, PrimitiveArray };
507/// # use vortex_array::arrays::bool::BoolArrayExt;
508/// # use vortex_array::IntoArray;
509/// # use vortex_array::{VortexSessionExecute};
510/// # use vortex_session::VortexSession;
511/// # use vortex_array::validity::Validity;
512/// # use vortex_buffer::buffer;
513/// # use vortex_array::expr::{root, lit, lt};
514/// let xs = PrimitiveArray::new(buffer![1i32, 2i32, 3i32], Validity::NonNullable);
515/// let result = xs.into_array().apply(&lt(root(), lit(3))).unwrap();
516/// let mut ctx = VortexSession::empty().create_execution_ctx();
517///
518/// assert_eq!(
519///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
520///     BoolArray::from_iter(vec![true, true, false]).to_bit_buffer(),
521/// );
522/// ```
523pub fn lt(lhs: Expression, rhs: Expression) -> Expression {
524    Binary
525        .try_new_expr(Operator::Lt, [lhs, rhs])
526        .vortex_expect("Failed to create Lt binary expression")
527}
528
529/// Creates a bound less-than expression.
530pub fn bound_lt(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
531    bound_binary(Operator::Lt, lhs, rhs)
532}
533
534/// Create a new [`Binary`] using the [`Or`](Operator::Or) operator.
535///
536/// ## Example usage
537///
538/// ```
539/// # use vortex_array::arrays::BoolArray;
540/// # use vortex_array::arrays::bool::BoolArrayExt;
541/// # use vortex_array::IntoArray;
542/// # use vortex_array::{VortexSessionExecute};
543/// # use vortex_session::VortexSession;
544/// # use vortex_array::expr::{root, lit, or};
545/// let xs = BoolArray::from_iter(vec![true, false, true]);
546/// let result = xs.into_array().apply(&or(root(), lit(false))).unwrap();
547/// let mut ctx = VortexSession::empty().create_execution_ctx();
548///
549/// assert_eq!(
550///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
551///     BoolArray::from_iter(vec![true, false, true]).to_bit_buffer(),
552/// );
553/// ```
554pub fn or(lhs: Expression, rhs: Expression) -> Expression {
555    Binary
556        .try_new_expr(Operator::Or, [lhs, rhs])
557        .vortex_expect("Failed to create Or binary expression")
558}
559
560/// Creates a bound boolean OR expression.
561pub fn bound_or(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
562    bound_binary(Operator::Or, lhs, rhs)
563}
564
565/// Collects a list of `or`ed values into a single expression using a balanced tree.
566///
567/// This creates a balanced binary tree to avoid deep nesting that could cause
568/// stack overflow during drop or evaluation.
569///
570/// [a, b, c, d] => or(or(a, b), or(c, d))
571pub fn or_collect<I>(iter: I) -> Option<Expression>
572where
573    I: IntoIterator<Item = Expression>,
574{
575    iter.into_iter().reduce_balanced(or)
576}
577
578/// Collects bound expressions into a balanced tree of boolean OR expressions.
579pub fn bound_or_collect<I>(iter: I) -> Option<BoundExpression>
580where
581    I: IntoIterator<Item = BoundExpression>,
582{
583    iter.into_iter().reduce_balanced(bound_or)
584}
585
586/// Create a new [`Binary`] using the [`And`](Operator::And) operator.
587///
588/// ## Example usage
589///
590/// ```
591/// # use vortex_array::arrays::BoolArray;
592/// # use vortex_array::arrays::bool::BoolArrayExt;
593/// # use vortex_array::IntoArray;
594/// # use vortex_array::{VortexSessionExecute};
595/// # use vortex_session::VortexSession;
596/// # use vortex_array::expr::{and, root, lit};
597/// let xs = BoolArray::from_iter(vec![true, false, true]).into_array();
598/// let result = xs.apply(&and(root(), lit(true))).unwrap();
599/// let mut ctx = VortexSession::empty().create_execution_ctx();
600///
601/// assert_eq!(
602///     result.execute::<BoolArray>(&mut ctx).unwrap().to_bit_buffer(),
603///     BoolArray::from_iter(vec![true, false, true]).to_bit_buffer(),
604/// );
605/// ```
606pub fn and(lhs: Expression, rhs: Expression) -> Expression {
607    Binary
608        .try_new_expr(Operator::And, [lhs, rhs])
609        .vortex_expect("Failed to create And binary expression")
610}
611
612/// Creates a bound boolean AND expression.
613pub fn bound_and(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
614    bound_binary(Operator::And, lhs, rhs)
615}
616
617/// Collects a list of `and`ed values into a single expression using a balanced tree.
618///
619/// This creates a balanced binary tree to avoid deep nesting that could cause
620/// stack overflow during drop or evaluation.
621///
622/// [a, b, c, d] => and(and(a, b), and(c, d))
623pub fn and_collect<I>(iter: I) -> Option<Expression>
624where
625    I: IntoIterator<Item = Expression>,
626{
627    iter.into_iter().reduce_balanced(and)
628}
629
630/// Collects bound expressions into a balanced tree of boolean AND expressions.
631pub fn bound_and_collect<I>(iter: I) -> Option<BoundExpression>
632where
633    I: IntoIterator<Item = BoundExpression>,
634{
635    iter.into_iter().reduce_balanced(bound_and)
636}
637
638/// Create a new [`Binary`] using the [`Add`](Operator::Add) operator.
639///
640/// ## Example usage
641///
642/// ```
643/// # use vortex_array::IntoArray;
644/// # use vortex_array::arrays::PrimitiveArray;
645/// # use vortex_array::builtins::ArrayBuiltins;
646/// # use vortex_array::{VortexSessionExecute};
647/// # use vortex_session::VortexSession;
648/// # use vortex_buffer::buffer;
649/// # use vortex_array::expr::{checked_add, lit, root};
650/// let xs = buffer![1, 2, 3].into_array();
651/// let result = xs.apply(&checked_add(root(), lit(5))).unwrap();
652///
653/// let mut ctx = VortexSession::empty().create_execution_ctx();
654/// let result = result.execute::<PrimitiveArray>(&mut ctx).unwrap();
655/// assert_eq!(result.as_slice::<i32>(), [6, 7, 8]);
656/// ```
657pub fn checked_add(lhs: Expression, rhs: Expression) -> Expression {
658    Binary
659        .try_new_expr(Operator::Add, [lhs, rhs])
660        .vortex_expect("Failed to create Add binary expression")
661}
662
663/// Creates a bound checked-add expression.
664pub fn bound_checked_add(lhs: BoundExpression, rhs: BoundExpression) -> BoundExpression {
665    bound_binary(Operator::Add, lhs, rhs)
666}
667
668// ---- Not ----
669
670/// Creates an expression that logically inverts boolean values.
671///
672/// Returns the logical negation of the input boolean expression.
673///
674/// ```rust
675/// # use vortex_array::expr::{not, root};
676/// let expr = not(root());
677/// ```
678pub fn not(operand: Expression) -> Expression {
679    Not.new_expr(EmptyOptions, vec![operand])
680}
681
682/// Creates a bound expression that logically inverts boolean values.
683pub fn bound_not(operand: BoundExpression) -> BoundExpression {
684    Not.try_new_bound_expr(EmptyOptions, [operand])
685        .vortex_expect("not expressions require a boolean operand")
686}
687
688// ---- Between ----
689
690/// Creates an expression that checks if values are between two bounds.
691///
692/// Returns a boolean array indicating which values fall within the specified range.
693/// The comparison strictness is controlled by the options parameter.
694///
695/// ```rust
696/// # use vortex_array::scalar_fn::fns::between::BetweenOptions;
697/// # use vortex_array::scalar_fn::fns::between::StrictComparison;
698/// # use vortex_array::expr::{between, lit, root};
699/// let opts = BetweenOptions {
700///     lower_strict: StrictComparison::NonStrict,
701///     upper_strict: StrictComparison::NonStrict,
702/// };
703/// let expr = between(root(), lit(10), lit(20), opts);
704/// ```
705pub fn between(
706    arr: Expression,
707    lower: Expression,
708    upper: Expression,
709    options: BetweenOptions,
710) -> Expression {
711    Between
712        .try_new_expr(options, [arr, lower, upper])
713        .vortex_expect("Failed to create Between expression")
714}
715
716/// Creates a bound expression that checks if values are between two bounds.
717pub fn bound_between(
718    arr: BoundExpression,
719    lower: BoundExpression,
720    upper: BoundExpression,
721    options: BetweenOptions,
722) -> BoundExpression {
723    Between
724        .try_new_bound_expr(options, [arr, lower, upper])
725        .vortex_expect("between expressions require compatible operand dtypes")
726}
727
728// ---- Select ----
729
730/// Creates an expression that selects (includes) specific fields from an array.
731///
732/// Projects only the specified fields from the child expression, which must be of DType struct.
733/// ```rust
734/// # use vortex_array::expr::{select, root};
735/// let expr = select(["name", "age"], root());
736/// ```
737pub fn select(field_names: impl Into<FieldNames>, child: Expression) -> Expression {
738    Select
739        .try_new_expr(FieldSelection::Include(field_names.into()), [child])
740        .vortex_expect("Failed to create Select expression")
741}
742
743/// Creates a bound expression that selects specific fields from a struct expression.
744pub fn bound_select(field_names: impl Into<FieldNames>, child: BoundExpression) -> BoundExpression {
745    Select
746        .try_new_bound_expr(FieldSelection::Include(field_names.into()), [child])
747        .vortex_expect("select expressions require fields from a struct child")
748}
749
750/// Creates an expression that excludes specific fields from an array.
751///
752/// Projects all fields except the specified ones from the input struct expression.
753///
754/// ```rust
755/// # use vortex_array::expr::{select_exclude, root};
756/// let expr = select_exclude(["internal_id", "metadata"], root());
757/// ```
758pub fn select_exclude(fields: impl Into<FieldNames>, child: Expression) -> Expression {
759    Select
760        .try_new_expr(FieldSelection::Exclude(fields.into()), [child])
761        .vortex_expect("Failed to create Select expression")
762}
763
764/// Creates a bound expression that excludes specific fields from a struct expression.
765pub fn bound_select_exclude(
766    fields: impl Into<FieldNames>,
767    child: BoundExpression,
768) -> BoundExpression {
769    Select
770        .try_new_bound_expr(FieldSelection::Exclude(fields.into()), [child])
771        .vortex_expect("select expressions require fields from a struct child")
772}
773
774// ---- Pack ----
775
776/// Creates an expression that packs values into a struct with named fields.
777///
778/// ```rust
779/// # use vortex_array::dtype::Nullability;
780/// # use vortex_array::expr::{pack, col, lit};
781/// let expr = pack([("id", col("user_id")), ("constant", lit(42))], Nullability::NonNullable);
782/// ```
783pub fn pack(
784    elements: impl IntoIterator<Item = (impl Into<FieldName>, Expression)>,
785    nullability: Nullability,
786) -> Expression {
787    let (names, values): (Vec<_>, Vec<_>) = elements
788        .into_iter()
789        .map(|(name, value)| (name.into(), value))
790        .unzip();
791    Pack.new_expr(
792        PackOptions {
793            names: names.into(),
794            nullability,
795        },
796        values,
797    )
798}
799
800/// Creates a bound expression that packs values into a struct with named fields.
801pub fn bound_pack(
802    elements: impl IntoIterator<Item = (impl Into<FieldName>, BoundExpression)>,
803    nullability: Nullability,
804) -> BoundExpression {
805    let (names, values): (Vec<_>, Vec<_>) = elements
806        .into_iter()
807        .map(|(name, value)| (name.into(), value))
808        .unzip();
809    Pack.try_new_bound_expr(
810        PackOptions {
811            names: names.into(),
812            nullability,
813        },
814        values,
815    )
816    .vortex_expect("pack expressions must have one name per child")
817}
818
819// ---- Cast ----
820
821/// Creates an expression that casts values to a target data type.
822///
823/// Converts the input expression's values to the specified target type.
824///
825/// ```rust
826/// # use vortex_array::dtype::{DType, Nullability, PType};
827/// # use vortex_array::expr::{cast, root};
828/// let expr = cast(root(), DType::Primitive(PType::I64, Nullability::NonNullable));
829/// ```
830pub fn cast(child: Expression, target: DType) -> Expression {
831    Cast.try_new_expr(target, [child])
832        .vortex_expect("Failed to create Cast expression")
833}
834
835/// Creates a bound expression that casts values to a target dtype.
836pub fn bound_cast(child: BoundExpression, target: DType) -> BoundExpression {
837    Cast.try_new_bound_expr(target, [child])
838        .vortex_expect("cast expressions require a supported source and target dtype")
839}
840
841// ---- FillNull ----
842
843/// Creates an expression that replaces null values with a fill value.
844///
845/// ```rust
846/// # use vortex_array::expr::{fill_null, root, lit};
847/// let expr = fill_null(root(), lit(0i32));
848/// ```
849pub fn fill_null(child: Expression, fill_value: Expression) -> Expression {
850    FillNull.new_expr(EmptyOptions, [child, fill_value])
851}
852
853/// Creates a bound expression that replaces null values with a fill value.
854pub fn bound_fill_null(child: BoundExpression, fill_value: BoundExpression) -> BoundExpression {
855    FillNull
856        .try_new_bound_expr(EmptyOptions, [child, fill_value])
857        .vortex_expect("fill-null expressions require compatible child and fill dtypes")
858}
859
860// ---- IsNull ----
861
862/// Creates an expression that checks for null values.
863///
864/// Returns a boolean array indicating which positions contain null values.
865///
866/// ```rust
867/// # use vortex_array::expr::{is_null, root};
868/// let expr = is_null(root());
869/// ```
870pub fn is_null(child: Expression) -> Expression {
871    IsNull.new_expr(EmptyOptions, vec![child])
872}
873
874/// Creates a bound expression that checks for null values.
875pub fn bound_is_null(child: BoundExpression) -> BoundExpression {
876    IsNull
877        .try_new_bound_expr(EmptyOptions, [child])
878        .vortex_expect("is-null expressions are always well-typed")
879}
880
881// ---- IsNan ----
882
883/// Creates an expression that checks for NaN values.
884///
885/// The expression is strict: null inputs produce null outputs, so the output nullability
886/// follows the input. Only primitive float inputs are supported.
887///
888/// ```rust
889/// # use vortex_array::expr::{is_nan, root};
890/// let expr = is_nan(root());
891/// ```
892pub fn is_nan(child: Expression) -> Expression {
893    IsNan.new_expr(EmptyOptions, vec![child])
894}
895
896/// Creates a bound expression that checks for NaN values.
897pub fn bound_is_nan(child: BoundExpression) -> BoundExpression {
898    IsNan
899        .try_new_bound_expr(EmptyOptions, [child])
900        .vortex_expect("is-nan expressions are always well-typed")
901}
902
903// ---- IsNotNull ----
904
905/// Creates an expression that checks for non-null values.
906///
907/// Returns a boolean array indicating which positions contain non-null values.
908///
909/// ```rust
910/// # use vortex_array::expr::{is_not_null, root};
911/// let expr = is_not_null(root());
912/// ```
913pub fn is_not_null(child: Expression) -> Expression {
914    IsNotNull.new_expr(EmptyOptions, vec![child])
915}
916
917/// Creates a bound expression that checks for non-null values.
918pub fn bound_is_not_null(child: BoundExpression) -> BoundExpression {
919    IsNotNull
920        .try_new_bound_expr(EmptyOptions, [child])
921        .vortex_expect("is-not-null expressions are always well-typed")
922}
923
924// ---- Like ----
925
926/// Creates a SQL LIKE expression.
927pub fn like(child: Expression, pattern: Expression) -> Expression {
928    Like.new_expr(
929        LikeOptions {
930            negated: false,
931            case_insensitive: false,
932        },
933        [child, pattern],
934    )
935}
936
937/// Creates a bound SQL LIKE expression.
938pub fn bound_like(child: BoundExpression, pattern: BoundExpression) -> BoundExpression {
939    bound_like_with_options(child, pattern, false, false)
940}
941
942/// Creates a case-insensitive SQL ILIKE expression.
943pub fn ilike(child: Expression, pattern: Expression) -> Expression {
944    Like.new_expr(
945        LikeOptions {
946            negated: false,
947            case_insensitive: true,
948        },
949        [child, pattern],
950    )
951}
952
953/// Creates a bound case-insensitive SQL ILIKE expression.
954pub fn bound_ilike(child: BoundExpression, pattern: BoundExpression) -> BoundExpression {
955    bound_like_with_options(child, pattern, false, true)
956}
957
958/// Creates a negated SQL NOT LIKE expression.
959pub fn not_like(child: Expression, pattern: Expression) -> Expression {
960    Like.new_expr(
961        LikeOptions {
962            negated: true,
963            case_insensitive: false,
964        },
965        [child, pattern],
966    )
967}
968
969/// Creates a bound negated SQL NOT LIKE expression.
970pub fn bound_not_like(child: BoundExpression, pattern: BoundExpression) -> BoundExpression {
971    bound_like_with_options(child, pattern, true, false)
972}
973
974/// Creates a negated case-insensitive SQL NOT ILIKE expression.
975pub fn not_ilike(child: Expression, pattern: Expression) -> Expression {
976    Like.new_expr(
977        LikeOptions {
978            negated: true,
979            case_insensitive: true,
980        },
981        [child, pattern],
982    )
983}
984
985/// Creates a bound negated case-insensitive SQL NOT ILIKE expression.
986pub fn bound_not_ilike(child: BoundExpression, pattern: BoundExpression) -> BoundExpression {
987    bound_like_with_options(child, pattern, true, true)
988}
989
990fn bound_like_with_options(
991    child: BoundExpression,
992    pattern: BoundExpression,
993    negated: bool,
994    case_insensitive: bool,
995) -> BoundExpression {
996    Like.try_new_bound_expr(
997        LikeOptions {
998            negated,
999            case_insensitive,
1000        },
1001        [child, pattern],
1002    )
1003    .vortex_expect("like expressions require UTF-8 or binary operands")
1004}
1005
1006// ---- Mask ----
1007
1008/// Creates a mask expression that applies the given boolean mask to the input array.
1009pub fn mask(array: Expression, mask: Expression) -> Expression {
1010    Mask.new_expr(EmptyOptions, [array, mask])
1011}
1012
1013/// Creates a bound mask expression.
1014pub fn bound_mask(array: BoundExpression, mask: BoundExpression) -> BoundExpression {
1015    Mask.try_new_bound_expr(EmptyOptions, [array, mask])
1016        .vortex_expect("mask expressions require a boolean mask")
1017}
1018
1019// ---- Merge ----
1020
1021/// Creates an expression that merges struct expressions into a single struct.
1022///
1023/// Combines fields from all input expressions. If field names are duplicated,
1024/// later expressions win. Fields are not recursively merged.
1025///
1026/// ```rust
1027/// # use vortex_array::dtype::Nullability;
1028/// # use vortex_array::expr::{merge, get_item, root};
1029/// let expr = merge([get_item("a", root()), get_item("b", root())]);
1030/// ```
1031pub fn merge(elements: impl IntoIterator<Item = impl Into<Expression>>) -> Expression {
1032    use itertools::Itertools as _;
1033    let values = elements.into_iter().map(|value| value.into()).collect_vec();
1034    Merge.new_expr(DuplicateHandling::default(), values)
1035}
1036
1037/// Creates a bound expression that merges struct expressions.
1038pub fn bound_merge(elements: impl IntoIterator<Item = BoundExpression>) -> BoundExpression {
1039    bound_merge_opts(elements, DuplicateHandling::default())
1040}
1041
1042/// Creates a merge expression with explicit duplicate handling.
1043pub fn merge_opts(
1044    elements: impl IntoIterator<Item = impl Into<Expression>>,
1045    duplicate_handling: DuplicateHandling,
1046) -> Expression {
1047    use itertools::Itertools as _;
1048    let values = elements.into_iter().map(|value| value.into()).collect_vec();
1049    Merge.new_expr(duplicate_handling, values)
1050}
1051
1052/// Creates a bound merge expression with explicit duplicate handling.
1053pub fn bound_merge_opts(
1054    elements: impl IntoIterator<Item = BoundExpression>,
1055    duplicate_handling: DuplicateHandling,
1056) -> BoundExpression {
1057    Merge
1058        .try_new_bound_expr(duplicate_handling, elements)
1059        .vortex_expect("merge expressions require non-nullable struct children")
1060}
1061
1062// ---- Zip ----
1063
1064/// Creates a zip expression that conditionally selects between two arrays.
1065///
1066/// ```rust
1067/// # use vortex_array::expr::{zip_expr, root, lit};
1068/// let expr = zip_expr(lit(true), root(), lit(0i32));
1069/// ```
1070pub fn zip_expr(mask: Expression, if_true: Expression, if_false: Expression) -> Expression {
1071    Zip.new_expr(EmptyOptions, [if_true, if_false, mask])
1072}
1073
1074/// Creates a bound zip expression that conditionally selects between two arrays.
1075pub fn bound_zip_expr(
1076    mask: BoundExpression,
1077    if_true: BoundExpression,
1078    if_false: BoundExpression,
1079) -> BoundExpression {
1080    Zip.try_new_bound_expr(EmptyOptions, [if_true, if_false, mask])
1081        .vortex_expect("zip expressions require a boolean mask and compatible value dtypes")
1082}
1083
1084// ---- Dynamic ----
1085
1086/// Creates a dynamic comparison expression from its complete options.
1087pub fn dynamic_with_options(options: DynamicComparisonExpr, lhs: Expression) -> Expression {
1088    DynamicComparison.new_expr(options, [lhs])
1089}
1090
1091/// Creates a bound dynamic comparison expression from its complete options.
1092pub fn bound_dynamic_with_options(
1093    options: DynamicComparisonExpr,
1094    lhs: BoundExpression,
1095) -> BoundExpression {
1096    DynamicComparison
1097        .try_new_bound_expr(options, [lhs])
1098        .vortex_expect("dynamic comparisons require a compatible left-hand dtype")
1099}
1100
1101/// Creates a dynamic comparison expression.
1102pub fn dynamic(
1103    operator: CompareOperator,
1104    rhs_value: impl Fn() -> Option<ScalarValue> + Send + Sync + 'static,
1105    rhs_dtype: DType,
1106    default: bool,
1107    lhs: Expression,
1108) -> Expression {
1109    dynamic_with_options(
1110        DynamicComparisonExpr {
1111            operator,
1112            rhs: Arc::new(Rhs {
1113                value: Arc::new(rhs_value),
1114                dtype: rhs_dtype,
1115            }),
1116            default,
1117        },
1118        lhs,
1119    )
1120}
1121
1122/// Creates a bound dynamic comparison expression.
1123pub fn bound_dynamic(
1124    operator: CompareOperator,
1125    rhs_value: impl Fn() -> Option<ScalarValue> + Send + Sync + 'static,
1126    rhs_dtype: DType,
1127    default: bool,
1128    lhs: BoundExpression,
1129) -> BoundExpression {
1130    bound_dynamic_with_options(
1131        DynamicComparisonExpr {
1132            operator,
1133            rhs: Arc::new(Rhs {
1134                value: Arc::new(rhs_value),
1135                dtype: rhs_dtype,
1136            }),
1137            default,
1138        },
1139        lhs,
1140    )
1141}
1142
1143/// Creates a dynamic expression that evaluates the current predicate of `source`.
1144///
1145/// The `inputs` are the expressions that every predicate of the source can read. A predicate
1146/// reads input `i` as the field named by
1147/// [`input_field_name(i)`](crate::scalar_fn::fns::dynamic_expression::input_field_name) of its
1148/// scope.
1149pub fn dynamic_expression(
1150    source: Arc<dyn DynamicExpressionSource>,
1151    inputs: impl IntoIterator<Item = Expression>,
1152) -> Expression {
1153    DynamicExpression.new_expr(DynamicExpressionOptions::new(source), inputs)
1154}
1155
1156/// Creates a bound dynamic expression that evaluates the current predicate of `source`.
1157pub fn bound_dynamic_expression(
1158    source: Arc<dyn DynamicExpressionSource>,
1159    inputs: impl IntoIterator<Item = BoundExpression>,
1160) -> BoundExpression {
1161    DynamicExpression
1162        .try_new_bound_expr(DynamicExpressionOptions::new(source), inputs)
1163        .vortex_expect("dynamic expressions accept any inputs")
1164}
1165
1166// ---- ListContains ----
1167
1168/// Creates an expression that checks whether a list contains a value.
1169///
1170/// A null element never matches anything: a needle that matches no element yields `false`. For
1171/// SQL's three-valued `IN`, where a null element makes that `null`, use [`in_list`].
1172///
1173/// ```rust
1174/// # use vortex_array::expr::{list_contains, lit, root};
1175/// let expr = list_contains(root(), lit(42));
1176/// ```
1177pub fn list_contains(list: Expression, value: Expression) -> Expression {
1178    list_contains_opts(list, value, ListContainsOptions::default())
1179}
1180
1181/// Creates an expression that checks whether a list contains a value, with explicit
1182/// [`ListContainsOptions`].
1183pub fn list_contains_opts(
1184    list: Expression,
1185    value: Expression,
1186    options: ListContainsOptions,
1187) -> Expression {
1188    ListContains.new_expr(options, [list, value])
1189}
1190
1191/// Creates `needle IN (list)` with SQL null semantics: a null element is an unknown value, so a
1192/// needle that matches no element yields `null` rather than `false` when the list holds one, and
1193/// `not(in_list(..))` never admits such a row.
1194///
1195/// ```rust
1196/// # use vortex_array::expr::{in_list, lit, root};
1197/// let expr = in_list(root(), lit(vec![1, 2, 3]));
1198/// ```
1199pub fn in_list(needle: Expression, list: Expression) -> Expression {
1200    list_contains_opts(
1201        list,
1202        needle,
1203        ListContainsOptions {
1204            sql_null_semantics: true,
1205        },
1206    )
1207}
1208
1209/// Creates `needle IN (elements)` with SQL null semantics for a list of constant elements of
1210/// `element_dtype`, ignoring nullability. An element can also be an untyped null.
1211///
1212/// The nullability of `element_dtype` is not used: the list elements are nullable only when a
1213/// null element is present.
1214///
1215/// Non-null integers that hold every value between their smallest and largest become a range
1216/// check, which is cheaper to evaluate and prunes with tighter bounds than a set lookup, as for
1217/// the keys of a small dimension table that a join pushes down.
1218///
1219/// # Errors
1220///
1221/// Returns an error if an element is not a null and not of `element_dtype`.
1222///
1223/// ```rust
1224/// # use vortex_array::dtype::{DType, Nullability, PType};
1225/// # use vortex_array::expr::{in_list_of, root};
1226/// let dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
1227/// let expr = in_list_of(root(), dtype, vec![3i32.into(), 1i32.into(), 2i32.into()])?;
1228/// assert_eq!(expr.to_string(), "(1i32 <= $ <= 3i32)");
1229/// # Ok::<(), vortex_error::VortexError>(())
1230/// ```
1231pub fn in_list_of(
1232    needle: Expression,
1233    element_dtype: DType,
1234    elements: Vec<Scalar>,
1235) -> VortexResult<Expression> {
1236    let element_dtype = if elements.iter().any(Scalar::is_null) {
1237        element_dtype.as_nullable()
1238    } else {
1239        element_dtype.as_nonnullable()
1240    };
1241    let mut elements = elements
1242        .iter()
1243        .map(|element| {
1244            vortex_ensure!(
1245                element.dtype() == &DType::Null
1246                    || element.dtype().eq_ignore_nullability(&element_dtype),
1247                "IN list element {element} is not of type {element_dtype}"
1248            );
1249            element.cast(&element_dtype)
1250        })
1251        .collect::<VortexResult<Vec<_>>>()?;
1252
1253    if let Some((low, high)) = contiguous_integer_bounds(&elements) {
1254        let options = BetweenOptions {
1255            lower_strict: StrictComparison::NonStrict,
1256            upper_strict: StrictComparison::NonStrict,
1257        };
1258        return Ok(between(
1259            needle,
1260            lit(low.clone()),
1261            lit(high.clone()),
1262            options,
1263        ));
1264    }
1265
1266    // Ordered elements make equal lists from the same set, so that equal filters deduplicate.
1267    // An engine can build a list from the keys of a hash join, which repeat, and each repeat makes
1268    // the lookup more costly, so equal elements are removed. One null keeps the SQL semantics.
1269    if elements
1270        .windows(2)
1271        .all(|pair| pair[0].partial_cmp(&pair[1]).is_some())
1272    {
1273        elements.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
1274        elements.dedup();
1275    }
1276    let list = Scalar::list(Arc::new(element_dtype), elements, Nullability::NonNullable);
1277    Ok(in_list(needle, lit(list)))
1278}
1279
1280/// The smallest and largest of non-null integer `scalars` when they hold every integer between
1281/// those two.
1282fn contiguous_integer_bounds(scalars: &[Scalar]) -> Option<(&Scalar, &Scalar)> {
1283    let mut values = scalars
1284        .iter()
1285        .map(|scalar| {
1286            // Viewing a scalar of another type as a primitive builds an error, which is costly.
1287            if !matches!(scalar.dtype(), DType::Primitive(ptype, _) if ptype.is_int()) {
1288                return None;
1289            }
1290            let primitive = scalar.as_primitive_opt()?;
1291            let value = if primitive.ptype().is_unsigned_int() {
1292                primitive.as_opt::<u64>()??.into()
1293            } else {
1294                i128::from(primitive.as_opt::<i64>()??)
1295            };
1296            Some((value, scalar))
1297        })
1298        .collect::<Option<Vec<(i128, &Scalar)>>>()?;
1299    values.sort_unstable_by_key(|(value, _)| *value);
1300    values.dedup_by_key(|(value, _)| *value);
1301    let (low, low_scalar) = values.first()?;
1302    let (high, high_scalar) = values.last()?;
1303    (high - low + 1 == i128::try_from(values.len()).ok()?).then_some((*low_scalar, *high_scalar))
1304}
1305
1306/// Creates a bound expression that checks whether a list contains a value.
1307pub fn bound_list_contains(list: BoundExpression, value: BoundExpression) -> BoundExpression {
1308    ListContains
1309        .try_new_bound_expr(ListContainsOptions::default(), [list, value])
1310        .vortex_expect("list-contains expressions require a list child")
1311}
1312
1313/// Creates a bound `needle IN (list)` with SQL null semantics. See [`in_list`].
1314pub fn bound_in_list(needle: BoundExpression, list: BoundExpression) -> BoundExpression {
1315    ListContains
1316        .try_new_bound_expr(
1317            ListContainsOptions {
1318                sql_null_semantics: true,
1319            },
1320            [list, needle],
1321        )
1322        .vortex_expect("list-contains expressions require a list child")
1323}
1324
1325// ---- ByteLength ----
1326
1327/// Creates an expression that computes the byte length of each element.
1328/// This is akin to ANSI SQL OCTET_LENGTH(), or DuckDB's strlen().
1329///
1330/// ```rust
1331/// # use vortex_array::expr::{byte_length, root};
1332/// let expr = byte_length(root());
1333/// ```
1334pub fn byte_length(input: Expression) -> Expression {
1335    ByteLength.new_expr(EmptyOptions, [input])
1336}
1337
1338/// Creates a bound expression that computes each element's byte length.
1339pub fn bound_byte_length(input: BoundExpression) -> BoundExpression {
1340    ByteLength
1341        .try_new_bound_expr(EmptyOptions, [input])
1342        .vortex_expect("byte-length expressions require a variable-length binary child")
1343}
1344
1345// ---- ExtStorage ----
1346
1347/// Creates an expression that extracts the storage values from an extension array.
1348///
1349/// ```rust
1350/// # use vortex_array::expr::{ext_storage, root};
1351/// let expr = ext_storage(root());
1352/// ```
1353pub fn ext_storage(input: Expression) -> Expression {
1354    ExtStorage.new_expr(EmptyOptions, [input])
1355}
1356
1357/// Creates a bound expression that extracts an extension array's storage values.
1358pub fn bound_ext_storage(input: BoundExpression) -> BoundExpression {
1359    ExtStorage
1360        .try_new_bound_expr(EmptyOptions, [input])
1361        .vortex_expect("extension-storage expressions require an extension child")
1362}
1363
1364// ---- ListLength ----
1365
1366/// Creates an expression that computes the number of elements in each list
1367/// for `List` and `FixedSizeList` inputs. This is akin to ANSI SQL `CARDINALITY()`,
1368/// or DuckDB's `len()`/`array_length()`.
1369///
1370/// ```rust
1371/// # use vortex_array::expr::{list_length, root};
1372/// let expr = list_length(root());
1373/// ```
1374pub fn list_length(input: Expression) -> Expression {
1375    ListLength.new_expr(EmptyOptions, [input])
1376}
1377
1378/// Creates a bound expression that computes the number of elements in each list.
1379pub fn bound_list_length(input: BoundExpression) -> BoundExpression {
1380    ListLength
1381        .try_new_bound_expr(EmptyOptions, [input])
1382        .vortex_expect("list-length expressions require a list child")
1383}
1384
1385// ---- ListSum ----
1386
1387/// Creates an expression that sums the elements of each list for `List` and
1388/// `FixedSizeList` inputs, akin to DuckDB's `list_sum()`.
1389///
1390/// Follows SQL `SUM` semantics per list: null lists, empty lists, and lists whose elements are
1391/// all null yield null; null elements are skipped; integer and decimal overflow yields a null
1392/// value. The result dtype follows `sum`'s widening rules and is always nullable. NaN float
1393/// elements are skipped by default; see [`list_sum_opts`] for the NaN-including variant.
1394///
1395/// ```rust
1396/// # use vortex_array::expr::{list_sum, root};
1397/// let expr = list_sum(root());
1398/// ```
1399pub fn list_sum(input: Expression) -> Expression {
1400    ListSum.new_expr(NumericalAggregateOpts::default(), [input])
1401}
1402
1403/// Creates a bound expression that sums the elements of each list.
1404pub fn bound_list_sum(input: BoundExpression) -> BoundExpression {
1405    ListSum
1406        .try_new_bound_expr(NumericalAggregateOpts::default(), [input])
1407        .vortex_expect("list-sum expressions require a numeric list child")
1408}
1409
1410/// Creates a [`list_sum`] expression with explicit [`NumericalAggregateOpts`], controlling
1411/// whether NaN float elements are skipped (the default) or poison the list's sum to NaN.
1412pub fn list_sum_opts(input: Expression, options: NumericalAggregateOpts) -> Expression {
1413    ListSum.new_expr(options, [input])
1414}
1415
1416/// Creates a bound list-sum expression with explicit aggregate options.
1417pub fn bound_list_sum_opts(
1418    input: BoundExpression,
1419    options: NumericalAggregateOpts,
1420) -> BoundExpression {
1421    ListSum
1422        .try_new_bound_expr(options, [input])
1423        .vortex_expect("list-sum expressions require a numeric list child")
1424}
1425
1426// ---- ListTransform ----
1427
1428/// Creates an expression that applies a lambda to every element of each list.
1429///
1430/// The lambda takes one parameter, the element.
1431///
1432/// ```rust
1433/// # use vortex_array::expr::{Lambda, checked_add, col, list_transform, lit, var};
1434/// let lambda = Lambda::new(["x"], checked_add(var("x"), lit(1_i32))).unwrap();
1435/// let expr = list_transform(col("l"), lambda);
1436/// assert_eq!(expr.to_string(), "vortex.list.transform($.l, (x) -> (@x + 1i32))");
1437/// ```
1438pub fn list_transform(list: Expression, lambda: Lambda) -> Expression {
1439    ListTransform.new_expr(ListTransformOptions::Lambda(lambda), [list])
1440}
1441
1442/// Reinterpret timestamp wall times in `options.time_zone`, preserving the time unit.
1443///
1444/// `ambiguous` is a UTF-8 expression containing `raise`, `earliest`, `latest`, or `null`.
1445/// Removing the timezone preserves wall time in a timezone-naive timestamp.
1446pub fn replace_time_zone(
1447    input: Expression,
1448    ambiguous: Expression,
1449    options: ReplaceTimeZoneOptions,
1450) -> Expression {
1451    ReplaceTimeZone.new_expr(options, [input, ambiguous])
1452}
1453
1454/// Create a bound timezone replacement expression.
1455pub fn bound_replace_time_zone(
1456    input: BoundExpression,
1457    ambiguous: BoundExpression,
1458    options: ReplaceTimeZoneOptions,
1459) -> BoundExpression {
1460    ReplaceTimeZone
1461        .try_new_bound_expr(options, [input, ambiguous])
1462        .vortex_expect("timezone replacement requires a timestamp and a UTF-8 ambiguity policy")
1463}
1464
1465/// Constructors for expressions whose children have already been bound and type-checked.
1466///
1467/// These mirror the constructors in [`crate::expr`] and panic when the supplied children do not
1468/// form a well-typed expression. Use [`BoundExpression::try_new`] when construction must be
1469/// fallible.
1470pub mod bound {
1471    pub use super::bound_and as and;
1472    pub use super::bound_and_collect as and_collect;
1473    pub use super::bound_between as between;
1474    pub use super::bound_binary as binary;
1475    pub use super::bound_byte_length as byte_length;
1476    pub use super::bound_case_when as case_when;
1477    pub use super::bound_case_when_no_else as case_when_no_else;
1478    pub use super::bound_cast as cast;
1479    pub use super::bound_checked_add as checked_add;
1480    pub use super::bound_col as col;
1481    pub use super::bound_dynamic as dynamic;
1482    pub use super::bound_dynamic_expression as dynamic_expression;
1483    pub use super::bound_dynamic_with_options as dynamic_with_options;
1484    pub use super::bound_eq as eq;
1485    pub use super::bound_ext_storage as ext_storage;
1486    pub use super::bound_fill_null as fill_null;
1487    pub use super::bound_get_item as get_item;
1488    pub use super::bound_gt as gt;
1489    pub use super::bound_gt_eq as gt_eq;
1490    pub use super::bound_ilike as ilike;
1491    pub use super::bound_in_list as in_list;
1492    pub use super::bound_is_nan as is_nan;
1493    pub use super::bound_is_not_null as is_not_null;
1494    pub use super::bound_is_null as is_null;
1495    pub use super::bound_like as like;
1496    pub use super::bound_list_contains as list_contains;
1497    pub use super::bound_list_length as list_length;
1498    pub use super::bound_list_sum as list_sum;
1499    pub use super::bound_list_sum_opts as list_sum_opts;
1500    pub use super::bound_lit as lit;
1501    pub use super::bound_lt as lt;
1502    pub use super::bound_lt_eq as lt_eq;
1503    pub use super::bound_mask as mask;
1504    pub use super::bound_merge as merge;
1505    pub use super::bound_merge_opts as merge_opts;
1506    pub use super::bound_nested_case_when as nested_case_when;
1507    pub use super::bound_not as not;
1508    pub use super::bound_not_eq as not_eq;
1509    pub use super::bound_not_ilike as not_ilike;
1510    pub use super::bound_not_like as not_like;
1511    pub use super::bound_or as or;
1512    pub use super::bound_or_collect as or_collect;
1513    pub use super::bound_pack as pack;
1514    pub use super::bound_replace_time_zone as replace_time_zone;
1515    pub use super::bound_root as root;
1516    pub use super::bound_select as select;
1517    pub use super::bound_select_exclude as select_exclude;
1518    pub use super::bound_variant_get as variant_get;
1519    pub use super::bound_zip_expr as zip_expr;
1520}